NetBox Datenprovider

Beschreibung

Der NetBox Datenprovider verbindet eine NetBox-Instanz mit Matrix42 – in beide Richtungen:

• Import (NetBox → Matrix42): Computer und Netzwerkgeräte werden samt Herstellern, Bestandsartikeln und Rollen aus NetBox in Matrix42 importiert und synchronisiert. Über das Rollen-Mapping wird gesteuert, welche NetBox-Rollen als welcher Asset-Typ übernommen werden.
• Export (Matrix42 → NetBox): Regionen, Sites, Standorte, Bestandsartikel (Gerätetypen) und Assets (Geräte) werden aus Matrix42 in NetBox angelegt und aktualisiert. Welche Objekte und Felder übertragen werden, wird vollständig in Matrix42 konfiguriert.

1 Installation

1.1 Voraussetzungen

1.2 Erweiterung installieren

Die Erweiterung NetBox Datenprovider wird über die Extension Gallery installiert (Administration > Extension Gallery).

Mit der Installation stehen unter anderem zur Verfügung:

• der Datenprovider NetBox (Generischer Konnektor) mit dem Konfigurationsdialog NetBox Configuration,
• die Workflows für Import und Export,
• die Modulaktivierungen Netbox - Import und Netbox - Export (gesperrt, ohne Zeitplan),
• der Webservice für den Export und das NetBox-Skript zum Download.

1.3 Datenprovider konfigurieren

1. Administration > Integration > Datenprovider öffnen.
2. Den NetBox-Datenprovider auswählen (im Beispiel „NetBox DEMO“) und Bearbeiten wählen.
3. Im Bereich Konfigurationen über + eine neue Konfiguration anlegen oder eine vorhandene Konfiguration per Doppelklick öffnen.
4. Im Dialog NetBox Configuration im Tab General die Verbindung zu NetBox hinterlegen und mit Speichern & Schließen speichern.

Der Dialog NetBox Configuration hat vier Tabs:

Tab General

2 Import

Der Import liest Geräte und Geräterollen über die NetBox-REST-API (/api/dcim/devices, /api/dcim/device-roles/) und legt daraus in Matrix42 Computer, Netzwerkgeräte, Hersteller, Bestandsartikel und Rollen an bzw. aktualisiert sie. Er wird vom Generischen Konnektor auf dem gewählten Data Provider Pool ausgeführt.

2.1 Import konfigurieren

Die Import-Einstellungen befinden sich im Tab Import der NetBox Configuration.

Allgemein

Importeinstellungen Inventarisierung

2.2 Rollen konfigurieren

Im Bereich Rollen konfigurieren wird festgelegt, welche Rollen aus NetBox welchen Asset-Typen in Matrix42 zugeordnet werden. Die Liste zeigt je Rolle Name, Slug und Asset Typ.

NetBox-Rollen importieren

Vor der eigentlichen Rollen-Konfiguration ist ein einmaliger Lauf des Datenproviders mit gültiger Grundkonfiguration erforderlich, ohne aktiviertes Rollen-Mapping. Dadurch werden die Rollen aus NetBox in Matrix42 importiert.

NetBox-Rollen zuordnen

Nach erfolgreichem Rollenimport wird den benötigten Rollen im Bereich Rollen konfigurieren der passende Asset Typ zugeordnet. Beim nächsten Lauf des Datenproviders werden alle Geräte importiert, deren NetBox-Rolle ein Asset Typ zugeordnet ist.

2.3 Automatische Ausführung (Modulaktivierung „Netbox - Import“)

Die mitgelieferte Modulaktivierung ist wie folgt vorkonfiguriert:

Einrichtung:

1. Administration > Dienste & Prozesse > Alle Modulaktivierungen anzeigen öffnen, Netbox - Import auswählen und Bearbeiten wählen.
2. Tab Aktivierte Dienste: Den Dienst Generic Connector öffnen und prüfen, dass unter Konnektoren der verwendete NetBox-Datenprovider eingetragen ist. Wird ein anderer Datenprovider als „NetBox“ verwendet, diesen hier auswählen.
3. Tab Zeitpläne: Über + einen Zeitplan anlegen (Name, Starte von, Laufzeit, Zeitzone, Frequenz, Wiederholung, Ende) und mit Beenden übernehmen.
4. Tab Allgemein: Gesamte Aktivierung abschalten entfernen.
5. Mit Speichern & Schließen speichern.

2.4 Attribut-Mapping

Die folgenden Tabellen zeigen, welche NetBox-Attribute in welche Matrix42-Felder importiert werden. Mit (matching) gekennzeichnete Felder dienen zur Wiedererkennung bestehender Objekte.

Computer (Asset-Gruppe 1)

API-Aufruf: GET https://{NetBoxUrl}/api/dcim/devices

Netzwerkgeräte (Asset-Gruppe 8)

API-Aufruf: GET https://{NetBoxUrl}/api/dcim/devices

Hersteller

Die Hersteller ergeben sich aus den eindeutigen Werten von device_type.manufacturer.name.

Rollen

API-Aufruf: GET https://{NetBoxUrl}/api/dcim/device-roles/

Bestandsartikel (Device Types)

Die Bestandsartikel ergeben sich aus den eindeutigen Kombinationen von device_type.model und device_type.manufacturer.name.

3 Export

3.1 Überblick

Beim Export werden Regionen, Sites, Standorte, Bestandsartikel und Assets aus Matrix42 in NetBox angelegt und aktualisiert. Im Tab Export der NetBox Configuration wird festgelegt, welche Objekte mit welchen Feldern übertragen werden. Die Übernahme in NetBox führt das NetBox-Skript Matrix42 Sync aus, das Konfiguration und Daten beim Webservice der Erweiterung abruft.

Ablauf eines aus Matrix42 gestarteten Exports:

3.2 Voraussetzungen

• NetBox 4.x mit aktivierten Custom Scripts. Das Python-Paket requests muss in NetBox verfügbar sein (im offiziellen NetBox-Docker-Image enthalten).
• Netzwerk: NetBox muss Matrix42 per HTTPS erreichen. Für den Start aus Matrix42 muss umgekehrt Matrix42 NetBox unter der Netbox Url erreichen.
• Matrix42-API-Token (Administration > Integration > Web Services Tokens) eines Benutzers, der die exportierten Daten lesen darf.
• Umgebungsvariablen M42_BASE_URL und M42_API_TOKEN in NetBox (siehe 3.3).
• Geräterollen: Die im Field Mapping für role gelieferten Slugs müssen in NetBox als Geräterollen existieren.
• Custom Fields: Werden über cf_<name> weitere Custom Fields befüllt, müssen diese in NetBox angelegt und dem jeweiligen Objekttyp zugewiesen sein. Das Custom Field matrix42_eoid legt das Skript selbst an.
• NetBox-API-Token (v1) im Tab General mit der Berechtigung, Skripte auszuführen (nur für den Start aus Matrix42).

3.3 Einrichtung

1. Matrix42-API-Token erstellen unter Administration > Integration > Web Services Tokens.
2. Export aktivieren: Im Tab Export der NetBox Configuration Export aktivieren setzen und speichern. Die Configuration ID wird später in NetBox benötigt.
3. Sync-Skript herunterladen: Im Tab Export DOWNLOAD SCRIPT wählen. Die heruntergeladene Datei netbox_sync.py passt immer zur installierten Version des Webservice.
4. Umgebungsvariablen in NetBox setzen und NetBox neu starten. Bei Docker-Installationen müssen die Variablen sowohl im NetBox-Container als auch im Worker-Container gesetzt sein, da Skripte als Hintergrundjob laufen:

   environment:
     M42_BASE_URL: 'https://matrix42.example.com'   # Basis-URL ohne /m42Services
     M42_API_TOKEN: '<Matrix42-API-Token>'

5. Skript in NetBox hochladen: In NetBox unter Customization > Scripts über Add die Datei netbox_sync.py hochladen. Danach erscheinen die Skripte Matrix42 Sync und Matrix42 Link Existing Objects.
6. Script-ID eintragen: Die numerische ID des Skripts Matrix42 Sync ermitteln (sichtbar in der URL /extras/scripts/<ID>/ oder über GET /api/extras/scripts/) und im Tab Export unter Netbox Script Id eintragen.
7. Geräterollen in NetBox anlegen, die im Field Mapping der Assets verwendet werden.
8. Entitäten konfigurieren: Im Tab Export je Entität Export-Haken, Filter, Status Mapping und Field Mapping festlegen (siehe 3.5 bis 3.7).
9. Bestehende NetBox-Daten verknüpfen: Enthält NetBox bereits Objekte, die aus Matrix42 kommen sollen, diese einmalig mit Matrix42 Link Existing Objects verknüpfen (siehe 3.8.1).
10. Testlauf: Matrix42 Sync in NetBox ohne Commit ausführen, das Protokoll prüfen und danach mit Commit ausführen (siehe 3.8.2).
11. Automatisieren über die Modulaktivierung Netbox - Export (siehe 3.8.3).

3.4 Tab Export – Einstellungen

3.5 Entitäten

Der Tab Export enthält je Entität einen eigenen Bereich. Die Entitäten werden in der folgenden Reihenfolge verarbeitet, damit Verweise auf bereits übertragene Objekte aufgelöst werden können:

Jeder Bereich enthält folgende Felder:

3.6 Field Mapping

Jede Zeile im Field Mapping ordnet einem NetBox-Feld einen Wert aus Matrix42 zu.

Zeilen ohne Columns Expression oder Netbox Target werden ignoriert. Für jede exportierte Entität muss mindestens eine vollständige Zeile vorhanden sein.

Pflichtzeile: Jede Entität benötigt die Zeile [Expression-ObjectID] → cf_matrix42_eoid. Darüber wird das Matrix42-Objekt dem NetBox-Objekt zugeordnet. Datensätze ohne diesen Wert werden nicht übertragen.

Field Policy

Ist keine Field Policy angegeben, gilt Always.

NetBox-Felder mit besonderer Behandlung

Alle anderen Netbox Targets werden direkt in das gleichnamige NetBox-Feld geschrieben (z. B. name, serial, asset_tag, description, comments, model, u_height, part_number, facility). Weitere Verweisfelder wie location, parent oder platform werden nicht unterstützt.

Welche Felder NetBox beim Anlegen verlangt, hängt vom Objekt ab. Der Slug wird bei Regionen, Sites, Standorten und Device Types automatisch als m42-<ID> gesetzt.

Beispiel: Field Mapping der Assets

Beispiel: Field Mapping der Bestandsartikel

3.7 Status Mapping

Das Status Mapping ordnet jedem Matrix42-Status einen NetBox-Status zu. Es ist für Site, Standort und Assets vorhanden und wird verwendet, wenn das Field Mapping das Feld status liefert.

• Status ohne zugeordneten NetBox-Status werden ignoriert. Objekte mit einem solchen Status werden nicht übertragen und im Protokoll als Fehler gemeldet.
• Der NetBox-Status muss für das jeweilige Objekt gültig sein:

3.8 Export ausführen

3.8.1 Einmalig: bestehende NetBox-Objekte verknüpfen

Enthält NetBox bereits Regionen, Sites, Standorte, Device Types oder Geräte, die künftig aus Matrix42 gepflegt werden sollen, müssen diese vor dem ersten Sync verknüpft werden. Andernfalls legt der Sync Duplikate an oder scheitert an bereits vergebenen Namen.

Das Skript Matrix42 Link Existing Objects ordnet die aus Matrix42 gelieferten Datensätze noch nicht verknüpften NetBox-Objekten zu. Dazu vergleicht es je Entität ein wählbares Feld und schreibt bei Übereinstimmung das Custom Field matrix42_eoid sowie das Tag m42-managed. Es legt keine Objekte an und ändert keine anderen Felder.

Regeln:

• Verglichen wird ohne Beachtung von Groß-/Kleinschreibung und führenden oder abschließenden Leerzeichen.
• Das Match field muss im Field Mapping der Entität als Netbox Target geliefert werden. Soll der Wert beim Sync nicht geschrieben werden, die Field Policy Never verwenden.
• Kommt ein Wert bei mehreren unverknüpften NetBox-Objekten vor, wird keines davon verknüpft.
• Bereits verknüpfte Objekte bleiben unverändert. Abweichungen im Match field werden als Warnung gemeldet.

Empfohlener Ablauf:

1. Skript ohne Commit ausführen.
2. Gemeldete Abweichungen in Matrix42 oder NetBox bereinigen und Schritt 1 wiederholen, bis das Protokoll sauber ist.
3. Skript mit Commit ausführen.
4. Anschließend Matrix42 Sync ausführen.

3.8.2 Manuell in NetBox

In NetBox unter Customization > Scripts das Skript Matrix42 Sync öffnen, die Parameter angeben und ausführen:

Das Ergebnis enthält je Entität die Anzahl der angelegten (created), aktualisierten (updated), unveränderten (unchanged), fehlgeschlagenen (failed) und nicht mehr gelieferten (disappeared) Objekte, z. B.:

regions: 0 created, 0 updated, 1 unchanged, 0 failed, 0 disappeared | sites: … | assets: 0 created, 0 updated, 1 unchanged, 0 failed, 0 disappeared

Alternativ kann Matrix42 Sync in NetBox direkt zeitgesteuert ausgeführt werden (Optionen Schedule at und Recurs every beim Ausführen).

3.8.3 Automatisch aus Matrix42 (Modulaktivierung „Netbox - Export“)

Die Erweiterung liefert die Modulaktivierung Netbox - Export mit. Sie startet den Workflow Netbox - Trigger Export. Dieser startet in NetBox das unter Netbox Script Id hinterlegte Skript für diese Konfiguration, wartet auf das Ende des NetBox-Jobs und speichert Status, Zeitpunkt, Ergebnis und Protokoll in den Feldern Last Export … im Tab Export.

Die Einrichtung erfolgt wie beim Import (siehe 2.3): Zeitplan im Tab Zeitpläne anlegen, im Tab Allgemein Gesamte Aktivierung abschalten entfernen und speichern.

Voraussetzungen für den Start aus Matrix42:

• Netbox Url und Token (v1) im Tab General sind gesetzt; der Token darf Skripte ausführen.
• Netbox Script Id im Tab Export enthält die ID des Skripts Matrix42 Sync.
• Export aktivieren ist gesetzt.

3.9 Verhalten beim Abgleich

• Verknüpfung: Matrix42-Objekte und NetBox-Objekte werden ausschließlich über das Custom Field matrix42_eoid (Label „Matrix42 EOID“) zugeordnet. Das Skript legt das Custom Field beim ersten Lauf an und weist es Region, Site, Location, Device Type und Device zu.
• Kennzeichnung: Alle vom Sync angelegten oder geänderten Objekte erhalten das Tag m42-managed. Auch automatisch angelegte Hersteller, Mandanten und Tags werden damit gekennzeichnet.
• Neue Objekte: Objekte ohne passendes matrix42_eoid werden neu angelegt. Regionen, Sites, Standorte und Device Types erhalten den Slug m42-<ID>.
• Unveränderte Objekte werden nicht gespeichert und erzeugen keinen Changelog-Eintrag.
• Nicht mehr gelieferte Objekte (z. B. durch einen geänderten Filter oder gelöschte Objekte in Matrix42) werden nur im Protokoll gemeldet. Sie werden in NetBox weder geändert noch gelöscht.
• Fehler: Verbindungs-, HTTP- oder Formatfehler beim Abruf brechen den gesamten Lauf ab, damit nie mit unvollständigen Daten abgeglichen wird. Fehler bei einzelnen Datensätzen werden protokolliert; die übrigen Datensätze werden weiter verarbeitet.
• Simulation: Ohne Commit werden alle Änderungen am Ende zurückgenommen. Das Ergebnis endet dann mit SIMULATION - nothing was saved.

3.10 Webservice-Referenz

Basis-URL: https://<Matrix42-Server>/m42Services/api/mountx/netbox

Authentifizierung

1. POST /m42Services/api/ApiToken/GenerateAccessTokenFromApiToken mit dem Header Authorization: Bearer <Matrix42-API-Token>. Die Antwort enthält im Feld RawToken ein Access-Token.
2. Alle weiteren Aufrufe mit dem Header Authorization: Bearer <RawToken>.

Endpunkte

Jeder Datensatz enthält die im Field Mapping definierten Netbox Targets als Schlüssel. Ist eine Entität nicht zum Export freigegeben, ist die Liste leer.

Beispiel:

GET https://matrix42.example.com/m42Services/api/mountx/netbox/skus?configurationId=<Configuration ID>
Authorization: Bearer <RawToken>
Accept: application/json

{
  "Skus": [
    {
      "model": "Catalyst 9300",
      "manufacturer": "Cisco",
      "cf_matrix42_eoid": "<ID des Bestandsartikels>",
      "u_height": 1
    }
  ]
}

Fehlermeldungen des Webservice

3.11 Fehlerbehebung

Die folgenden Meldungen erscheinen im Protokoll des NetBox-Jobs bzw. im Feld Last Export Log.