NetBox als Quelle der Wahrheit: Netz und Geräte dokumentieren, Ansible daraus füttern

NetBox ist eine Open-Source-Anwendung, in der Du Standorte, Racks, Geräte, virtuelle Maschinen, Adressbereiche, IP-Adressen und VLANs an einer Stelle pflegst. Quelle der Wahrheit heißt: Was in NetBox steht, gilt, und alle Werkzeuge lesen von dort. Ansible holt sich sein Inventar mit dem Plugin netbox.netbox.nb_inventory direkt aus NetBox. Eine neue VM in NetBox steht damit beim nächsten Lauf auch im Inventar.

01Warum eine Quelle statt vieler Tabellen

Ohne NetBox liegt das Wissen über ein Netz verstreut: eine Tabelle mit IP-Adressen, eine Serverliste im Wiki, ein Inventar in Ansible und Notizen im Kopf eines Kollegen. Jede dieser Kopien veraltet für sich. Nach ein paar Monaten weiß niemand mehr, welche stimmt.

Mit einer einzigen Quelle ändert sich das:

• Eine Stelle zum Pflegen: Eine neue Adresse wird einmal eingetragen und ist danach überall bekannt.
• Regeln, die NetBox selbst prüft: Doppelte IP-Adressen und doppelte Adressbereiche lehnt NetBox in der Grundeinstellung ab, solange sie keinem VRF zugeordnet sind.
• Automatisierung liest mit: Ansible, Überwachung und Skripte holen ihre Daten über die API. Niemand tippt Listen ab.

NetBox beschreibt den Soll-Zustand. Es fragt keine Geräte ab und findet nichts von allein. Du trägst ein, wie das Netz aussehen soll, und die Automatisierung sorgt dafür, dass es so aussieht.

02Das Datenmodell in Kürze

In der API und in der Dokumentation heißen die Objekte englisch, deshalb stehen hier die englischen Namen.

• Abhängigkeiten: Ein Gerät braucht einen Standort, einen Gerätetyp und eine Rolle. Ein Gerätetyp braucht einen Hersteller. Eine VM braucht mindestens einen Standort, einen Cluster oder ein Gerät.
• Adressen hängen an Schnittstellen: Eine IP-Adresse wird einer Schnittstelle eines Geräts oder einer VM zugeordnet. Erst danach kannst Du sie als primäre IP festlegen. Diese primäre IP nutzt Ansible später, um den Host zu erreichen.

03Reihenfolge beim Erfassen

Wer mit den VMs anfängt, stößt überall auf fehlende Pflichtfelder. Arbeite von außen nach innen:

1. Standort: eine Site für Dein Labor.
2. Stammdaten: Hersteller, Gerätetypen und Rollen, etwa server, router und switch.
3. Geräte: zum Beispiel Deinen Proxmox-Host. Racks sind im Labor freiwillig.
4. Netze: eine VLAN-Gruppe, die VLANs und die Prefixes, jeweils mit Standort und VLAN verknüpft.
5. Virtualisierung: einen Clustertyp wie „Proxmox“, einen Cluster, und den Proxmox-Host als Gerät dazu.
6. VMs: jede mit Schnittstelle, IP-Adresse aus dem passenden Prefix und gesetzter primärer IP.

04Datenqualität

• Feste Namensregeln: Schreib auf, wie Hosts, Rollen und Standorte heißen. Aus den Namen werden später Gruppen in Ansible.
• Status pflegen: Geräte und VMs haben einen Status wie active, planned oder offline. Filterst Du in Ansible auf active, landet eine geplante VM nicht versehentlich im Lauf.
• Wenig, aber vollständig: Lieber zehn Felder, die immer gefüllt sind, als dreißig, die halb leer bleiben. Eigene Felder (Custom Fields) erst anlegen, wenn eine Automatisierung sie wirklich liest. Im Änderungsprotokoll siehst Du, wer wann was geändert hat.

05API-Token anlegen

Für Ansible legst Du einen eigenen Benutzer an, der nur lesen darf. Für diesen Benutzer erzeugst Du im Profil unter „API Tokens“ ein Token und lässt „Write enabled“ aus. Seit NetBox 4.5 gibt es Token der zweiten Generation. Sie beginnen mit nbt_ und werden mit dem Schlüsselwort Bearer übergeben. NetBox zeigt das Token nur einmal an, notier es Dir sofort im Passwortmanager.

Ein schneller Test, ob das Token funktioniert, mit curl und jq. read -rs liest es ein, ohne dass es in der Shell-Historie landet. Die Adresse netbox.labor.test:8000 steht hier und unten für Deine NetBox:

read -rs NETBOX_TOKEN && export NETBOX_TOKEN
curl -s -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Accept: application/json" \
  http://netbox.labor.test:8000/api/virtualization/virtual-machines/ | jq '.results[].name'

06Ansible liest sein Inventar aus NetBox

Das Plugin gehört zur Collection netbox.netbox und braucht die Python-Pakete pynetbox und pytz. Auf Debian 13 installierst Du Python-Pakete in eine eigene virtuelle Umgebung:

sudo apt install python3-venv jq
python3 -m venv ~/venvs/ansible
. ~/venvs/ansible/bin/activate
pip install ansible pynetbox pytz
ansible-galaxy collection install netbox.netbox

Danach beschreibt eine kleine YAML-Datei, was Ansible aus NetBox holen soll. Das Token steht nicht darin, das Plugin liest es aus der Umgebungsvariable NETBOX_TOKEN.

# netbox_inventory.yml
plugin: netbox.netbox.nb_inventory
api_endpoint: http://netbox.labor.test:8000   # Platzhalter
plurals: false
group_by:
  - site
  - role
  - cluster
query_filters:
  - status: active
device_query_filters:
  - has_primary_ip: "true"
vm_query_filters:
  - has_primary_ip: "true"

Prüf das Ergebnis, bevor Du ein Playbook darauf loslässt:

ansible-inventory -i netbox_inventory.yml --graph
ansible all -i netbox_inventory.yml -m ansible.builtin.ping

Bei jedem Host sollte ansible_host auf seine primäre IP zeigen. Die Gruppen entstehen aus Standort, Rolle und Cluster. Ein Playbook kann also auf alle Hosts mit einer bestimmten Rolle zielen, ohne dass Du eine Liste pflegst.

07Typische Fallen

• Keine primäre IP: Eine VM hat zwar eine Adresse an der Schnittstelle, aber keine primäre IP. Mit dem Filter has_primary_ip fehlt sie dann im Inventar, ohne Filter steht sie dort ohne ansible_host.
• IPv6 statt IPv4: Hat ein Host eine primäre IPv4- und eine primäre IPv6-Adresse, bevorzugt NetBox in der Grundeinstellung IPv6. Läuft Dein Labor nur mit IPv4, setz PREFER_IPV4 in der NetBox-Konfiguration.
• Token im Repository: Das Token gehört in einen Passwortmanager oder einen Tresor wie Ansible Vault, nie in die Inventardatei.
• Pflege an zwei Stellen: Wer eine Adresse am Server ändert und NetBox vergisst, hat wieder zwei Wahrheiten. Änderungen beginnen in NetBox.
• Gruppennamen geraten: Wie die Gruppen heißen, hängt von plurals und group_by ab. Schau mit --graph nach, bevor Du sie in Playbooks schreibst.

08Übung

1. Setz NetBox in einer VM auf, am einfachsten mit dem Projekt netbox-docker. Mach vorher einen Snapshot.
2. Leg einen Standort, einen Hersteller, einen Gerätetyp und die Rollen server und router an. Erfasse Deinen Proxmox-Host als Gerät.
3. Leg zwei VLANs und die dazugehörigen Prefixes an.
4. Leg einen Cluster an und erfasse zwei Debian-VMs aus Deinem Übungsnetz, jeweils mit Schnittstelle, IP-Adresse, primärer IP und Status active.
5. Erzeuge ein Token für einen Benutzer, der nur lesen darf.
6. Schreib die Inventardatei und prüfe sie mit ansible-inventory --graph und einem Ping an alle Hosts.
7. Leg in NetBox eine dritte VM an und lass das Inventar erneut laufen. Setz sie danach auf offline und lass es noch einmal laufen.

Geschafft, wenn: Die neue VM ohne Änderung an Deinen Ansible-Dateien im Inventar auftaucht, nach dem Statuswechsel wieder verschwindet und kein Token in Deinem Repository steht.

09Häufige Fragen zu NetBox

Was bedeutet „Quelle der Wahrheit“? Es gibt genau eine Stelle, an der festgelegt ist, wie das Netz aussehen soll. Alle anderen Werkzeuge lesen von dort und führen keine eigenen Listen.

Erkennt NetBox meine Geräte automatisch? Nein. NetBox beschreibt den Soll-Zustand, den Du einträgst. Es gibt Zusatzwerkzeuge, die Daten einsammeln, aber für den Einstieg pflegst Du alles selbst und lernst dabei das Datenmodell.

Was ist der Unterschied zwischen einem Prefix und einer IP-Adresse? Ein Prefix ist ein Adressbereich wie ein /24-Netz. Eine IP-Adresse ist eine einzelne Adresse mit Maske, die an einer Schnittstelle hängt. NetBox ordnet jede Adresse dem passenden Prefix zu und zeigt, wie voll ein Bereich ist.

Warum soll das Token nur lesen dürfen? Ansible braucht für das Inventar nur Lesezugriff. Gerät ein Token mit Schreibrecht in falsche Hände, kann jemand Deine ganze Dokumentation ändern, und Deine Automatisierung würde den falschen Daten folgen.

10Weiter im Lernpfad

Zurück zur Übersicht: Lernpfad IT-Infrastruktur. Das Inventar aus NetBox nutzt Du in Ansible lernen: Playbook und Rolle. Die VMs dafür legst Du mit Terraform auf Proxmox an, die Grundlage ist Deine Proxmox-Übungsumgebung. Danach geht es mit der Überwachung weiter: Server überwachen mit Zabbix. Wenn Du in der Umschulung zum Fachinformatiker bist: Dokumentation und Automatisierung von Netzen sind Teil unserer Praktika Fachinformatiker Systemintegration, Fachinformatiker Daten- und Prozessanalyse und Fachinformatiker Digitale Vernetzung.

Zuletzt geprüft: Oktober 2026