In Teil 1 dieser Artikelserie ging es darum, wie du Airbyte installierst und wie du Verbindungen in der Airbyte-Instanz über die Weboberfläche konfigurierst. Dabei hast du auch erfahren, dass das Deployment auf andere Airbyte-Instanzen nur mit großem manuellem Aufwand möglich ist.
Jetzt fragst du dich wahrscheinlich, ob bei Airbyte auch ein Command-Line-Tool inklusive Versionierung in Git eingesetzt werden kann. Die Antwort auf deine Frage lautet: Ja. Dafür gibt es das Tool Octavia-cli.
Was kann Octavia-cli?
Octavia-cli ist ein Command-Line-Tool zur deklarativen Verwaltung von Datenintegrationskonfigurationen mithilfe von YAML-Dateien.
Octavia-cli bietet:
- Generierung von YAML-Dateien inkl. Versionierung in Git
- Dynamische Generierung von Konfigurationen für Sources, Destinations und Connections
- Deployment der Konfiguration auf multiplen Airbyte Instanzen
- Integration in einen CI-Workflow zur Automatisierung des Deployments
Octavia-cli läuft in einem Docker Image. Details zur Installation findest du hier: https://github.com/airbytehq/airbyte/blob/master/octavia-cli/README.md#install
Im Docker-Container erfolgt die Installation mit folgendem Befehl im Bash-Profil:
curl -s -o- https://raw.githubusercontent.com/airbytehq/airbyte/master/octavia-cli/install.sh | bash
Wie wird Octavia-cli verwendet?
Die Arbeit mit Octavia-cli lässt sich in 5 Schritte aufteilen:
1. Der Einstieg
Am besten arbeitest du mit einer IDE (z. B. Visual Studio Code). Nach der Installation von Octavia-cli erstellst du in deinem Projektverzeichnis ein Unterverzeichnis (z. B. octavia_directory). Hier werden später die YAML-Dateien der Sources, Destinations und Connections abgelegt.
Dann wechselst du in dieses Verzeichnis und führst den Befehl
octavia init
aus.
Mit diesem Befehl erstellst du unterhalb des zuvor erstellten Octavia-Verzeichnisses die Verzeichnisstruktur für Connections, Destinations und Sources.
Aufbau des Octavia-Verzeichnisses
Mithilfe der Befehle
octavia list connectors sources
octavia list connectors destinations
kannst du dir sämtliche Source- und Destination-Konnektoren auflisten lassen.
Liste aller Source- und Destination-Konnektoren
Später, z. B. in Schritt 3 – wenn es um die Generierung der Source bzw. Destination geht – benötigst du die SOURCE_DEFINITION_ID bzw. die DESTINATION_DEFINITION_ID aus der letzten Spalte.
Natürlich kannst du auch mit bestimmten Befehlen ganz gezielt nach einem bestimmten Source- oder Destination-Konnektor suchen. Für PostgreSQL sähe das beispielsweise so aus:
octavia list connectors sources | grep postgres
octavia list connectors destinations | grep postgres
2. Sources generieren
Wie die Source-Generierung funktioniert, beschreibe ich dir wieder anhand von PostgreSQL, weil das sehr verbreitet ist:
Mit dem oben genannten Octavia-List-Befehl für PostgreSQL wurde die SOURCE_DEFINITION_ID decd338e-5647-4c0b-adf4-da0e75f5a750 ermittelt. Diese ID und den Namen der PostgreSQL Source hängst du an den Befehl
octavia generate source
an.
In meinem Beispiel habe ich die PostgreSQL Source my_postgres_source mit diesem Befehl generiert:
octavia generate source decd338e-5647-4c0b-adf4-da0e75f5a750 my_postgres_source
Die Konsole zeigt daraufhin diesen Text an:
Mit diesem Befehl habe ich unterhalb von octavia_directory/sources das Verzeichnis my_postgres_source inklusive der Datei configuration.yaml erstellt. Bei configuration.yaml handelt es sich um das Konfigurations-Template, in dem notwendige Parameter wie Host, User, Password, Port etc. ergänzt werden müssen.
3. Destinations generieren
Auch die Destination-Generierung beschreibe ich dir wieder anhand von PostgreSQL.
Mit dem oben genannten Octavia-list-Befehl für PostgreSQL wurde die DESTINATION_DEFINITION_ID 25c5221d-dce2-4163-ade9-739ef790f503 ermittelt. Diese ID und den Namen der PostgreSQL Destination musst du an den Befehl octavia generate destination anhängen.
Im konkreten Beispiel zur Generierung der PostgreSQL Destination my_postgres_destination lautet der Befehl:
octavia generate destination 25c5221d-dce2-4163-ade9-739ef790f503 my_postgres_destination
Die Konsole zeigt daraufhin diesen Text an:
Mit diesem Befehl habe ich unterhalb von octavia_directory/destinations das Verzeichnis my_postgres_destination einschließlich der Datei configuration.yaml erstellt. Bei configuration.yaml handelt es sich auch hier wieder um das Konfigurations-Template, in dem notwendige Parameter wie Host, User, Password, Port etc. ergänzt werden müssen.
4. Connections generieren
Bevor du eine Connection zwischen neu angelegten Sources und Destinations anlegen kannst, musst du Source und Destination als Remote-Ressourcen auf der Airbyte Instanz anlegen. Dies machst du mit dem Befehl
octavia apply
Die Konsole zeigt daraufhin diesen Text an:
So werden Source und Destination anschließend auf der Weboberfläche angezeigt
Jetzt kannst du die Verbindung zwischen my_postgres_source und my_postgres_destination herstellen. Hierzu dient der Befehl
octavia generate connection
Als Source-Parameter gibst du den Pfad der Yaml-Datei für die Source-Konfiguration an und als Destination-Parameter den Pfad der Yaml-Datei für die Destination-Konfiguration. Dann nur noch einen Namen für deine Verbindung übergeben und fertig!
In meinem Beispiel sähe das so aus:
octavia generate connection --source sources/my_postgres_source/configuration.yaml --destination destinations/my_postgres_destination/configuration.yaml Postgres_2_Postgres
Mit diesem Befehl wird unterhalb von octavia_directory/connections das Verzeichnis postgres_2_postgres einschließlich des Konfigurations-Template configuration.yaml erstellt. In diesem Template sind sämtliche Default-Einstellungen aus der „leeren“ Connection-Konfigurationsmaske in der Weboberfläche gesetzt. Du musst das Template also noch an die Dataingestion-Anforderungen anpassen.
Dafür einfach in der Datei configuration.yaml unter anderem Folgendes konfigurieren:
- Frequenz der Datenreplikation einstellen (einmal täglich, alle 10 Minuten etc.)
- Destination Namespace angeben (z. B. Schema auf der Destination-Datenbank)
- Tabellen aktivieren, die aus der Source synchronisiert werden sollen. Achtung: Die Datei configuration.yaml enthält alle Tabellen der Source. Rein theoretisch können also alle Tabellen über eine Connection geladen werden, sofern bei jeder Tabelle selected=true gesetzt ist. Dies ist die Default-Einstellung in der YAML-Datei. Deshalb muss bei der Konfiguration genau geprüft werden, welche Tabellen über die Connection synchronisiert werden sollen.
- Sync-Mode bei selektierten Tabellen angeben
- Basic-Normalization aktivieren oder deaktivieren (ja/nein)
Nach Abschluss der Konfiguration übergibst du die Connection per octavia apply an die Airbyte Instanz. Dieser Schritt macht sie auf der Weboberfläche verfügbar. Durch den Apply-Befehl wird im Verzeichnis der Connection eine state.yaml-Datei erzeugt. Diese Datei enthält den Zustand der Konfiguration zum Zeitpunkt der Generierung in Form des Hashwerts configuration_hash und des Zeitstempels generation_timestamp.
Auf der Web-Oberfläche verfügbar
5. Import von Instanz-Ressourcen aus Airbyte ins Git-Verzeichnis
Du kannst dir den Import-Befehl zu Nutze machen, um sämtliche über die Weboberfläche fertig entwickelten Airbyte Verbindungen auf andere Airbyte Instanzen zu deployen. Der Import-Befehl überträgt die Konfigurationen aller Sources, Destinations und Connections von der Airbyte Instanz ins Git-Verzeichnis. Und zwar als YAML-Datei.
Du fragst dich, wofür das nötig ist? Stelle dir bitte folgendes Szenario vor:
In der Entwicklungsumgebung hast du alle Sources, Destinations und Connections über die Airbyte-Weboberfläche konfiguriert. Im Git Repository hast du das zugehörige Projekt mit der entsprechenden Ordner-Struktur (airbyte/octavia_directory) angelegt und ausgecheckt.
Octavia-cli ist installiert und durch Ausführung von octavia init im Verzeichnis octavia_directory legst du die in Schritt 1 beschriebenen Unterverzeichnisse an.
Jetzt führst du diesen Befehl aus:
octavia import all
Das machst du ebenfalls im Verzeichnis octavia_directory, wodurch zu jede Source, Destination und Connection unterhalb der Verzeichnisse sources, destinations und connections weitere Verzeichnisse mit den Namen der Sources, Destinations, und Connections erstellt werden.
In diesen Verzeichnissen findest du die Dateien configuration.yaml und state.yaml
Wichtig: Bevor du dein lokales Git-Repository in das Remote-Git-Repository eincheckst, müssen die Verbindungsdaten der configuration.yaml Dateien für Source und Destination geprüft werden, da die Passwörter nicht mit übertragen werden. Aus Sicherheitsgründen solltest du die Passwörter als Umgebungsvariablen abgelegen. So stehen sie während der Konfiguration zur Verfügung.
Wenn du die Verbindungsdaten angepasst hast, führst du im lokalen Git-Repository git add, git commit und git push aus, so dass die Airbyte Konfiguration ins Remote-Git-Repository eingecheckt wird.
Andere Entwickler:innen können deinen Entwicklungsstand nun aus dem Remote-Git-Repository auschecken und in ihrer lokalen Entwicklungsumgebung im Verzeichnis octavia_directory octavia apply ausführen. Dadurch werden die von dir entwickelten Airbyte Ressourcen auf den Airbyte Instanzen der anderen angelegt.
Fazit
Das Command-Line-Tool Octavia-cli erleichtert die Entwicklung und das Deployment:
- Airbyte-Instanz-Ressourcen können per octavia import ins Git übertragen und dort verwaltet werden.
- Mit dem Befehl octavia apply können Ressourcen, die in Git verwaltet werden, auf anderen Airbyte-Instanzen eingespielt werden.
- Außerdem helfen Templates bei der dynamischen Generierung von Sources, Destinations und Connections. Diese Templates müssen vorher allerdings mithilfe von Skripts, z. B. in Python, überarbeitet werden. Denn durch eine rein manuelle Konfiguration in der Datei hätte man gegenüber der Weboberfläche nichts gewonnen.
Leider ist auch Octavia-cli nicht frei von Stolpersteinen. So hat das Deployment der configuration.yaml-Dateien in meinem Beispielprojekt nur innerhalb der gleichen Airbyte Version funktioniert.
Ferner ist noch anzumerken, dass sich die Connection-ID ändert, wenn auf eine andere Airbyte-Instanz deployt wird. In meinem Beispiel wirkte sich das auf das Deployment des Modern Data Stack aus. Der bestand aus Airbyte, dbt und Airflow. Mit Airflow werden Airbyte und dbt-Prozesse orchestriert. Im Directed Acyclic Graph (DAG) von Airflow muss bei jedem Airbyte-Prozess die entsprechende Connection-ID angegeben werden. Als sich diese änderte, musste der DAG angepasst werden.
Damit wäre ich auch schon am Ende von Teil 2 angelangt. Im abschließenden Teil der Airbyte-Trilogie erwartet dich ein tieferer Einblick in den eigentlichen Data-Ingestion-Prozess.
Darum, stay tuned!
Teil 1: Daten integrieren mit Airbyte – Teil 1: Einführung & Installation
