Diagram-as-Code: Mermaid, PlantUML und Graphviz im Netzwerk

Diagram-as-Code bringt Netzwerkteams aus der „Screenshot-Falle“: Statt schwer reviewbarer Visio- oder PNG-Dateien entstehen Diagramme als Text, versioniert in Git, prüfbar per CI und reproduzierbar gerendert. Für den Betrieb ist das ein echter Qualitätssprung. Änderungen an Topologie, Segmentierung, Security-Zonen oder Pfaden lassen sich wie Konfigurationsänderungen behandeln: mit Pull Requests, Diffs, Reviews und klarer Historie („was hat sich geändert und warum“). Gleichzeitig bleibt die Darstellung flexibel: Aus denselben Quellen erzeugen Sie SVGs für Wikis, PDFs für Audits und Previews für Merge Requests. In der Praxis haben sich drei Werkzeuge besonders etabliert, weil sie unterschiedliche Diagrammtypen abdecken: Mermaid für schnelle, gut lesbare Diagramme direkt in Markdown, PlantUML für strukturierte Architektur- und Sequenzdiagramme mit hoher Ausdruckskraft, und Graphviz (DOT) für komplexe Graphen, automatische Layouts und Infrastruktur-Graph-Visualisierungen. Dieser Artikel zeigt, wie Sie Diagram-as-Code im Netzwerkalltag einsetzen, welche Tool-Stärken wofür passen und welche Best Practices verhindern, dass aus „Code-Diagrammen“ neue Spaghetti-Pläne werden.

Warum Diagram-as-Code im Netzwerkbetrieb funktioniert

Netzwerkdiagramme scheitern selten an fehlenden Tools, sondern an drei betrieblichen Problemen: mangelnde Reviewbarkeit, Drift und fehlende Wiederholbarkeit. Diagram-as-Code adressiert genau diese Punkte.

• Reviewbarkeit: Textbasierte Diagramme lassen sich diffen. Reviewer sehen, ob ein Link, eine Zone oder ein Pfad hinzugefügt wurde – ohne Pixelvergleich.
• Versionierung: Git-Historie beantwortet „wann, wer, warum“. Das ist für Changes, Audits und Postmortems zentral.
• Automatisierung: CI kann Syntax prüfen, Diagramme rendern, Broken Links finden und Freshness-Regeln durchsetzen.
• Wiederverwendung: Templates (Branch, DC-Pod, Edge) werden instanziert statt jedes Mal neu gezeichnet.
• Portabilität: Diagramme sind unabhängig von einzelnen Desktop-Tools und lassen sich in vielen Umgebungen rendern.

„One Diagram per Question“ bleibt Pflicht, auch mit Code

Diagram-as-Code löst nicht automatisch die falsche Diagrammstrategie. Wenn ein Diagramm zehn Fragen gleichzeitig beantworten soll, wird es unlesbar – egal ob als PNG oder als DOT. Definieren Sie deshalb pro Diagramm eine Leitfrage und halten Sie den Scope eng.

• „Wie sieht die High-Level-Konnektivität zwischen Sites, DC und Cloud aus?“
• „Wo liegen Trust Boundaries und welche Kontrollpunkte erzwingen Segmentierung?“
• „Wie läuft der Pfad für Flow X (primär/backup, stateful Controls)?“
• „Wo kann ich mitschneiden (Capture Points) und welche Logs sind relevant?“

Aus einem Network Graph können Sie viele Views generieren. Aber Sie sollten sie bewusst kuratieren, statt „alles auf einmal“ zu rendern.

Mermaid im Netzwerk: Schnell, leichtgewichtig, ideal für Markdown

Mermaid ist besonders beliebt, weil es ohne zusätzliche Software in vielen Doku-Stacks funktioniert (z. B. GitHub/GitLab, viele Static-Site-Generatoren) und schnell zu „gut genug“ Ergebnissen führt. Für Netzwerkteams ist Mermaid ideal für Overview Maps, einfache Flow-Diagramme, Service Maps und Incident-Timelines.

Stärken von Mermaid

• Niedrige Einstiegshürde: Syntax ist relativ intuitiv; Diagramme passen direkt in Markdown.
• Gute Lesbarkeit: Für schnelle Onboarding- und Management-Views oft ausreichend.
• Viele Diagrammtypen: Flowcharts, Sequence, State, ER, Mindmaps – nützlich für Runbooks und Abhängigkeiten.

Grenzen von Mermaid

• Komplexe Topologien: Sehr große L2/L3-Topologien werden schnell unübersichtlich.
• Feingranulares Layout: Weniger Kontrolle als bei dedizierten Diagrammtools; automatische Layouts sind nicht immer optimal.
• Semantik: Symbole und „Netzwerk-Ikonografie“ sind begrenzt; arbeiten Sie stärker mit Containern und Labels.

Praktisch bewährt: Mermaid für „Explain the idea“ und PlantUML/Graphviz für „Model the system“.

PlantUML im Netzwerk: Architektur, Sequenzen, Zonen und Runbooks

PlantUML eignet sich hervorragend, wenn Sie Netzwerkarchitektur als wiederholbare Struktur beschreiben wollen: Zonen, Layered Views, Kontrollpunkte, aber auch Ablaufdiagramme (Sequence) für Troubleshooting und Incident-Dokumentation. PlantUML ist zudem stark, wenn Sie mit wiederverwendbaren Includes/Skins arbeiten möchten, um Teamstandards durchzusetzen.

Stärken von PlantUML

• Ausdrucksstarke Diagramme: Komponenten-/Deployment-/Sequence-Diagramme sind sehr geeignet für Architektur- und Betriebsdoku.
• Wiederverwendbarkeit: Gemeinsame Styles und Bausteine (z. B. „Firewall“, „SASE PoP“, „Transit Hub“) lassen sich standardisieren.
• Skalierbarkeit: Strukturierte Diagramme bleiben auch bei Wachstum beherrschbar, wenn Sie konsequent modularisieren.

Typische Netzwerk-Use-Cases

• Security-Zonen-Diagramme: Zonen als Container, Kontrollpunkte als Gate-Objekte, Flow-Kategorien als Pfeile.
• Incident-Sequenzen: „Client → DNS → Proxy → WAF → LB → App → DB“ inklusive Timeouts und Retries.
• Change-Runbooks: Schrittfolgen, Validierungen, Rollback als Ablaufdiagramme.

Ein praktischer Vorteil: PlantUML lässt sich sehr gut in CI rendern (Server oder lokale Runner), und damit werden Diagramme zu einem echten Build-Artefakt.

Graphviz im Netzwerk: DOT als Sprache für Infrastruktur-Graphen

Graphviz (DOT) ist das Werkzeug der Wahl, wenn Sie „Graphen“ wirklich als Graphen modellieren: viele Knoten, viele Kanten, automatische Layouts und programmatische Generierung. Für Network Graph Datenmodelle, LLDP-Topologien, BGP-Sessions oder Abhängigkeitsgraphen ist DOT sehr stark.

Stärken von Graphviz

• Automatisches Layout: Layout-Engines (z. B. dot, neato) sind für große Graphen gemacht.
• Programmatische Generierung: DOT lässt sich leicht aus Telemetrie, NetBox, CMDB oder Config-Parsing erzeugen.
• Skalierung: Bei vielen Knoten können Sie durch Clusters/Subgraphs Domänen sauber trennen (Sites, Pods, Zonen).

Grenzen von Graphviz

• Manuelle Feinkontrolle: Automatisches Layout ist hilfreich, aber nicht immer „präsentationsperfekt“.
• Lesbarkeit: Ohne Filter/Aggregation entstehen schnell Spaghetti-Graphen; kuratierte Views sind Pflicht.

Graphviz ist ideal, wenn Sie Diagramme als „Output“ eines Infrastructure Graphs verstehen: Daten rein, kuratierte Sicht raus.

Toolauswahl nach Diagrammtyp: Wer kann was am besten?

Ein häufiger Fehler ist, „ein Tool für alles“ erzwingen zu wollen. Besser ist eine einfache Zuordnung nach Use Case und Lesbarkeit.

• Onboarding & Overview: Mermaid (schnell, direkt in Markdown)
• Security-Zonen & Kontrollpunkte: PlantUML (strukturierte Container, wiederverwendbare Bausteine)
• Service Maps & Sequenzen: PlantUML Sequence (präzise Ablaufdarstellung)
• Große Topologien aus Datenquellen: Graphviz (automatisches Layout, Clusters)
• CI-Preview: alle drei, wenn Rendering automatisiert ist

Repo-Struktur und Standards: Damit Diagram-as-Code nicht chaotisch wird

Ohne Struktur wird ein Diagramm-Repo schnell unübersichtlich. Bewährt hat sich eine Trennung nach Domänen und eine klare Template-Strategie.

Empfohlene Struktur

• /docs: Dokumentationsseiten (Markdown/HTML), in denen Diagramme eingebettet oder verlinkt sind
• /diagrams/src: Quellen (Mermaid .mmd, PlantUML .puml, Graphviz .dot)
• /diagrams/out: gerenderte Artefakte (SVG/PNG/PDF), idealerweise CI-generiert
• /diagrams/templates: wiederverwendbare Bausteine (z. B. PlantUML includes, Mermaid Snippets)
• /schemas: Naming- und Metadatenregeln (Regex, Glossar, Lint-Konfiguration)

Namenskonventionen und Metadaten als Pflicht

• Scope: Site/Region/Umgebung (Prod/Non-Prod) muss im Dateinamen oder Header erkennbar sein.
• Owner: verantwortlich für Aktualität (Team oder Rolle).
• Last reviewed: Datum, optional mit Change-Referenz.
• Leitfrage: ein Satz, der erklärt, wofür das Diagramm gedacht ist.

CI-Rendering und Checks: Diagramme wie Code behandeln

Diagram-as-Code entfaltet den vollen Nutzen erst mit CI: Diagramme müssen syntaktisch valide sein, automatisch gerendert werden und als Preview verfügbar sein. CI kann außerdem verhindern, dass „Diagramm-Lügen“ durch Drift entstehen.

Was CI prüfen sollte

• Syntax: Mermaid/PlantUML/DOT müssen renderbar sein; Render-Fails blockieren den Merge.
• Broken Links: interne Links und externe Referenzen, mit sinnvollen Allowlists und Timeouts.
• Freshness: Diagramme ohne Review-Datum oder älter als definierte Schwellen werden markiert.
• Source-Pflicht: Keine „nackten PNGs“ ohne zugehörige Quelle (oder bewusst deklarierte Ausnahme).

Für CI-Implementierung sind die Plattformdokus hilfreich: GitHub Actions und GitLab CI/CD. Für Linkchecks hat sich Lychee etabliert.

Best Practices für Netzwerkdiagramme als Code

Damit Diagramme nicht nur existieren, sondern im Betrieb helfen, sollten Sie einige Regeln konsequent anwenden.

Layered Views statt Mischdiagramme

• Physisch (L1): Ports, Racks, Panels, Circuits – getrennt von logischen Sichten.
• Switching (L2): VLAN-Domänen, Trunks, MLAG/vPC – ohne Routingdetails.
• Routing (L3): VRFs, Areas, BGP Sessions, Summaries – ohne Patchpanel-Details.
• Security: Zonen, Boundaries, Kontrollpunkte – Flow-Kategorien statt Regelwüste.
• Service: Dependencies und Kommunikationspfade – anwendungsnah.

Labels kurz, Details verlinken

• Im Diagramm: Kurzlabels (VRF-PROD, Po10, eBGP, DMZ).
• Details: Links auf Source of Truth, Runbooks, Policy-Kataloge, Dashboards.

Stateful Controls markieren

• Firewalls/NAT/LBs als stateful kennzeichnen, um Asymmetrie-Risiken im Pfad sichtbar zu machen.
• Primär/Backup-Pfade mit Linienarten oder Labels unterscheiden.

Mermaid, PlantUML, Graphviz gemeinsam nutzen: Ein praxistauglicher Hybrid

In reifen Umgebungen nutzen Teams häufig mehrere Sprachen, aber mit klarer Rollenverteilung. Ein sinnvolles Hybridmodell:

• Mermaid für schnelle, lesbare Doku-Sichten direkt in Markdown (Onboarding, Overview, einfache Flows).
• PlantUML für strukturierte Architektur- und Ablaufdiagramme (Zonen, Sequenzen, Runbooks).
• Graphviz für datengetriebene Diagramme aus Telemetrie/SoT/Config-Parsing (Topologien, Abhängigkeitsgraphen).

Wichtig: Die Tools teilen sich Standards (Namenskonventionen, Legenden, Metadaten) und werden über CI einheitlich gerendert.

Integration mit Source of Truth und Telemetrie: Diagramme als Views, nicht als Stammdaten

Diagram-as-Code ist am stärksten, wenn Diagramme nicht versuchen, Stammdaten zu besitzen. Stattdessen verweisen sie auf führende Systeme (IPAM/DCIM/CMDB) und nutzen Telemetrie als Validierung. NetBox ist dafür häufig der technische Anker; Referenz: NetBox REST API. Für Flow- und Pfadmodelle ist IPFIX als Standard in RFC 7011 beschrieben. Modellgetriebene Telemetrie lässt sich gut über OpenConfig strukturieren.

• SoT hält Intent: Owner, Roles, Lifecycle, „was soll gelten“.
• Telemetrie liefert Observed Signals: Neighbor, States, Flows, Health.
• Diagramme visualisieren kuratierte Sichten: „One Diagram per Question“.

Typische Anti-Pattern bei Diagram-as-Code im Netzwerk

• Ein Tool für alles: führt zu Kompromissen; Lösung: Tool nach Diagrammtyp wählen.
• Nur gerenderte Bilder: keine Diffs, kein Review; Lösung: Quellen versionieren, CI rendert Outputs.
• Keine Leitfrage: Diagramme wachsen unkontrolliert; Lösung: Scope erzwingen, Layer trennen.
• Keine Metadaten: niemand vertraut; Lösung: Owner/Last reviewed/Scope verpflichtend.
• Automatisches „Alles plotten“: Spaghetti aus Graphviz; Lösung: Filter, Aggregation, kuratierte Views.
• Copy-Paste-Stammdaten: Drift; Lösung: SoT verlinken, nicht replizieren.

Checkliste: Diagram-as-Code mit Mermaid, PlantUML und Graphviz erfolgreich einführen

• Hauptkeyword „Diagram-as-Code“ ist als Prozess definiert: Quellen in Git, Reviews, CI-Rendering, reproduzierbare Artefakte
• Toolauswahl ist use-case-getrieben: Mermaid für schnelle Markdown-Views, PlantUML für Architektur/Sequenzen, Graphviz für datengetriebene Graphen
• „One Diagram per Question“ ist Standard, Layered Views verhindern Mischdiagramme
• Repo-Struktur trennt Quellen und Outputs; Templates/Includes erzwingen Teamstandards
• CI prüft Syntax, rendert Diagramme, erzeugt Previews und findet Broken Links (z. B. mit Lychee)
• Metadaten sind Pflicht (Owner, Scope, Last reviewed), Freshness-Regeln verhindern veraltete Diagramme
• Diagramme verlinken auf Source of Truth und Evidence (NetBox API, Runbooks, Dashboards) statt Stammdaten zu kopieren
• Overlays/ECMP/stateful Controls werden korrekt modelliert und nicht „wegabstrahiert“
• Security ist berücksichtigt: Diagramm- und CI-Pipelines leaken keine Secrets, Zugriffe sind least-privilege
• Outbound-Links zeigen auf Primärquellen: Mermaid, PlantUML, Graphviz, GitHub Actions, GitLab CI/CD

Cisco Netzwerkdesign, CCNA Support & Packet Tracer Projekte

Cisco Networking • CCNA • Packet Tracer • Network Configuration

Ich biete professionelle Unterstützung im Bereich Cisco Computer Networking, einschließlich CCNA-relevanter Konfigurationen, Netzwerkdesign und komplexer Packet-Tracer-Projekte. Die Lösungen werden praxisnah, strukturiert und nach aktuellen Netzwerkstandards umgesetzt.

Diese Dienstleistung eignet sich für Unternehmen, IT-Teams, Studierende sowie angehende CCNA-Kandidaten, die fundierte Netzwerkstrukturen planen oder bestehende Infrastrukturen optimieren möchten. Finden Sie mich auf Fiverr.

Leistungsumfang:

• Netzwerkdesign & Topologie-Planung

• Router- & Switch-Konfiguration (Cisco IOS)

• VLAN, Inter-VLAN Routing

• OSPF, RIP, EIGRP (Grundlagen & Implementierung)

• NAT, ACL, DHCP, DNS-Konfiguration

• Troubleshooting & Netzwerkoptimierung

• Packet Tracer Projektentwicklung & Dokumentation

• CCNA Lern- & Praxisunterstützung

Lieferumfang:

• Konfigurationsdateien

• Packet-Tracer-Dateien (.pkt)

• Netzwerkdokumentation

• Schritt-für-Schritt-Erklärungen (auf Wunsch)

Arbeitsweise:Strukturiert • Praxisorientiert • Zuverlässig • Technisch fundiert

CTA:
Benötigen Sie professionelle Unterstützung im Cisco Networking oder für ein CCNA-Projekt?
Kontaktieren Sie mich gerne für eine Projektanfrage oder ein unverbindliches Gespräch. Finden Sie mich auf Fiverr.