Lokale Airflow-Umgebung mit dem Befehlszeilentool für die lokale Entwicklung von Composer ausführen

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

In diesem Abschnitt wird beschrieben, wie Sie mit dem Composer Local Development-Befehlszeilentool eine lokale Airflow-Umgebung erstellen, konfigurieren und ausführen.

Composer Local Development CLI-Tool

Das Composer Local Development-Befehlszeilentool vereinfacht die Entwicklung von Apache Airflow-DAGs für Cloud Composer, indem es eine Airflow-Umgebung lokal ausführt. Diese lokale Airflow-Umgebung verwendet ein Airflow-Build-Image, das von einer bestimmten Cloud Composer-Version verwendet wird.

Sie können eine lokale Airflow-Umgebung auf Grundlage einer vorhandenen Cloud Composer-Umgebung erstellen. In diesem Fall übernimmt die lokale Airflow-Umgebung die Liste der installierten PyPI-Pakete und die Namen der Umgebungsvariablen aus Ihrer Cloud Composer-Umgebung.

Sie können diese lokale Airflow-Umgebung für Tests und Entwicklungszwecke verwenden, z. B. um neuen DAG-Code, PyPI-Pakete oder Airflow-Konfigurationsoptionen zu testen.

Hinweise

  • Mit dem Composer Local Development-CLI-Tool werden lokale Airflow-Umgebungen in einem Verzeichnis erstellt, in dem Sie den Befehl composer-dev create ausführen. Wenn Sie später auf Ihre lokale Airflow-Umgebung zugreifen möchten, führen Sie die Tool-Befehle in dem Pfad aus, in dem Sie die lokale Umgebung ursprünglich erstellt haben. Alle Daten für die lokale Umgebung werden in einem Unterverzeichnis unter dem Pfad gespeichert, in dem Sie die lokale Umgebung erstellt haben: ./composer/<local_environment_name>.

  • Auf Ihrem Computer muss genügend Speicherplatz zum Speichern von Airflow-Build-Images vorhanden sein. Das Composer Local Development-Befehlszeilentool speichert eine Bilddatei für jeden Airflow-Build. Wenn Sie beispielsweise zwei lokale Airflow-Umgebungen mit unterschiedlichen Airflow-Builds haben, speichert das Composer Local Development-Befehlszeilentool zwei Airflow-Build-Images.

  • Das CLI-Tool für die lokale Entwicklung von Composer verwendet farbige Ausgaben. Sie können die farbige Ausgabe mit der Variablen NO_COLOR=1 deaktivieren: NO_COLOR=1 composer-dev <other commands>.

  • Wenn Sie nur eine lokale Umgebung haben, können Sie den Namen der lokalen Umgebung in allen composer-dev-Befehlen mit Ausnahme von run-airflow-cmd weglassen.

  • Installieren Sie die Abhängigkeiten des Composer Local Development CLI-Tools:

  • Installieren Sie Docker. Docker muss auf dem lokalen System installiert sein und ausgeführt werden. Um zu prüfen, ob Docker ausgeführt wird, können Sie einen beliebigen Docker-CLI-Befehl ausführen, z. B. docker ps.

Anmeldedaten konfigurieren

Falls noch nicht geschehen, rufen Sie neue Nutzeranmeldedaten ab, die als Standardanmeldedaten für Anwendungen verwendet werden sollen:

gcloud auth application-default login

Melden Sie sich mit Ihrem Google-Konto in der gcloud CLI an:

gcloud auth login

Alle API-Aufrufe, die vom Composer Local Development CLI-Tool und von DAGs ausgeführt werden, erfolgen über das Konto, das Sie in der gcloud CLI verwenden. Wenn beispielsweise ein DAG in Ihrer lokalen Airflow-Umgebung Inhalte eines Cloud Storage-Bucket liest, muss dieses Konto Berechtigungen für den Zugriff auf den Bucket haben. Das unterscheidet sich von Cloud Composer-Umgebungen, in denen das Dienstkonto einer Umgebung die Aufrufe ausführt.

Composer Local Development CLI-Tool installieren

Klonen Sie das Composer Local Development CLI-Repository:

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

Führen Sie im obersten Verzeichnis des geklonten Repositorys folgenden Befehl aus:

pip install .

Je nach pip-Konfiguration ist der Pfad, unter dem das Tool installiert ist, möglicherweise nicht in der Variablen PATH enthalten. In diesem Fall wird in pip eine Warnmeldung angezeigt. Anhand der Informationen in dieser Warnmeldung können Sie das Verzeichnis der PATH-Variable in Ihrem Betriebssystem hinzufügen.

Lokale Airflow-Umgebung mit einem Airflow-Build-Image erstellen

Führen Sie Folgendes aus, um die verfügbaren Airflow-Build-Images aufzulisten:

composer-dev list-available-versions --include-past-releases --limit 10

So erstellen Sie eine lokale Airflow-Umgebung mit Standardparametern:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

Sonstige Parameter:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

Ersetzen Sie:

  • IMAGE_VERSION durch den Namen des Airflow-Build-Images.
  • PROJECT_ID durch die Projekt-ID.
  • WEB_SERVER_PORT durch den Port, an dem der Airflow-Webserver auf Anfragen warten muss.
  • LOCAL_DAGS_PATH durch den Pfad zu einem lokalen Verzeichnis, in dem sich die DAG-Dateien befinden.
  • LOCAL_ENVIRONMENT_NAME durch den Namen dieser lokalen Airflow-Umgebung.

Beispiel:

composer-dev create \
  --from-image-version composer-3-airflow-2.10.5-build.12 \
  example-local-environment

Lokale Airflow-Umgebung aus einer Cloud Composer-Umgebung erstellen

Nur die folgenden Informationen werden aus einer Cloud Composer-Umgebung übernommen:

  • Die spezifische Airflow-Version, die von Ihrer Umgebung verwendet wird.

  • Liste der benutzerdefinierten PyPI-Pakete, die in Ihrer Umgebung installiert sind.

  • Auskommentierte Liste der Namen der Umgebungsvariablen, die in Ihrer Umgebung festgelegt sind.

Andere Informationen und Konfigurationsparameter aus der Umgebung, z. B. DAG-Dateien, der Verlauf von DAG-Ausführungen, Airflow-Variablen und Verbindungen, werden nicht aus Ihrer Cloud Composer-Umgebung kopiert.

So erstellen Sie eine lokale Airflow-Umgebung aus einer vorhandenen Cloud Composer-Umgebung:

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH

Ersetzen Sie:

  • LOCAL_ENVIRONMENT_NAME durch einen Namen für die lokale Airflow-Umgebung.
  • ENVIRONMENT_NAME durch den Namen der Cloud Composer-Umgebung.
  • LOCATION durch die Region, in der sich die Cloud Composer-Umgebung befindet.
  • PROJECT_ID durch die Projekt-ID.
  • WEB_SERVER_PORT durch einen Port für den lokalen Airflow-Webserver.
  • Ersetzen Sie LOCAL_DAGS_PATH durch einen Pfad zu einem lokalen Verzeichnis, in dem sich die DAGs befinden.

Beispiel:

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

Lokale Airflow-Umgebung starten

Führen Sie Folgendes aus, um eine lokale Airflow-Umgebung zu starten:

composer-dev start LOCAL_ENVIRONMENT_NAME

Ersetzen Sie:

  • LOCAL_ENVIRONMENT_NAME durch den Namen einer lokalen Airflow-Umgebung.

Lokale Airflow-Umgebung beenden oder neu starten

Wenn Sie eine lokale Airflow-Umgebung neu starten, startet das Composer Local Development CLI-Tool den Docker-Container neu, in dem die Umgebung ausgeführt wird. Alle Airflow-Komponenten werden beendet und neu gestartet. Daher werden alle DAG-Ausführungen, die während eines Neustarts ausgeführt werden, als fehlgeschlagen markiert .

So starten Sie eine angehaltene lokale Airflow-Umgebung neu oder starten sie:

composer-dev restart LOCAL_ENVIRONMENT_NAME

Ersetzen Sie:

  • LOCAL_ENVIRONMENT_NAME durch den Namen einer lokalen Airflow-Umgebung.

So beenden Sie eine lokale Airflow-Umgebung:

composer-dev stop LOCAL_ENVIRONMENT_NAME

DAGs hinzufügen und aktualisieren

DAGs werden in dem Verzeichnis gespeichert, das Sie beim Erstellen Ihrer lokalen Airflow-Umgebung im Parameter --dags-path angegeben haben. Standardmäßig ist dieses Verzeichnis ./composer/<local_environment_name>/dags. Mit dem Befehl describe können Sie das von Ihrer Umgebung verwendete Verzeichnis abrufen.

Wenn Sie DAGs hinzufügen und aktualisieren möchten, ändern Sie Dateien in diesem Verzeichnis. Sie müssen Ihre lokale Airflow-Umgebung nicht neu starten.

Lokale Airflow-Umgebungsprotokolle ansehen

Sie können sich die letzten Logs eines Docker-Containers ansehen, in dem Ihre lokale Airflow-Umgebung ausgeführt wird. So können Sie containerbezogene Ereignisse überwachen und in Airflow-Logs nach Fehlern suchen, z. B. nach Abhängigkeitskonflikten, die durch die Installation von PyPI-Paketen verursacht werden.

So rufen Sie Logs aus einem Docker-Container auf, in dem Ihre lokale Airflow-Umgebung ausgeführt wird:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Wenn Sie dem Logstream folgen möchten, lassen Sie das --max-lines-Argument weg:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Airflow-Befehlszeilenbefehl ausführen

Sie können Befehle der Airflow-Befehlszeile in Ihrer lokalen Airflow-Umgebung ausführen.

So führen Sie einen Airflow-Befehlszeilenbefehl aus:

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

Beispiel:

composer-dev run-airflow-cmd example-local-environment dags list -o table

Lokale Airflow-Umgebungen konfigurieren

Das Composer Local Development-CLI-Tool speichert Konfigurationsparameter für eine lokale Airflow-Umgebung, z. B. Umgebungsvariablen und PyPI-Paketanforderungen, im Verzeichnis der lokalen Umgebung (./composer/<local_environment_name>).

Die Konfiguration wird angewendet, wenn eine lokale Airflow-Umgebung gestartet wird. Wenn Sie beispielsweise inkompatible PyPI-Paketanforderungen hinzufügen, meldet das Composer Local Development CLI-Tool Fehler, wenn Sie die lokale Umgebung starten.

Airflow-Verbindungen werden in der Datenbank der lokalen Airflow-Umgebung gespeichert. Sie können sie konfigurieren, indem Sie einen Airflow-Befehlszeilenbefehl ausführen oder die Verbindungsparameter in Umgebungsvariablen speichern. Weitere Informationen zum Erstellen und Konfigurieren von Verbindungen finden Sie in der Airflow-Dokumentation unter Managing connections.

Liste und Status lokaler Airflow-Umgebungen abrufen

So listen Sie alle verfügbaren lokalen Airflow-Umgebungen auf und zeigen deren Status an:

composer-dev list

So beschreiben Sie eine bestimmte Umgebung und rufen Details wie die Image-Version, den DAG-Pfad und die Webserver-URL einer Umgebung ab:

composer-dev describe LOCAL_ENVIRONMENT_NAME

Ersetzen Sie:

  • LOCAL_ENVIRONMENT_NAME durch den Namen der lokalen Airflow-Umgebung.

Bilder auflisten, die von lokalen Airflow-Umgebungen verwendet werden

Führen Sie Folgendes aus, um alle vom Composer Local Development CLI-Tool verwendeten Images aufzulisten:

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

Plug-ins installieren und Daten ändern

Plug-ins und Daten für eine lokale Airflow-Umgebung werden aus dem Verzeichnis der lokalen Umgebung abgerufen: ./composer/<local_environment_name>/data und ./composer/<local_environment_name>/plugins.

Wenn Sie den Inhalt der Verzeichnisse /data und /plugins ändern möchten, fügen Sie Dateien in diesen Verzeichnissen hinzu oder entfernen Sie sie. Docker überträgt Dateiänderungen automatisch in Ihre lokale Airflow-Umgebung.

Das Composer Local Development CLI-Tool unterstützt nicht die Angabe eines anderen Verzeichnisses für Daten und Plug-ins.

Umgebungsvariablen konfigurieren

Wenn Sie Umgebungsvariablen konfigurieren möchten, bearbeiten Sie die Datei variables.env im Umgebungsverzeichnis: ./composer/<local_environment_name>/variables.env.

Die Datei variables.env muss Schlüssel/Wert-Definitionen enthalten, eine Zeile für jede Umgebungsvariable. Verwenden Sie das Format AIRFLOW__SECTION__KEY, um Airflow-Konfigurationsoptionen zu ändern. Weitere Informationen zu den verfügbaren Umgebungsvariablen finden Sie in der Airflow-Konfigurationsreferenz.

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

Starten Sie Ihre lokale Airflow-Umgebung neu, damit die Änderungen übernommen werden.

PyPI-Pakete installieren oder entfernen

Wenn Sie PyPI-Pakete installieren oder entfernen möchten, ändern Sie die Datei requirements.txt im Umgebungsverzeichnis: ./composer/<local_environment_name>/requirements.txt.

Die Anforderungen müssen dem in PEP-508 angegebenen Format entsprechen, wobei jede Anforderung in Kleinbuchstaben angegeben wird und aus dem Paketnamen mit optionalen Extras und Versionsangaben besteht.

Starten Sie Ihre lokale Airflow-Umgebung neu, damit die Änderungen übernommen werden.

Zu einem anderen Airflow-Build-Image wechseln

Sie können ein beliebiges Airflow-Build-Image mit dem Composer Local Development-CLI-Tool verwenden und zwischen den Images wechseln. Dieser Ansatz unterscheidet sich vom Aktualisieren Ihrer Cloud Composer-Umgebung, da Konfigurationsparameter Ihrer lokalen Airflow-Umgebung beim Start angewendet werden.

Nachdem beispielsweise ein neuer Airflow-Build veröffentlicht wurde, können Sie Ihre Umgebung so umstellen, dass er verwendet wird, und die vorhandene lokale Airflow-Umgebungskonfiguration beibehalten.

So ändern Sie das Image der Umgebung, das von Ihrer lokalen Airflow-Umgebung verwendet wird:

  1. Bearbeiten Sie die Konfigurationsdatei der lokalen Umgebung: ./composer/<local_environment_name>/config.json.

  2. Ändern Sie den Wert des Parameters composer_image_version. Verfügbare Images auflisten

  3. Starten Sie Ihre lokale Airflow-Umgebung neu, damit die Änderungen übernommen werden.

Lokale Airflow-Umgebung löschen

Achtung:Sorgen Sie dafür, dass Sie alle erforderlichen Daten aus der Umgebung gespeichert haben, z. B. Logs und Konfiguration.

Führen Sie den folgenden Befehl aus, um eine lokale Airflow-Umgebung zu löschen:

composer-dev remove LOCAL_ENVIRONMENT_NAME

Wenn die Umgebung ausgeführt wird, fügen Sie das Flag --force hinzu, um das Entfernen zu erzwingen.

Docker-Images löschen

So löschen Sie alle Bilder, die mit dem Composer Local Development CLI-Tool heruntergeladen wurden:

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

Fehlerbehebung

In diesem Abschnitt finden Sie Lösungen für häufig auftretende Probleme.

Lokale Umgebung kann unter MacOS nicht gestartet werden

Wenn Sie das composer-dev-Paket in einem Verzeichnis installiert haben, auf das Docker nicht zugreifen kann, wird Ihre lokale Umgebung möglicherweise nicht gestartet.

Wenn Python beispielsweise im Verzeichnis /opt installiert ist, etwa wenn Sie es mit der Standardkonfiguration von Homebrew unter MacOS installieren, wird das Paket composer-dev ebenfalls im Verzeichnis /opt installiert. Da Docker den Sandbox-Regeln von Apple entspricht, ist das Verzeichnis /opt standardmäßig nicht verfügbar. Außerdem können Sie sie nicht über die Benutzeroberfläche hinzufügen (Einstellungen > Ressourcen > Dateifreigabe).

In diesem Fall generiert das Composer Local Development CLI-Tool eine Fehlermeldung, die dem folgenden Beispiel ähnelt:

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

Sie können eine der folgenden Lösungen verwenden:

  • Installieren Sie Python oder das composer-dev-Paket in einem anderen Verzeichnis, damit Docker auf das Paket zugreifen kann.
  • Bearbeiten Sie die Datei ~/Library/Group\ Containers/group.com.docker/settings.json manuell und fügen Sie /opt zu filesharingDirectories hinzu.

Nächste Schritte