Dokumentation für Topologien ist in Telco- und Provider-Netzen kein „Nice-to-have“, sondern ein Sicherheits- und Betriebsfaktor. Carrier-Grade Netze sind groß, redundant, multi-vendor und verändern sich ständig: neue PoPs, neue Wellen im FTTH-Ausbau, neue Peering-Partner, neue SR-Policies, neue DDoS-Mechanismen. Wenn Dokumentation dabei nur aus gelegentlichen PowerPoint-Diagrammen besteht, entsteht Drift – und Drift ist einer der größten Treiber für Incidents, lange MTTR und teure Fehlentscheidungen. Gute Topologie-Dokumentation schafft dagegen etwas, das in Telcos extrem wertvoll ist: gemeinsame, überprüfbare Realität. Dazu gehören zwei Bausteine, die sich perfekt ergänzen: standardisierte Diagramme (damit jeder im NOC, Engineering und Management dasselbe sieht und versteht) und ADRs (Architecture Decision Records), die erklären, warum eine Topologie so gebaut wurde und welche Alternativen bewusst verworfen wurden. Diagramm-Standards sorgen für Lesbarkeit und Vergleichbarkeit über Regionen hinweg; ADRs sorgen dafür, dass Entscheidungen auditierbar sind, nicht „historisch“ werden und später nicht versehentlich gebrochen werden. Dieser Artikel zeigt praxisnahe Standards für Telco-Topologie-Dokumentation: Welche Diagrammtypen Sie pro Layer brauchen (L1/L2/L3/Services/Ops), wie Sie Naming, Farben, Labels und Symbole standardisieren, wie Sie ADRs schlank und wirksam einsetzen, und wie Sie eine Source-of-Truth-Strategie etablieren, damit Diagramme und Entscheidungen nicht veralten, sondern Teil eines wiederholbaren Carrier-Grade Prozesses werden.
Warum Telcos spezielle Dokumentationsstandards brauchen
In Enterprise-Netzen ist Dokumentation oft schon schwierig – in Telcos ist sie kritisch. Die Gründe sind strukturell: viele Failure Domains, viele Stakeholder, viele Wechselwirkungen zwischen Topologie, Routing-Policies und Services. Die Dokumentation muss deshalb drei Dinge gleichzeitig leisten: sie muss schnell verständlich sein (für Betrieb), technisch präzise (für Engineering) und historisch nachvollziehbar (für Governance, Audit, Migrationen).
- Skalierung: Hunderte bis Tausende Sites/Links lassen sich nur mit Standards konsistent dokumentieren.
- Redundanz: „Dual-Homing“ ohne SRLG-Information ist gefährlich; L1 muss mitdenken.
- Multi-Domain: Core, Metro, Access, Internet Edge, DCI, Services – jede Domäne hat andere Leser.
- Change-Tempo: Ausbauwellen und Rolling Upgrades erzeugen permanente Änderungen, Dokumentation muss mithalten.
Leitprinzip: Diagramme erklären „was“, ADRs erklären „warum“
Ein Diagramm zeigt die Struktur. Ein ADR zeigt die Entscheidung und ihre Grenzen. Ohne ADRs werden Diagramme zu Momentaufnahmen ohne Kontext – und damit riskant.
Grundmodell: Dokumentation nach Layern trennen
Ein häufiger Fehler ist „ein großes Diagramm für alles“. Das ist selten lesbar und wird schnell falsch interpretiert. Carrier-Grade Dokumentation trennt konsequent nach Layern und bindet die Layer über stabile IDs zusammen. So kann ein Incident-Responder vom Service zum Pfad zum Link zum Circuit drill-downen, ohne in einem Schaubild zu ertrinken.
- L1 (Physical): Circuits, Trassen/SRLG, Facilities, Cross-Connects, Optik/Wellenlängen, Port-to-Port.
- L2 (Switching): VLAN/QinQ, LAG/MLAG, Ring-Protection, EVPN/L2VPN-Domänen, Broadcast-Grenzen.
- L3 (Routing): IGP-Domänen, BGP-Hierarchien, SRGB/SIDs, Summarization, ECMP/TE.
- Services: VRFs, L3VPN/L2VPN Blueprints, Internet Edge Policies, CGNAT/BNG, Anycast, DDoS.
- Ops/Management: OOB/In-Band, Jump-Zones, Telemetry-Pfade, Logging, SLO-Messpunkte.
Designregel: Ein Diagramm pro Frage
Wenn das Diagramm zwei Zielgruppen mit unterschiedlichen Fragen bedienen soll, ist es meist zu groß. Besser sind mehrere kleine, standardisierte Diagramme mit klarer Referenzierung.
Diagramm-Standards: Naming, IDs und Konsistenzregeln
Standards beginnen bei Namen. In Telcos sind Namen nicht nur „Labels“, sondern Verknüpfungspunkte für Automatisierung, Monitoring und Troubleshooting. Ein Diagramm ist nur dann zuverlässig, wenn Device- und Linknamen eindeutig, konsistent und mit der Source of Truth kompatibel sind.
- Device Naming: Region-PoP-Rolle-Index (z. B. DE-FRA-CORE01, DE-FRA-EDGE02, DE-BER-AGG03).
- Site IDs: Stabile Site-ID (nicht nur „Frankfurt“), die sich in Systemen wiederfindet.
- Link/Circuit IDs: Circuit-ID als Pflicht, plus Linkklasse (CORE, DCI, IXP, ACCESS, BACKHAUL).
- Service IDs: VRF-ID, VPN-ID, Customer-ID – damit Servicepfade eindeutig referenzierbar sind.
Anti-Pattern: „R1/R2“ in Telco-Diagrammen
Abstrakte Namen sind im Lab okay, in Produktion gefährlich. Ein Standard muss erzwingen, dass Diagramme direkt auf reale IDs referenzieren.
Visuelle Sprache: Symbole, Farben und Linienarten standardisieren
Telco-Diagramme werden von unterschiedlichen Teams genutzt. Deshalb braucht es eine klare visuelle Sprache, die über alle Dokumente konsistent ist. Wichtig: Farben dürfen nicht die einzige Informationsquelle sein (Barrierefreiheit), und die Bedeutung muss in einer Legende oder einem Standarddokument festgeschrieben sein.
- Rollen-Symbole: Unterschiedliche Shapes für Core, Edge, Aggregation, Access, RR, Security/DDoS.
- Linienarten: Durchgezogen = aktiv, gestrichelt = Standby/Backup, gepunktet = Management/Telemetry.
- Linkklassen-Farben: z. B. Core/Backbone, Metro, DCI, IXP/Transit, Access/Backhaul – konsistent in allen Diagrammen.
- Failure Domains: Umrandungen oder „Domains“ für PoP, Region, Ring-ID, SRLG-Zonen, Maintenance Domains.
Designregel: Jede visuelle Bedeutung muss textlich erklärbar sein
Wenn jemand die Aussage eines Diagramms nicht ohne Farben reproduzieren kann, ist der Standard zu schwach. Nutzen Sie Labels, Line Styles und Legenden.
Welche Diagrammtypen Telcos wirklich brauchen
Statt unzählige freie Diagramme zu pflegen, sind wenige, standardisierte Typen effizienter. Diese Typen decken die meisten Fragen ab: „Wie ist es physisch verbunden?“, „Wie wird geroutet?“, „Wie laufen Services?“, „Was passiert im Failover?“, „Wie betreiben wir es?“
- Physical Connectivity Map (L1): Circuits, SRLG, Facilities, Cross-Connects, diverse Paths.
- Logical Topology (L3): IGP-Domänen, BGP/RR-Hierarchie, SR/SIDs, ECMP/TE.
- Service Path Diagram: VRF/Service Chain (BNG/CGNAT/Firewall/DDoS), Normal- und Failoverpfade.
- Interconnect/Peering Map: IXPs, PNIs, Transit, Policy-Grenzen, DDoS-Steering-Pfade.
- Ops View: Management-Netze, Jump-Zones, Telemetry/Logging-Pfade, SLO-Probes und Dashboards.
Anti-Pattern: Das „Konzernübersichtsdiagramm“
Ein Weltkarten-Diagramm kann für Management nützlich sein, aber es ersetzt keine Engineering-Diagramme. Telco-Standards sollten Übersichten und detailreiche Views getrennt behandeln.
ADRs für Telcos: Warum Architekturentscheidungen dokumentiert werden müssen
ADRs (Architecture Decision Records) sind kurze Dokumente, die eine Architekturentscheidung festhalten: Kontext, Entscheidung, Alternativen, Konsequenzen. Für Telcos sind ADRs besonders wertvoll, weil Topologieentscheidungen Jahre wirken und später von anderen Teams weiterentwickelt werden. Ohne ADRs wird die Entscheidung „vergessen“, und neue Changes brechen unbewusst Grundannahmen (z. B. warum ein Ring nicht als Mesh gebaut wurde, warum SRGB so gewählt wurde, warum BNG zentral platziert ist).
- Auditierbarkeit: Warum wurde ein Design gewählt? Wer hat entschieden? Welche Risiken wurden akzeptiert?
- Wiederverwendbarkeit: Blueprints werden konsistent, weil Entscheidungen nachvollziehbar sind.
- Change-Sicherheit: ADRs definieren Guardrails: „Wenn X, dann muss Y geprüft werden“.
- Wissenstransfer: Teams wechseln, die Architektur bleibt. ADRs verhindern Wissensverlust.
Leitprinzip: ADRs sind kurz, aber verbindlich
Ein ADR soll nicht alle Details enthalten. Er soll die Entscheidung und ihre Grenzen so klar festhalten, dass spätere Änderungen sicher bewertet werden können.
ADR-Template: Minimal, aber vollständig
Ein Telco-ADR sollte schlank sein, aber die entscheidenden Punkte enthalten. Besonders wichtig ist die explizite Nennung von Failure Domains, Betriebsfolgen und Messkriterien (Design KPIs), damit ADRs nicht zu „Meinungsprotokollen“ werden.
- Kontext: Problem, Scope (Region/PoP/Domäne), Anforderungen/SLOs, Constraints.
- Entscheidung: Was wird gebaut? (z. B. „Metro als L3-Ring mit Dual-Hub“, „SR-MPLS mit TI-LFA“)
- Alternativen: Welche Optionen wurden geprüft (Ring vs. Mesh, LDP vs. SR, zentral vs. regional)? Warum verworfen?
- Konsequenzen: Trade-offs, Risiken, Migration/Interop, Betriebsaufwand.
- Guardrails: Pflichtchecks (Max-Prefix, MTU, QoS, SRLG, CoPP), Tests (Lab/Intent Validation).
- KPIs: Zielwerte für Konvergenz, Availability, Headroom, Change-Failure-Rate.
Anti-Pattern: ADR ohne „Consequences“
Wenn ein ADR keine Konsequenzen enthält, ist es nur eine Entscheidung ohne Verantwortung. Telco-ADRs müssen Trade-offs explizit machen.
ADRs und Diagramme verknüpfen: Die „Bidirektionale“ Dokumentation
Diagramme ohne ADRs sind kontextlos. ADRs ohne Diagramme sind abstrakt. Die beste Praxis ist eine bidirektionale Verknüpfung: Jedes Diagramm referenziert die relevanten ADRs („warum so“), und jedes ADR referenziert die relevanten Diagramme („wie umgesetzt“). Dadurch entstehen stabile Blueprints.
- Diagramm → ADR: In der Legende oder im Info-Panel: „Designentscheidung: ADR-XYZ“.
- ADR → Diagramm: Verweis auf konkrete L1/L3/Service-Diagramme und auf SoT-Objekte (IDs).
- Versionierung: Diagramme und ADRs gemeinsam versionieren, idealerweise im selben Repo/Prozess.
- Änderungsregeln: „Wenn Diagramm geändert, ADR prüfen“ und umgekehrt.
Designregel: Jede große Topologieänderung braucht ein ADR
Wenn eine Änderung die Failure Domains, Routing-Hierarchie oder Servicepfade verändert, muss die Entscheidung dokumentiert werden – sonst entsteht Drift und spätere Reviews werden unsicher.
Source of Truth und „Docs as Code“: Veralten verhindern
Die beste Dokumentation ist wertlos, wenn sie veraltet. Telcos brauchen deshalb einen Mechanismus, der Drift minimiert: eine Source of Truth (NetBox/CMDB oder vergleichbar) und einen „Docs as Code“-Ansatz, bei dem Dokumente versioniert, reviewt und automatisiert geprüft werden. Das Ziel ist nicht, alles zu automatisieren, sondern kritische Konsistenzregeln zu erzwingen.
- SoT Ownership: Welche Daten werden wo gepflegt (Links, Geräte, SRLG, VRFs, Peerings)?
- Automatische Checks: Naming-Konventionen, Pflichtfelder, SRLG-Attribute, Linkklassen.
- Diagramm-Generierung: Wo möglich aus SoT ableiten (oder zumindest mit SoT abgleichen).
- Review Workflow: Pull-Request-ähnliche Reviews für Diagramme und ADRs, inklusive Gate-Checkliste.
Anti-Pattern: Wiki als einzige Wahrheit
Wikis sind gut für Erklärtexte, aber schlecht als Datenquelle. Telco-Topologie braucht strukturierte Daten als Grundlage und Texte/ADRs als Kontext.
Diagrammqualität in Reviews: Checkliste für „diagrammreife“ Artefakte
Damit Diagramme im Review wirklich helfen, sollten sie Qualitätskriterien erfüllen. Diese Kriterien sind unabhängig vom Tool (Visio, draw.io, Lucidchart, Graphviz) und können als Standard in Ihrem Reviewprozess verankert werden.
- Lesbarkeit: Maximal eine primäre Aussage pro Diagramm, klare Legende, klare Scopes.
- Vollständigkeit: Alle kritischen Links/Nodes vorhanden, Linkklassen und Rollen markiert.
- Failure Domains sichtbar: PoP/Region/Ring/DCI/Maintenance Domains eingezeichnet.
- IDs vorhanden: Site-ID, Device-ID, Circuit-ID, VRF/Service-ID.
- Normal- und Failoverpfad: Für kritische Services mindestens als zweite View oder Layer.
Designregel: Ein Diagramm muss „incident-tauglich“ sein
Wenn ein Diagramm im Incident nicht hilft, Pfade und Blast Radius schnell zu verstehen, ist es für Telco-Betrieb unzureichend.
ADRs in der Praxis: Häufige Telco-Entscheidungen, die ein ADR verdienen
- Topologiepattern: Ring vs. Mesh vs. Hub-and-Spoke in Metro/Backhaul.
- Core-Architektur: Dual-Core vs. Multi-Core, SR-MPLS vs. SRv6, FRR/TI-LFA Strategy.
- BGP/RR Design: RR-Hierarchie und Placement, Failure Domain Trennung, Guardrails.
- Internet Edge: Peering/Transit Strategie, DDoS Scrubbing Placement und Steering.
- Access/BNG: BNG Placement (zentral/regional), IPv6 PD Design, CGNAT Strategie.
- Observability: Telemetry-Pipeline, Sampling-Strategie, SLO-Messpunkte.
Praktische Leitlinien: Diagramm-Standards und ADRs als Telco-Standardprozess
- Layer trennen: L1/L2/L3/Services/Ops als feste Dokumenttypen, verbunden über stabile IDs.
- Visuelle Sprache standardisieren: Rollen-Symbole, Linkklassen, Linienarten, Failure Domains und Legenden verbindlich machen.
- Naming erzwingen: Region-PoP-Rolle-Index für Geräte, Circuit-ID für Links, VRF/Service-IDs für Dienste.
- ADRs verpflichtend nutzen: Jede große Topologie-/Policy-Entscheidung bekommt ein ADR mit Kontext, Alternativen, Konsequenzen und KPIs.
- Bidirektional verlinken: Diagramme verweisen auf ADRs, ADRs verweisen auf Diagramme und SoT-Objekte.
- Source of Truth etablieren: Strukturierte Daten als Basis, Dokumente als Kontext; Drift-Checks automatisieren.
- Docs as Code: Versionierung, Review-Workflows, Gate-Checkliste für Diagrammqualität und ADR-Qualität.
- Evidence-by-Design: ADRs enthalten Guardrails und Testnachweise (Lab, Intent Validation, Failure Workshops).
- Incident-Fitness prüfen: Diagramme müssen Normal- und Failoverpfade erklären und Blast Radius sichtbar machen.
- Kontinuierlich verbessern: Nach Incidents und Migrationen Standards nachschärfen, statt ad hoc Diagramme zu ergänzen.
