NetBox und Git: IT-Dokumentation, die mit der Umgebung Schritt hält

Die meisten IT-Dokumentationen sind am Tag ihrer Abgabe richtig und danach jeden Tag ein bisschen falscher. Eine VM kommt hinzu, eine IP-Adresse wird umgezogen, ein Kabel steckt jetzt in einem anderen Port. Niemand trägt es nach, weil das Nachtragen Arbeit ist, die keiner sieht. Im September 2026 haben wir unsere eigene IT-Dokumentation deshalb umgebaut: Sie entsteht jetzt so weit wie möglich aus der Umgebung selbst. Hier beschreiben wir, wie NetBox und Git dabei zusammenarbeiten.

Zwei Werkzeuge, zwei Fragen

Git beantwortet: Wie ist es gebaut, und wer hat was geändert? Im Repository liegen der Code für Terraform und Ansible, die Betriebsdokumentation und jede Änderung mit Begründung und Freigabe. Was im Git steht, hat eine Geschichte.

NetBox beantwortet: Was gibt es, und wo ist es? Geräte, virtuelle Maschinen, IP-Adressen, VLANs, Verkabelung, dazu Zweck und Verantwortliche eines Systems. NetBox ist eine verbreitete Open-Source-Anwendung für genau diese Bestandsdaten, mit Oberfläche, Suche und einer Schnittstelle für Skripte.

Beides zusammen ersetzt die Excel-Liste, den Netzplan als PDF und das Wissen im Kopf einzelner Kollegen. Wichtig ist die Richtung: Nach Möglichkeit fließen die Daten aus der Umgebung in die Dokumentation, nicht umgekehrt aus dem Gedächtnis.

Woher die Daten kommen

Eine leere NetBox von Hand zu füllen wäre genau die Arbeit, die vorher schon niemand gemacht hat. Deshalb liest bei uns ein Skript die Daten aus den Quellen, die ohnehin stimmen müssen:

Quelle	Was daraus in NetBox landet
Proxmox	virtuelle Maschinen und Container mit CPU, RAM, Festplatte, Netzwerkkarten
Switches (LLDP)	welches Gerät an welchem Port hängt
Firewall	Schnittstellen, VLANs, IP-Adressen im Netz
Terraform-Code	VM-Größen und DNS-Einträge
Ansible-Code	welche Dienste auf welchem System laufen

Das Skript ist idempotent: Ein zweiter Lauf ändert nur, was sich tatsächlich geändert hat, und legt keine doppelten Einträge an. Es liegt selbst im Git, wird mit Ansible ausgerollt und läuft bei jedem Deploy von NetBox mit.

Unsicheres sichtbar machen

Nicht jede Information ist eindeutig. Manche IP-Adresse ist nur aus einer Konfigurationsdatei abgeleitet, manche Verkabelung nur vermutet, weil das Gerät am anderen Ende kein LLDP spricht. Statt solche Einträge wegzulassen oder als sicher auszugeben, bekommen sie in NetBox eine eigene Markierung: „zu prüfen“.

Das klingt nach einem Detail, ist aber der wichtigste Teil. Eine Dokumentation, bei der man nicht weiß, welche Einträge stimmen, ist kaum besser als keine. Mit der Markierung sieht jeder auf einen Blick, worauf er sich verlassen kann und was noch jemand vor Ort ansehen muss. Die Liste der markierten Einträge ist zugleich die Arbeitsliste für die nächsten Wochen.

Der Netzplan entsteht aus den Daten

Aus NetBox erzeugt ein zweites Skript die Netzpläne: physische Verkabelung, Cluster mit ihren virtuellen Maschinen, die Datenflüsse des Monitorings. Die Diagramme landen als Mermaid- und Graphviz-Dateien im Git, zusammen mit einer interaktiven Ansicht zum Zoomen.

Oben in jeder erzeugten Datei steht: nicht von Hand bearbeiten, und der Befehl, mit dem man sie neu erzeugt. Wer den Netzplan ändern will, ändert die Daten. Damit gibt es keinen zweiten Netzplan mehr, der langsam vom ersten abweicht.

Fertige NetBox-Erweiterungen für Netzpläne haben wir auch geprüft. Die verbreiteten liefen zum Zeitpunkt der Einführung nicht mit der aktuellen NetBox-Version, eine war seit Jahren nicht mehr gepflegt. Ein eigenes Skript mit wenigen hundert Zeilen war die robustere Wahl.

NetBox als Inventar für Ansible

Wenn NetBox weiß, welche Systeme es gibt, kann Ansible diese Liste direkt nutzen. Das dynamische Inventar bildet Gruppen aus den NetBox-Daten: alle Hypervisoren, alle Systeme eines Kunden, alle Linux-Server, alle eingeschalteten Systeme. Ein Befehl für „alle aktiven Linux-Server eines Kunden“ braucht dann keine gepflegte Liste mehr, sondern nur die Schnittmenge zweier Gruppen.

Wir nutzen dieses Inventar bewusst nur, wenn wir es beim Aufruf ausdrücklich angeben. Die regulären Abläufe arbeiten weiter mit dem Inventar im Repository. So kann ein fehlerhafter Eintrag in NetBox nicht unbemerkt bestimmen, auf welchen Servern ein Playbook läuft.

Was beim Abgleich schiefging

Drei Fehler, die wir beim Aufbau gemacht haben und die bei jedem ähnlichen Projekt lauern:

1. Jeder Lauf änderte alles. NetBox liefert manche Zahlen als Text mit Nachkommastellen zurück, etwa „4.00“ statt 4. Das Skript hielt das für eine Abweichung und schrieb bei jedem Lauf alle virtuellen Maschinen neu. Technisch harmlos, aber das Änderungsprotokoll von NetBox war damit wertlos: Wenn alles geändert ist, sieht man die eine echte Änderung nicht mehr. Seitdem vergleicht das Skript Zahlen als Zahlen.

2. Zwei Quellen überschrieben sich gegenseitig. Jede Quelle markiert ihre Einträge mit einer Herkunft. Die erste Version setzte beim Aktualisieren alle Markierungen neu und löschte dabei die der anderen Quelle. Die zweite Quelle setzte sie beim nächsten Lauf wieder, und so weiter. Markierungen werden seitdem nur ergänzt, nie ersetzt.

3. Was man nicht misst, sieht man nicht. Die Switches erkennen ihre Nachbarn über LLDP. Auf unseren Proxmox-Servern lief der dafür nötige Dienst anfangs nicht, also fehlten deren Kabel im Netzplan, obwohl sie physisch steckten. Erst als wir ihn per Ansible auf allen Servern eingerichtet hatten, tauchten die fehlenden Verbindungen auf.

Was nicht automatisch geht

Ehrlich gesagt bleibt Handarbeit:

Zweck und Verantwortliche. Wofür ein System da ist und wen man anruft, wenn es ausfällt, weiß keine Schnittstelle.
Geräte ohne Schnittstelle. Ältere Switches, Drucker oder Geräte, die kein LLDP sprechen, tragen wir von Hand ein.
Rack-Positionen. Welcher Server in welcher Höheneinheit steckt, muss jemand vor Ort aufschreiben.
Passwörter. Die gehören nicht in NetBox, sondern in eine Passwortverwaltung.

Auch der Abgleich selbst ist noch nicht vollständig automatisch. Heute stoßen wir ihn nach Änderungen an der Umgebung an. Ein fester Zeitplan, der ihn regelmäßig ohne unser Zutun laufen lässt, steht auf unserer Liste.

Lohnt sich das?

Für eine Handvoll Geräte reicht eine gepflegte Liste. Sobald mehrere Cluster, viele VLANs oder mehrere Kunden im Spiel sind, zahlt sich der Aufbau aus, spätestens beim ersten Audit, beim ersten Dienstleisterwechsel oder bei der ersten Störung nachts um drei, in der niemand weiß, an welchem Port der ausgefallene Server hängt.

Der größte Gewinn ist aber ein anderer: Die Dokumentation hört auf, eine Aufgabe zu sein, die man aufschiebt. Sie wird ein Nebenprodukt des Betriebs.

Wie wir NetBox für Kunden aufbauen und welche Daten sich bei Ihnen automatisch erfassen lassen, steht unter IT-Dokumentation mit NetBox. Wie Terraform und Ansible die Umgebung beschreiben, aus der NetBox seine Daten holt, zeigt der Beitrag Terraform und Ansible: Wer konfiguriert was?.