Dokumentation mit Nornir/Ansible: Inventar und Facts automatisch pflegen

Dokumentation mit Nornir/Ansible ist eine der pragmatischsten Methoden, um Netzwerk-Inventar und Device-Facts nicht nur einmalig zu erfassen, sondern dauerhaft aktuell zu halten. In vielen Teams entsteht Dokumentationsdrift, weil Veränderungen schneller passieren als manuelle Updates in Wiki, Excel oder Diagrammen. Genau hier setzen Automatisierungs-Frameworks an: Nornir (Python-basiert, flexibel, parallel) und Ansible (deklarativ, verbreitet, rollen- und playbookorientiert) können regelmäßig „Facts“ aus Geräten auslesen, normalisieren und in eine Source of Truth (z. B. NetBox oder eine CMDB) zurückschreiben – oder zumindest Abweichungen als Aufgaben/Tickets sichtbar machen. Der entscheidende Punkt ist dabei nicht das Tool, sondern das Betriebsmodell: Welche Daten gelten als „Fakten“ (aus der Realität messbar), welche als „Intent“ (architektonische Vorgabe), und welche Felder dürfen automatisch gepflegt werden, ohne dass Governance und Ownership verwässern? Dieser Artikel zeigt Best Practices, um Inventar und Facts mit Nornir/Ansible automatisiert zu pflegen: von Datenquellen und Normalisierung über robuste Runbooks/Jobs bis zu Qualitätschecks, Versionierung und Sicherheitsregeln.

Warum automatisierte Facts-Dokumentation im Netzwerkbetrieb so viel bringt

„Inventar“ ist mehr als eine Geräteliste. Für Betrieb, Security, Compliance und Troubleshooting zählt, ob Informationen schnell auffindbar und vertrauenswürdig sind: Welche Geräte gibt es? Wo stehen sie? Welche Rollen haben sie? Welche Interfaces sind aktiv? Welche IPs sind konfiguriert? Welche Routing-Sessions existieren? Welche Softwarestände laufen? Wenn diese Informationen unvollständig oder veraltet sind, steigt MTTR, Changes werden riskanter und Audits werden hektisch. Automatisiertes Fact-Collection reduziert diesen Schmerz, weil es die Daten an der Quelle abholt: am Gerät.

• Aktualität: regelmäßige Synchronisation statt „nach Gefühl“ aktualisieren
• Geschwindigkeit: schnelle Antworten im Incident („Welche Uplinks hat das Device?“, „Welche OS-Version?“)
• Standardisierung: gleiche Datenfelder über viele Standorte und Vendoren
• Nachvollziehbarkeit: Drift wird sichtbar (z. B. „Config weicht vom Standard ab“)

Fakten vs. Intent: Das wichtigste Architekturprinzip

Damit automatisierte Dokumentation nicht zur „nächsten Wahrheit“ neben der Wahrheit wird, müssen Sie Fakten und Intent trennen. Nornir/Ansible sind hervorragend darin, Fakten zu sammeln. Intent kommt typischerweise aus Architektur, Standards, Change-Records und Source-of-Truth-Modellen.

• Fakten: OS-Version, Seriennummer, Interface-Status, LLDP-Nachbarn, Management-IP, BGP-Neighbor-State
• Intent: Device Role (CORE/EDGE/LEAF), Ownership, Zonenmodell, zulässige SNMP/NTP/AAA-Standards, Naming-Konvention

Best Practice ist: Automation schreibt Faktenfelder automatisch, Intent-Felder nur kontrolliert (Review/Approval) oder gar nicht. So bleibt Ihre Governance stabil, während der Ist-Zustand automatisch aktuell wird.

Nornir und Ansible: Unterschiede, die in der Praxis zählen

Beide Werkzeuge können „Facts“ sammeln, aber sie passen zu unterschiedlichen Team- und Betriebsmodellen.

• Nornir: Python-Framework, sehr flexibel, gut für parallele Jobs, komplexe Normalisierung und eigene Logik. Einstieg: Nornir Dokumentation.
• Ansible: Playbook-basiert, starke Community, viele Netzwerkmodule, gut für standardisierte Abläufe. Einstieg: Ansible Dokumentation.

In vielen Teams koexistieren beide: Ansible für „standardisierte Betriebsaufgaben“ (z. B. Compliance-Checks, Baseline-Konfiguration), Nornir für „Datenpipelines“ und maßgeschneiderte Integrationen (z. B. NetBox-Updates, Graph-Modelle, komplexe Abgleiche).

Welche Facts sich wirklich lohnen: Minimaler, aber wertvoller Katalog

Der häufigste Fehler ist „wir sammeln alles“. Das erzeugt Datenmüll und erschwert Reviews. Besser ist ein minimaler Fact-Katalog, der operativ den größten Nutzen bringt.

Inventar- und Identitäts-Facts

• Hostname (kanonisch), Management-IP, Site/Location (falls ableitbar)
• Hersteller/Plattform, Modell, Seriennummer (wo zuverlässig)
• OS-Version/Build, Uptime (als Indikator, nicht als Asset-Feld)

Interface- und Link-Facts

• Interface-Liste (physisch/logisch), Admin/Oper Status, Speed
• Beschreibung (ifAlias/description) als Qualitätssignal, wenn Standards existieren
• LLDP-Nachbarn (Topologiehinweis) und Link-Flaps/Errors (für Troubleshooting)

IPAM-nahe Facts

• Interface-IPs (Loopbacks, SVIs, Transit), VRF-Zuordnung
• Default-Gateway/Next-Hop-Informationen (vorsichtig, je nach Plattform)

Control-Plane Facts

• BGP Neighbors (up/down, peer IP/ASN), OSPF/IS-IS Nachbarn (State)
• Optional: Policy-Indikatoren (z. B. Route-Map/Policy-Name), nicht das komplette Regelwerk

Inventar-Quelle: Woher kommen die Devices überhaupt?

Facts sammeln setzt ein verlässliches Inventar voraus. Genau hier entscheidet sich, ob Ihre Pipeline stabil wird. In der Praxis gibt es drei Muster, die sich bewährt haben:

• SoT-first: NetBox/CMDB ist führend; Nornir/Ansible ziehen Hosts und Variablen daraus.
• Automation-first: Inventar liegt in Git (YAML/JSON), Änderungen via Pull Request; SoT wird daraus befüllt.
• Hybrid: NetBox führt Stammdaten, Git führt Standards/Intents (z. B. NTP/DNS/AAA), Jobs prüfen und synchronisieren.

Für NetBox als technische SoT ist der API-Zugriff zentral; Einstieg: NetBox REST API. Wenn Sie Ansible nutzen, ist das NetBox-Inventory-Plugin ein gängiger Weg, um Hosts dynamisch zu laden.

Fact Collection in Ansible: Strukturiert, wiederholbar, teamfähig

In Ansible besteht ein typischer Fact-Workflow aus drei Teilen: (1) Host-Inventar und Variablen, (2) modulbasierte Abfragen (show commands, facts modules), (3) Normalisierung und Output (JSON, NetBox-Update, Report). In Multivendor-Umgebungen ist es entscheidend, Vendor-spezifische Facts auf ein neutrales Zielmodell zu mappen.

• Module statt Shell: Wo möglich, nutzen Sie Netzwerkmodule (z. B. für EOS/IOS/Junos), um strukturierte Daten zu erhalten.
• Role-Struktur: Fact-Collection als Role, die pro Device Role (EDGE/CORE) leicht angepasst werden kann.
• Idempotenz im Sinne der Doku: Der Job kann beliebig oft laufen und erzeugt denselben Output, solange sich nichts geändert hat.

Für die Praxis ist es hilfreich, Outputs nicht nur „zu speichern“, sondern direkt gegen Standards zu prüfen und Abweichungen in einem Report oder Ticketprozess sichtbar zu machen.

Fact Collection in Nornir: Pipeline-Denken und Normalisierung als Stärke

Nornir eignet sich besonders gut, wenn Sie Facts als Datenpipeline betrachten: sammeln, transformieren, matchen, validieren, schreiben. Durch Python haben Sie volle Freiheit für Normalisierung, Konfliktlogik und Integrationen (NetBox, CMDB, Graphdatenbanken, Slack/Email-Benachrichtigungen).

• Parallelität: große Inventare schneller abarbeiten, ohne dass Playbooks unübersichtlich werden.
• Plugin-Ökosystem: Treiber und Tasks lassen sich gut kombinieren (z. B. via NAPALM oder Netmiko je nach Plattform).
• Custom Validations: Plausibilitätschecks und Quality Gates lassen sich sehr gezielt implementieren.

Ein häufig genutzter Baustein für Multivendor-Facts ist NAPALM, weil es ein vereinheitlichtes Datenmodell über Vendoren hinweg anstrebt. Einstieg: NAPALM Dokumentation.

Normalisierung: Der Schritt, der aus Daten wirklich Dokumentation macht

Egal ob Ansible oder Nornir: Rohdaten sind selten direkt dokumentationstauglich. Normalisierung heißt, Vendor-Varianten zu vereinheitlichen und auf Ihr Zielmodell zu bringen. Typische Normalisierungen:

• Interface-Namen: Eth1/1 vs. Gi0/1 vs. xe-0/0/1 – für Menschen und Tools konsistent darstellen
• Statuswerte: up/up, administratively down, lowerlayerdown – auf ein gemeinsames Schema mappen
• Plattformtypen: IOS-XE vs. IOS-XR vs. NX-OS – als taxonomy festlegen
• Standort/Role: nicht aus der Config „raten“, sondern aus SoT übernehmen

Ohne Normalisierung entstehen zwei Probleme: (1) Reports sind nicht vergleichbar, (2) Visualisierungen werden unlesbar, weil gleiche Konzepte unterschiedlich heißen.

Updates in NetBox/CMDB: Schreibstrategie statt „alles pushen“

Automatisches Pflegen bedeutet nicht, alles automatisch zu überschreiben. Best Practice ist eine klare Schreibstrategie pro Feld. Ein bewährtes Modell:

• Auto-write: OS-Version, Seriennummer (wenn verlässlich), Interface-Existenz, LLDP-Nachbarn (als Observed), Management-IP
• Write-with-review: neue Prefixe/Interface-IPs, wenn sie nicht im SoT reserviert/erwartet sind
• Read-only: Device Name, Role, Ownership, Zonenlabels (Intent-Felder)

Praktisch funktioniert das am besten über zwei Outputs: (1) ein Report („drift found“), (2) ein kontrollierter Update-Job („apply approved changes“). So behalten Sie Governance und vermeiden, dass ein Parsing-Fehler plötzlich Ihre SoT beschädigt.

Qualitätschecks: Damit Facts nicht zur nächsten „Diagramm-Lüge“ werden

Automatisch gepflegte Fakten schaffen Vertrauen nur, wenn sie validiert werden. Setzen Sie daher Quality Gates ein, die typische Fehlerbilder auffangen.

• Orphan Detection: Device taucht in Jobs auf, aber nicht in SoT (oder umgekehrt)
• Naming Compliance: Hostnames entsprechen dem Schema (Site-Code, Rolle, Index)
• Plausible Neighbors: LLDP zeigt Nachbarn in falscher Site/Location → Flag statt „Wahrheit“
• IP-Plausibilität: Interface-IP liegt außerhalb erwarteter Prefixe/VRFs → Review
• Status-Drift: SoT „decommissioned“, Device antwortet aktiv → Task

Dokumentations-Outputs: Welche Artefakte aus Facts wirklich nützlich sind

Facts sind Rohstoff. Wert entsteht, wenn Sie daraus konkrete Dokumentationsartefakte erzeugen, die im Alltag genutzt werden. Beispiele:

• Inventar-Übersichten: pro Site/Role eine aktuelle Geräteliste mit OS-Version und Ownership
• Portmaps/Link-Maps: LLDP-basierte „wer hängt an wem“-Sichten, pro Site oder pro Rack
• Routing Health Views: BGP/IGP Neighbor State und Flap-Historie (für On-Call)
• Compliance Dashboards: NTP/DNS/AAA/SNMPv3 Standarderfüllung
• Change-Impact Reports: „Welche Devices/Links waren seit gestern verändert?“

Für Visualisierung lohnt sich oft ein „One Diagram per Question“-Ansatz: Ein View für Onboarding, ein View für Incident, ein View für Security Boundaries. Facts liefern die Daten, Ihre Views liefern den Fokus.

Operativer Betrieb: Jobs, Zeitpläne und Definition of Done

Die beste Automatisierung scheitert, wenn sie nicht in Prozesse eingebettet ist. Definieren Sie daher, wann welche Facts gesammelt werden und wie Updates in SoT/CMDB in Changes eingebunden sind.

• Nightly Inventory: einmal täglich OS-Version, Seriennummer, Interface-Existenz, LLDP Snapshot
• Frequent Health: alle 5–15 Minuten Interface/Neighbor States und kritische Session-States (wenn Telemetrie verfügbar)
• Change-triggered: nach Changes automatisch „post-check“ ausführen und Abweichungen melden

Wichtig ist eine Definition of Done: Ein Change gilt erst als abgeschlossen, wenn (1) SoT aktualisiert ist, (2) Fact-Job sauber durchläuft, (3) Drift-Report leer oder akzeptiert ist. Das koppelt Dokumentation an Realität.

Sicherheit: Automatisierung braucht privilegierte Zugriffe

Nornir/Ansible Jobs greifen auf Geräte zu – oft mit weitreichenden Rechten. Behandeln Sie Fact-Collection daher als Sicherheitskomponente.

• Least Privilege: Read-only Accounts, wo möglich; getrennte Accounts für Read vs. Change
• Secrets Management: keine Passwörter/Keys im Repo; Nutzung eines Secret Stores
• Management-Segmentierung: Automations-Runner in Management-Netz/VRF, klare ACLs
• Audit Trail: Logging, welche Jobs wann welche Geräte abgefragt haben
• Retention: Outputs (Facts/Reports) mit klarer Aufbewahrung, da sie Topologie- und Assetdetails enthalten

Typische Anti-Pattern und wie Sie sie vermeiden

• „Alles automatisch überschreiben“: führt zu beschädigter SoT; Lösung: Field Ownership, Review-Queue
• Keine Normalisierung: Reports sind wertlos; Lösung: neutrales Zielmodell
• Kein Inventaranker: Hosts „fliegen“ frei; Lösung: SoT-first Inventar (z. B. NetBox)
• Zu viele Facts: Datenmüll; Lösung: minimaler Fact-Katalog mit operativem Nutzen
• Keine Qualitätschecks: „automatische Diagramm-Lügen“; Lösung: Plausibilitätsregeln und Drift-Alerts
• Keine Prozesskopplung: Drift bleibt; Lösung: Definition of Done im Change-Prozess

Pragmatischer Start: In vier Schritten zu automatisch gepflegtem Inventar

• Schritt 1: Inventarquelle festlegen (SoT-first), Naming-Standard und Device Roles definieren
• Schritt 2: Minimal-Facts sammeln (OS-Version, Seriennummer, Interfaces, Management-IP, LLDP)
• Schritt 3: Normalisieren und Qualitätschecks einführen (Orphans, IP-Plausibilität, Neighbor-Plausibilität)
• Schritt 4: Controlled Updates in SoT (Auto-write + Review-Queue), Reports und Dashboards operationalisieren

Checkliste: Dokumentation mit Nornir/Ansible Inventar und Facts automatisch pflegen

• Das Hauptkeyword „Dokumentation mit Nornir/Ansible“ wird als Pipeline verstanden: sammeln, normalisieren, validieren, publizieren
• Inventarquelle ist definiert (SoT-first bevorzugt), inklusive stabiler Identifikatoren
• Ein minimaler Fact-Katalog ist festgelegt (Inventar, Interfaces, IPAM-nahe Daten, Control-Plane States)
• Normalisierung ist umgesetzt (Statuswerte, Interface-Namen, Plattformtaxonomie) für vendorübergreifende Konsistenz
• Schreibstrategie ist klar (Auto-write für Fakten, Review für kritische Felder, Intent-Felder read-only)
• Qualitätschecks verhindern Drift und „Doku-Lügen“ (Orphans, IP-/Neighbor-Plausibilität, Status-Drift)
• Outputs sind operativ nutzbar (Inventarübersichten, Portmaps, Routing-Health, Compliance-Reports)
• Jobs sind zeitlich sinnvoll geplant (nightly inventory, frequent health, change-triggered post-checks)
• Sicherheitsregeln sind umgesetzt (Least Privilege, Secrets Management, Management-Segmentierung, Audit Trail)
• Outbound-Links zeigen auf Primärquellen (Nornir: Dokumentation, Ansible: Dokumentation, NAPALM: Dokumentation, NetBox API: REST API)

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.