Funktionalität des ND-Device-Imports

Verfahrensbeschreibung

Durch das Import-Verfahren besteht die Möglichkeit, den Sollzustand eines ganzheitlichen Datenbestandes abzubilden. Dieser ganzheitliche Datenbestand umfasst den lt. Datenmodell dokumentierbaren Konfigurationsumfang eines Devices bzw. Hosts, dh. die device-bezogenen (regulären) Objekttypen.

Als Import-Medium dient ein JSON-Dokument. Das Import-Verfahren besteht darin, dass der aktuell vorhandene Datenbestand eines Devices (reguläre Objekttypen) mit dem des zu importierenden Datenbestandes (Objekttypen des Import-JSON-Dokuments) nach einem Differenzverfahren abgeglichen wird. Nach erfolgreichem Abschluss des Imports gibt es keine Unterschiede zwischen beiden Datenbeständen, dh. der Stand der Daten im Import-Medium stellt den Sollzustand dar. Pro Import-Vorgang wird genau ein Device behandelt. Für Devices selbst können Neueinträge und Aktualisierungen, aber keine Löschungen vorgenommen werden.

Die folgende Tabelle zeigt die Zuordnung zwischen den regulären Objekttypen (device-bezogene) und den Import-Objekttypen des JSON-Dokuments:

device-bezogener Objekttyp korrespondierender Import-Objekttyp (JSON)
nd.vlan2device nd.vlan_imp
nd.l_port nd.l_port_imp
nd.l2p_port nd.l2p_port_imp
nd.ip_intf nd.ip_intf_imp
nd.ip_route nd.ip_route_imp
nd.vlan_egress nd.vlan_egress_imp
cntl.ot_attr_val nd.device_attribute_imp

Aufrufmöglichkeiten / Schnittstellen

Die Importfunktion ist in 2 Varianten aufrufbar:

  1. direkt als WebAPI-Funktion nd.device.imp
  2. indirekt als Teilarbeitsschritt ‘DB-Importer’ einer DIQ-Transaktion

und besteht aus 2 Teilschritten, die via Schalter nd.device.do_import (Bool-Parameter) der WebAPI-Funktionnd.device.imp separat steuerbar sind (s.a. Importfunktion vs. DIQ):

  1. Übergabe/Eingabe des JSON-Dokuments und interne Speicherung
  2. Import des intern gespeicherten JSON-Dokuments

Dadurch ist die Übergabe und Zwischenspeicherung des JSON-Dokuments und dessen eigentliche Verarbeitung transaktional entkoppelbar, um die beiden Aufrufvarianten miteinander kombinieren zu können. Prinzipielle Wirkungsweise der steuerbaren Teilschritte in beiden Aufrufvarianten:

  • in Teilschritt 1 wurde ein JSON-Dokument übergeben und Teilschritt 2 ist deaktiviert: Das übergebene JSON-Dokument wird intern gespeichert, bis es in einer anderen, nachfolgenden Transaktion importiert wird.
  • in Teilschritt 1 wurde kein JSON-Dokument übergeben und Teilschritt 2 ist aktiviert: Setzt voraus, dass das zu importierende JSON-Dokument bereits in einer anderen, vorausgehenden Transaktion übergeben und gespeichert wurde.
  • in Teilschritt 1 wurde ein JSON-Dokument übergeben und Teilschritt 2 ist aktiviert: Das übergebene JSON-Dokument wird intern gespeichert, importiert und danach wieder gelöscht.

DIQ - Device-Import-Queue

Die DIQ ist eine Warteschlange geplanter Device-Import-Transaktionen, die in der Reihenfolge ihrer Positionen zyklisch durch den DIQ-Workerprozess auf den DIQ-Servern

- svc-netdb-prod-1.tmn.scc.kit.edu (Produktionsumgebung)
- svc-netdb-test-1.tmn.scc.kit.edu (Testumgebung)
- svc-netdb-devel-1.tmn.scc.kit.edu (Entwicklungsumgebung)

abgearbeitet wird. Die Position einer wartenden (aktiven) DIQ-Transaktion ergibt sich im Normalfall aus der zeitlichen Reihenfolge des Eintragens, kann aber bei Bedarf mit DIQ-Administrator-Rechten modifiziert werden.

Zu einer DIQ-Transaktion gehören ein oder mehrere Device-Einträge mit den jeweils zugeordneten Einstellungen und Arbeitsschritten. Bei mehreren Devices ist die Reihenfolge innerhalb der Transaktion durch die FQDN-Sortierung festgelegt. Die Arbeitsschritte umfassen das Hochladen der Konfiguration, die Konfigurationssicherung und das Parsen dieser gesicherten Konfiguration (Kernfunktionen des Parsers) sowie die eigentliche Importfunktion. Der letzte Arbeitsschritt des Parsers erzeugt als Ergebnis das für den eigentlichen Import erforderliche JSON-Dokument und speichert es intern ab - unabhänging davon, ob die abschließende Importfunktion aktiviert wurde oder nicht.

Die DIQ kann aktive und passive Transaktionseinträge behinhalten. Die aktiven Einträge sind wartende Einträge und werden positional durch den DIQ-Worker abgearbeitet; die passiven sind pausierte Einträge und verbleiben parallel zu den aktiven unbehandelt (werden vom DIQ-Worker ignoriert), bis sie entweder gelöscht oder reaktiviert werden. Bei Reaktivierung werden sie direkt wieder ans Ende der aktiven Einträge positioniert, so dass sie wieder zu Kandidaten für die Abarbeitung durch den DIQ-Worker werden.

Leere aktive DIQ-Transaktionen (solche, die keine Devices enthalten) werden bei Abarbeitung durch den DIQ-Worker sofort gelöscht. Leere passive DIQ-Transaktionen verbleiben, wie beschrieben.

Aktive vs. passive DIQ-Transaktionen

Um eine DIQ-Transaktion später wiederholen zu können, besteht die Möglichkeit, diese nach Abarbeitung nicht automatisch löschen zu lassen, sondern als passiven Eintrag zu behalten. Dies kann als Erinnerung an fehlerhafte, noch zu erledigende Transaktionen oder zur Vorbereitung/Zusammenstellung mehrerer transaktional zu importierender Devices bzw. für wiederholbare Import-Szenarien dienen.

Diese Steuerung wird durch die Parameter

  • nd.diq_ta.preserve_on_error: DIQ-TA bei DI-Fehler behalten
  • nd.diq_ta.preserve_on_success: DIQ-TA bei DI-Erfolg behalten

erreicht. Eine Reaktivierung ist jederzeit durch Ändern des Schalters nd.diq_ta.is_active (DIQ-TA zur Bearbeitung aktiviert) möglich. Die DIQ-Transaktion wird dann mit allen Einstellungen der enthaltenen Device-Einträge erneut vom DIQ-Worker abgearbeitet.

Das letzte Transaktionsergebnis kann in passiven Einträgen jederzeit abgefragt werden. Alternativ kann es per E-Mail direkt nach Abarbeitung einmalig an den Eigentümer gesendet werden:

  • nd.diq_ta.mail_on_error: Mail bei DI-Erfolg zusenden
  • nd.diq_ta.mail_on_error: Mail bei DI-Fehler zusenden

Parser

Die Objekte des Typs ndcfg.parser beinhalten vordefinierte Methoden zur Behandlung der komponenten- bzw. herstellerspezifischen Gerätekonfigurationsdateien. Diese Methoden bestehen aus den Teilarbeitsschritten

  • Upload: Hochladen der Konfiguration bzw. von Teilen der Konfiguration von einer Datei, die auf dem DIQ-Server bereitgestellt werden muss
  • Save: Sichern der Gerätekonfiguration in eine Datei auf dem DIQ-Server
  • Parse: Übersetzen der zuvor gesicherten Konfiguration in das Import-JSON-Dokument (und dessen interne Speicherung)

Diese Schritte bzw. Methoden können entweder im DIQ-Parser direkt integriert werden (und im Verbund über den DIQ-Worker gemeinsam mit dem DB-Import aktiviert werden), oder davon unabhängig als externer Parser bereitgestellt werden. Im letzten Fall wird die extern gewonnene Gerätekonfiguration als JSON-Dokument über die WebAPI-Device-Importfunktion intern gespeichert und kann -je nach Schalter do_import- in derselben oder einer anderen bzw. späteren Transaktion importiert werden.

Importfunktion

Die WebAPI-Funktion nd.device.imp importiert das zuvor bereitgestellte bzw. direkt übergebene Import-Medium (JSON-Dokument, s. Beispiel) in die Datenbank. Das Import-Medium wird anschließend gelöscht. Wurde kein Import-Medium bereitgestellt, bricht die Transaktion mit einer Fehlermeldung ab.

WebAPI-basierter Device-Import vs. DIQ

Die Teilarbeitsschritte des Parsers und die DB-Importfunktion können nach folgenden Varianten kombiniert werden:

  1. DIQ-Parser + DIQ-DB-Importer: Standardmethode

  2. externer Parser + DIQ-DB-Importer: das JSON-Dokument des externen Parsers wird durch die WebAPI-Funktion nd.device.imp mit den Parametern

    • do_import = false
    • import_data = {<import_json_doc>}

    gespeichert, aber wg. not do_import noch nicht importiert. Anschließend kann die DIQ-Transaktion für das betreffende Device (ggf. zusammen mit anderen Devices in dieser TA) aktiviert werden. Erst dadurch erfolgt der eigentliche Import.

  3. DIQ-Parser + WebAPI-DB-Importer: das gespeicherte JSON-Dokument des DIQ-Parsers wird durch die WebAPI-Funktion nd.device.imp ohne Angabe des Parameters import_data importiert.

  4. externer Parser + WebAPI-DB-Importer: das JSON-Dokument des externen Parsers wird durch die WebAPI-Funktion nd.device.imp gespeichert und importiert.

Der Vorteil dieser Kombinationsmöglichkeiten liegt darin, dass jeweils die DIQ-Transaktion oder die WebAPI-Transaktion unabhängig voneinander zusammengestellt werden können. Mit Variante 1 allein wäre es z.B. nicht möglich, den Device-Import mit anderen WebAPI-Statements in derselben Transaktion zu kombinieren. Auch könnten Devices mit externen Parserdaten (externes JSON-Dokument) und Devices mit DIQ-Parserdaten nicht in derselben Transaktion importiert werden. Der Import über die WebAPI-Funktion gestattet außerdem eine willkürliche Reihenfolge und Kombination der zu importierenden Devices mit weiteren Statements der Transaktion. In der DIQ-Transaktion ist die Reihenfolge durch die FQDN-Sortierung festgelegt.

Datenstruktur des Import-JSON-Dokuments

Die Daten im JSON-Dokument für den Device-Import haben immer überschreibende Wirkung, dh. der Stand der Daten im importierten JSON-Dokument stellt den Sollzustand dar. Ausgenommen sind die Key-Value-Paare unter nd.device_attribute_imp; hier werden nur die Values der angegebenen Keys überschrieben (wird intern auf die Funktion cntl.ot_attr_val.update umgeleitet).

Schema:

{
  "nd.vlan_imp": [{"id": 0, "vxlan_vni": null, "name": ""}, ...],
  "nd.device_attribute_imp": [{"key_word": "", "value": ""}, ...],
  "nd.ip_route_imp": [{"net": "", "dest_ip_addr": "", "dest_l_port_name": "", "metric": 0}, ...],
  "nd.ip_intf_imp": [{"ip_addr": "", "is_secondary": true, "is_vrrp": true, "l_port_name": "", "vrrp_id": 0}, ...],
  "nd.l_port_imp": [{"name": "", "vlan_id_ingress": 0, "description": "", "status": 0, "port_level": 0, "prio": 0, "lag": 0}, ...],
  "nd.vlan_egress_imp": [{"id": 0, "l_port_name": "", "is_tagged": true}, ...],
  "nd.l2p_port_imp": [{"l_port_name": "", "p_port_name": "", "mdl_fq_name": "", "port_order": 0}, ...]
}

Die Import-Objekttypen (JSON-Keys des importierten JSON-Dokuments) und deren Attribute sowie Datenintegritätsbedingungen (Constraints) sind im Objekttyp- bzw. Funktionsindex unter der Funktion document sichtbar. Die inneren JSON-Objekte stellen die zu importierenden Datensätze dar. Deren Keys entsprechen den Attributnamen des zugehörigen Import-Objekttyps. Attribute in Import-Datensätzen, die namentlich keine Übereinstimmung mit den dokumentierten Attributen haben, werden automatisch ignoriert. Nicht vorkommende (weggelassene) Attribute in Import-Datensätzen bekommen automatisch den Wert NULL, sofern kein Standardwert existiert.

Beispiel