Funktionalität des Device-Imports

Verfahrensbeschreibung

Durch das Import-Verfahren besteht die Möglichkeit, einen ganzheitlichen Datenbestand abzubilden, der den lt. Datenmodell dokumentierbaren Konfigurationsumfang eines Devices bzw. Hosts umfasst. Zu diesem ganzheitlichen Datenbestand gehören die device-bezogenen (regulären) Objekttypen. Als Import-Medium dient ein JSON-Dokument. Das Import-Verfahren besteht darin, dass der aktuell dokumentierte Datenbestand eines Devices (reguläre Objekttypen) mit dem des zu importierenden Datenbestandes (Objekttypen des Import-JSON-Dokuments) nach einem Differenzverfahren abgeglichen wird. Nach 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. Es 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.device {"main": {}}
nd.vlan2device {"sub": {"nd.vlan_imp": {}}
nd.device_attribute {"sub": {"nd.device_attribute_imp": {}}
nd.l_port {"sub": {"nd.l_port_imp": {}}
nd.l2p_port {"sub": {"nd.l2p_port_imp": {}}
nd.ip_intf {"sub": {"nd.ip_intf_imp": {}}
nd.ip_route {"sub": {"nd.ip_route_imp": {}}
nd.vlan_egress {"sub": {"nd.vlan_egress_imp": {}}

Aufrufmöglichkeiten / Schnittstellen

Die Import-Funktion 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 separat steuerbar sind:

  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:

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

- net-svc01.tmn.scc.kit.edu (Produktionsumgebung)
- net-svc-test.tmn.scc.kit.edu (Testumgebung)
- net-svc-devel.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 jeweiligen Einstellungen und Arbeitsschritten. Diese Arbeitsschritte umfassen neben der eigentlichen Import-Funktion auch das Hochladen der Konfiguration, die Konfigurationssicherung und das Parsen der gesicherten Konfiguration (s.a. Parser). Der letzte Schritt erzeugt als Ergebnis das für den eigentlichen Import erforderliche JSON-Dokument und speichert es intern ab. Bei mehreren Devices ist die Reihenfolge innerhalb der Transaktion durch die FQDN-Sortierung festgelegt.

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

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:

Parser

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

Diese Schritte bzw. Methoden können entweder im Verbund über den DIQ-Worker (via DeviceImport-Queue) gemeinsam mit dem DB-Import aktiviert werden oder extern bereitgestellt werden.

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 wird die DIQ-Transaktion für das betreffende Device (ggf. zusammen mit anderen Devices in dieser TA) aktiviert. Erst dadurch erfolgt der eigentliche Import.
  3. externer Parser + WebAPI-DB-Importer: das JSON-Dokument des externen Parsers wird durch die WebAPI-Funktion nd.device.imp gespeichert und importiert.
  4. 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.

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. Schema:

{
  "main": {
    "acg_name": "<access_group>",
    "device_description": "info text",
    "device_type_name": "<type>",
    "nc_name": "<net_compound>",
    "parser_name": "<parser>",
    "snmp_sysdescr": "sysdescription text"
  },
  "sub": {
      "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": "", "mdl_pk": 0, "port_order": 0}, ...]
  }
}

Die Import-Objekttypen (JSON-Keys des Objekts unter sub) und deren Attribute 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 Attribute in Import-Datensätzen bekommen automatisch den Wert NULL, sofern kein Standardwert existiert.