Von der NiFi Registry nach GitLab: Flows migrieren, ohne die Versionshistorie zu verlieren

Wer Datenflüsse mit Apache NiFi betreibt, kennt die NiFi Registry: Sie versioniert Flows, hält Änderungen fest und macht frühere Stände jederzeit wieder zugänglich. Lange Zeit war sie der einzige Registry-Client, der NiFi Flows versionieren und damit ein gemeinsames Arbeiten an Flows ermöglichen konnte. Mit NiFi 2.0 wurden auch andere Registry-Clients, wie GitLab, Bitbucket oder GitHub, eingeführt. Mit NiFi 3.0 stellt der Hersteller die NiFi Registry ein.

Das Problem: Die Historie bleibt zurück

Im Laufe der Zeit können für einzelne Flows zahlreiche Versionen entstehen, jeweils mit Zeitstempel und Kommentar. Diese Historie ist insbesondere im Betrieb wertvoll, da sie Änderungen nachvollziehbar macht und frühere Versionsstände dokumentiert. Wird die NiFi Registry abgeschaltet, ohne die bestehende Historie zu migrieren, gehen diese Informationen verloren. 

Die Lösung: GitLab als native Versionierung

Seit NiFi 2.x lassen sich Flows direkt über Git versionieren. Dafür gibt es den GitLabFlowRegistryClient. Dabei ist GitLab nicht die einzige Option. NiFi 2.x bringt Flow Registry Clients für GitHub, GitLab, Bitbucket und Azure DevOps mit. Daneben existiert weiterhin der NifiRegistryFlowRegistryClient für die bisherige NiFi Registry, der mit NiFi 3.0.0 aber entfällt. Noch wichtiger ist jedoch ein Aspekt, der leicht unterschätzt wird und zwar: Der GitLabFlowRegistryClient ist kein direkter Ersatz mit identischer Bedienung für die bisherige NiFi Registry. Die grundlegende Funktion und die Versionierung von Flows bleiben erhalten, jedoch unterscheiden sich beispielsweise die Anbindung, die Verwaltung von Versionen und die Interaktion mit dem Git-Repository.

Erst verstehen, dann programmieren

Bevor die erste Zeile Code entstand, stand eine Frage im Raum: Wie genau erwartet NiFi die Daten in Git?

Laut offiziellem Java-Quellcode für GitLabFlowRegistryClient, konkret AbstractGitFlowRegistryClient.java war das Ergebnis eindeutig:

• Ein Flow entspricht genau einer Datei im Repository. 
• Jede Version ist ein Commit auf dieser Datei. 
• Die „Version“ ist die Commit-SHA, keine fortlaufende Zahl mehr. 
• Die Datei wird bei jeder Version überschrieben, nicht dupliziert.

Entscheidend ist dabei, dass Bucket und Flow über lesbare Namen identifiziert werden und nicht wie in NiFi Registry über UUIDs. Werden stattdessen die bisherigen UUIDs als Namen übernommen, kann NiFi die migrierten Flows nicht korrekt zuordnen. 

Das Projekt: Ausgangslage und Ziel

Im Rahmen meines Praxisprojektes bei ORDIX habe ich genau diesen Fall bearbeitet. Bei der ORDIX haben wir ein laufendes BI-Projekt. Dabei wird NiFi eingesetzt, um Daten aus verschiedenen lokalen Datenbanken abzurufen, teilweise zu anonymisieren, in unterschiedliche Dateiformate umzuwandeln und in der Cloud abzulegen.

Das Projekt besteht seit mehr als drei Jahren. Die Versionsverwaltung der NiFi Flows erfolgt bislang über die NiFi Registry. Im Laufe dieser Zeit wurden die Flows kontinuierlich erweitert und angepasst, wodurch eine umfangreiche Versionshistorie entstanden ist.

Die Migration verteilt sich auf drei Python-Skripte. Die ersten beiden Migrationsskripte sprechen direkt mit der Registry REST API, das dritte hingegen mit der NiFi REST API.

01) Registry-History.py (optional): Exportiert die Versionshistorie aus der bestehenden Registry und legt die Rohdaten als JSON-Dateien ab. Dieser Schritt ist optional, weil Git-Migration.py die Versionen auch selbst direkt über die Registry REST API abrufen und daraus die Commits erstellen kann. Für den Migrationsablauf ist kein technischer Export erforderlich. Der Export kann dennoch sinnvoll sein, um einen Überblick über die Rohdaten zu behalten.

02) Git-Migration.py: Verarbeitet die Rohdaten, bereinigt sie nach der Analyse des Java-Quellcodes des GitLabFlowRegistryClient und erzeugt für jede historische Version einen eigenen Commit. Ziel dieses Skriptes ist die vollständige Übernahme der Versionshistorie einschließlich der ursprünglichen Zeitstempel aus den bestehenden NiFi Registry in ein GitLab Repository.

Damit die migrierten Commits nicht alle den Zeitpunkt der Migration erhalten, wird der ursprüngliche Zeitstempel beim Erstellen des Commits übernommen. Dafür werden GIT_AUTHOR_DATE und GIT_COMMITTER_DATE entsprechend gesetzt.

03) Update-Process-Group.py: Das ist der dritte und letzte Schritt. Das dritte Skript ermöglicht die direkte Umstellung der Process Groups aus der NiFi Registry auf das GitLab Repository ohne jede Process Group manuell anfassen zu müssen. Dadurch können die Versionen direkt über die Funktion „Change Version“ verwaltet und bei Bedarf auf frühere Versionsstände zurückgesetzt werden.

Entscheidend ist dabei das Objekt versionedFlow. Darin werden Registry, Bucket, Flow und die Aktion Commit angegeben. Bucket und Flow werden dabei nicht aus einer Neuanlage erzeugt, sondern aus der vorhandenen API-Antwort des gefundenen Flows übernommen. Zusätzlich wird die aktuelle ProcessGroupRevision angegeben, die NiFi für den Request erwartet, damit NiFi die Änderung auf dem aktuellen Stand der Process Group ausführt.

Fazit

Der Wechsel von der NiFi Registry zu GitLab bedeutet vor allem eins: Flow-Definitionen als das zu behandeln, was sie in Git tatsächlich sind und zwar als Dateien, deren Namen über den Pfad bestimmt werden und nicht über eine UUID. Wer die migrierten Flow-Definitionen an der von NiFi erwarteten Struktur ausrichtet, erhält eine vollständig nachvollziehbare Versionshistorie.

Der Aufwand für eine saubere Migration zahlt sich im Betrieb aus. Die Historie liegt im selben Repository wie die übrige Infrastruktur und Änderungen an Flows lassen sich mit demselben Werkzeug nachverfolgen wie Änderungen am Quellcode.

Und die Git-basierte Versionierung eröffnet Möglichkeiten, die es vorher nicht gab: Automatisierter Abgleich über CI/CD-Pipelines etwa oder die saubere Trennung von Entwicklungs- und Produktionsständen über Branches.

Falls ihr bei eurer Migration Unterstützung braucht, kontaktiert uns gerne. In unseren praxisorientierten Seminaren und Schulungen vermitteln wir fundiertes Wissen rund um Apache NiFi und unterstützen euch dabei, das Gelernte direkt in der Praxis anzuwenden.

Tipp: Für den fachlichen Austausch empfehlen wir außerdem die MeetUp-Gruppe „Apache NiFi Germany“.

Seminarempfehlungen