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

Managed Airflow (Gen 3) | Managed Airflow (Gen 2) | Managed Airflow (Legacy Gen 1)

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

Informationen zum Composer Local Development CLI-Tool

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

Sie können eine lokale Airflow-Umgebung basierend auf einer vorhandenen Managed Airflow-Umgebung erstellen. In diesem Fall übernimmt die lokale Airflow-Umgebung die Liste der installierten PyPI-Pakete und die Namen der Umgebungsvariablen aus Ihrer Managed Airflow-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.

Hinweis

  • Das Composer Local Development CLI-Tool erstellt lokale Airflow-Umgebungen in einem Verzeichnis, 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 Toolbefehle im Pfad aus, in dem Sie die lokale Umgebung ursprünglich erstellt haben. Alle Daten für die lokale Umgebung werden in einem Unterverzeichnis im Pfad gespeichert, in dem Sie die lokale Umgebung erstellt haben: ./composer/<local_environment_name>.

  • Auf Ihrem Computer muss genügend Speicherplatz zum Speichern von Managed Airflow-Images vorhanden sein. Das Composer Local Development CLI-Tool speichert eine Image-Datei für jede Managed Airflow-Version. Wenn Sie beispielsweise zwei lokale Airflow-Umgebungen mit unterschiedlichen Managed Airflow-Versionen haben, speichert das Composer Local Development CLI-Tool zwei Managed Airflow-Images.

  • Das Composer Local Development CLI-Tool verwendet eine farbige Ausgabe. Sie können die farbige Ausgabe mit der NO_COLOR=1 Variablen 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 außer 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

Rufen Sie neue Nutzeranmeldedaten für Standardanmeldedaten für Anwendungen ab, falls noch nicht geschehen, die 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, werden über das Konto ausgeführt, das Sie in der gcloud CLI verwenden. Wenn ein DAG in Ihrer lokalen Airflow-Umgebung beispielsweise Inhalte aus einem Cloud Storage-Bucket liest, muss dieses Konto Berechtigungen für den Zugriff auf den Bucket haben. Dies unterscheidet sich von Managed Airflow-Umgebungen, in denen die Aufrufe über das Dienstkonto einer Umgebung erfolgen.

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 Verzeichnis der obersten Ebene des geklonten Repositorys Folgendes aus:

pip install .

Je nach pip-Konfiguration befindet sich der Pfad, in dem das Tool installiert ist, möglicherweise nicht in der Variablen PATH. In diesem Fall zeigt pip eine Warnmeldung an. Sie können die Informationen aus dieser Warnmeldung verwenden, um dieses Verzeichnis der Variablen PATH in Ihrem Betriebssystem hinzuzufügen.

Lokale Airflow-Umgebung mit einem Managed Airflow-Image erstellen

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

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

Führen Sie Folgendes aus, um eine lokale Airflow-Umgebung mit Standardparametern zu erstellen:

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 Managed Airflow-Images.
  • PROJECT_ID durch die Projekt-ID.
  • WEB_SERVER_PORT durch den Port, an dem der Airflow-Webserver lauschen 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-2.17.2-airflow-2.11.1 \
  example-local-environment

Lokale Airflow-Umgebung aus einer Managed Airflow-Umgebung erstellen

Nur die folgenden Informationen werden aus einer Managed Airflow-Umgebung übernommen:

  • Versionen von Managed Airflow und Airflow, die in Ihrer Umgebung verwendet werden.

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

  • Liste der Namen von Umgebungsvariablen, die in Ihrer Umgebung festgelegt sind (mit Kommentarzeichen versehen).

Andere Informationen und Konfigurationsparameter aus der Umgebung, z. B. DAG-Dateien, DAG-Ausführungsprotokoll, Airflow-Variablen und -Verbindungen, werden nicht aus Ihrer Managed Airflow-Umgebung kopiert.

So erstellen Sie eine lokale Airflow-Umgebung aus einer vorhandenen Managed Airflow-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 Managed Airflow-Umgebung.
  • LOCATION durch die Region, in der sich die Managed Airflow-Umgebung befindet.
  • PROJECT_ID durch die Projekt-ID.
  • WEB_SERVER_PORT durch einen Port für den lokalen Airflow-Webserver.
  • 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 .

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

composer-dev restart LOCAL_ENVIRONMENT_NAME

Ersetzen Sie:

  • LOCAL_ENVIRONMENT_NAME durch den Namen einer lokalen Airflow-Umgebung.

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

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. Sie können das von Ihrer Umgebung verwendete Verzeichnis mit dem describe Befehl abrufen.

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

Logs der lokalen Airflow-Umgebung ansehen

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

Führen Sie Folgendes aus, um Logs aus einem Docker-Container anzusehen, in dem Ihre lokale Airflow-Umgebung ausgeführt wird:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Wenn Sie den Logstream verfolgen möchten, lassen Sie das Argument --max-lines weg:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Befehl der Airflow-Befehlszeile ausführen

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

So führen Sie einen Befehl der Airflow-Befehlszeile 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-Paket anforderungen, 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 Befehl der Airflow-Befehlszeile ausführen oder die Verbindungsparameter in Umgebungsvariablenspeichern. 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 ihren Status an:

composer-dev list

So rufen Sie eine Beschreibung einer bestimmten Umgebung und Details wie die Image-Version, den Pfad zu den DAGs 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.

Images auflisten, die von lokalen Airflow-Umgebungen verwendet werden

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

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 übernommen: ./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 auf 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 variables.env Datei 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, um die Änderungen zu übernehmen.

PyPI-Pakete installieren oder entfernen

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

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

Starten Sie Ihre lokale Airflow-Umgebung neu, um die Änderungen zu übernehmen.

Zu einem anderen Managed Airflow-Image wechseln

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

Nach der Veröffentlichung einer neuen Managed Airflow-Version können Sie beispielsweise Ihre Umgebung so umstellen, dass sie diese verwendet, und die vorhandene Konfiguration der lokalen Airflow-Umgebung beibehalten. Sie können auch zwischen verschiedenen Airflow-Versionen innerhalb einer bestimmten Managed Airflow-Version wechseln.

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. Wenn Sie die verfügbaren Werte sehen möchten, können Sie die verfügbaren Images auflisten.

  3. Starten Sie Ihre lokale Airflow-Umgebung neu, um die Änderungen zu übernehmen.

Lokale Airflow-Umgebung löschen

Achtung:Achten Sie darauf, 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

Führen Sie Folgendes aus, um alle vom Composer Local Development CLI-Tool heruntergeladenen Images zu löschen:

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

Fehlerbehebung

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

Lokale Umgebung unter macOS kann nicht gestartet werden

Wenn Sie das Paket composer-dev 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, z. B. wenn Sie es mit der Standardkonfiguration von Homebrew unter macOS installieren, wird das Paket composer-dev ebenfalls im Verzeichnis /opt installiert. Da Docker die Sandbox-Regeln von Apple einhält, ist das Verzeichnis /opt standardmäßig nicht verfügbar. Außerdem können Sie es 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 haben folgende Möglichkeiten:

  • Installieren Sie Python oder das Paket composer-dev 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