Lokale Airflow-Umgebung mit dem lokalen Composer-Befehlszeilentool ausführen

Cloud Composer 1 Cloud Composer 2

In diesem Abschnitt wird beschrieben, wie Sie eine lokale Airflow-Umgebung mit der lokalen Composer-Befehlszeile erstellen, konfigurieren und ausführen.

Über die Composer-Befehlszeile für die lokale Entwicklung

Das Composer-Befehlszeilentool für die lokale Entwicklung optimiert die Apache Airflow-DAG-Entwicklung für Cloud Composer 2 durch lokale Ausführung einer Airflow-Umgebung. Diese lokale Airflow-Umgebung verwendet ein Image einer bestimmten Cloud Composer-Version.

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

Sie können diese lokale Airflow-Umgebung zu Test- und Entwicklungszwecken verwenden, z. B. zum Testen von neuem DAG-Code, PyPI-Paketen oder Airflow-Konfigurationsoptionen.

Hinweise

  • Das Composer-CLI-Tool für die lokale Entwicklung unterstützt nur Cloud Composer 2-Images. Sie können eine beliebige Version von Cloud Composer 2 mit dem Composer-CLI-Tool für die lokale Entwicklung verwenden.

  • Das Composer-Befehlszeilentool für die lokale Entwicklung 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 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 dem Computer muss genügend Speicherplatz zum Speichern von Cloud Composer-Images vorhanden sein. Das Composer-Befehlszeilentool für die lokale Entwicklung speichert eine Image-Datei für jede Cloud Composer-Version. Wenn Sie beispielsweise zwei lokale Airflow-Umgebungen mit unterschiedlichen Cloud Composer-Versionen haben, speichert das Composer-Tool (Local Development CLI) zwei Cloud Composer-Images.

  • Das Composer-CLI-Tool für die lokale Entwicklung verwendet die 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 bei allen composer-dev-Befehlen mit Ausnahme von run-airflow-cmd weglassen.

  • Installieren Sie die Abhängigkeiten des Composer-Befehlszeilentools für die lokale Entwicklung:

  • Installieren Sie Docker. Docker muss auf dem lokalen System installiert sein und ausgeführt werden. Wenn Sie prüfen möchten, ob Docker ausgeführt wird, können Sie einen beliebigen Docker-Befehl wie docker ps ausführen.

Anmeldedaten konfigurieren

Falls noch nicht geschehen, fordern Sie neue Nutzeranmeldedaten für die Verwendung als Standardanmeldedaten für Anwendungen an:

gcloud auth application-default login

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

gcloud auth login

Alle API-Aufrufe, die vom Composer-CLI-Tool zur lokalen Entwicklung ausgeführt werden, und DAGs werden über das Konto ausgeführt, 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. Dies unterscheidet sich von Cloud Composer-Umgebungen, in denen das Dienstkonto einer Umgebung die Aufrufe durchführt.

Composer-Befehlszeile für die lokale Entwicklung installieren

Klonen Sie das Repository der Composer-Befehlszeile für die lokale Entwicklung:

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

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

pip install .

Abhängig von Ihrer pip-Konfiguration befindet sich der Pfad, in dem das Tool installiert wird, 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 einer bestimmten Cloud Composer-Version erstellen

Führen Sie folgenden Befehl aus, um die verfügbaren Versionen von Cloud Composer aufzulisten:

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

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

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

Weitere 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 Cloud Composer-Images.
  • PROJECT_ID durch die Projekt-ID.
  • WEB_SERVER_PORT durch den Port, den der Airflow-Webserver überwachen 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.6.6-airflow-2.6.3 \
  example-local-environment

Lokale Airflow-Umgebung aus einer Cloud Composer-Umgebung erstellen

Aus einer Cloud Composer-Umgebung werden nur die folgenden Informationen übernommen:

  • Image-Version (Versionen von Cloud Composer und Airflow, die in Ihrer Umgebung verwendet werden).
  • Liste der in Ihrer Umgebung installierten benutzerdefinierten PyPI-Pakete.

  • Kommentierte Liste mit Namen von Umgebungsvariablen, die in Ihrer Umgebung festgelegt wurden.

Andere Informationen und Konfigurationsparameter aus der Umgebung wie DAG-Dateien, der DAG-Ausführungsverlauf, Airflow-Variablen und Verbindungen werden nicht aus der 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
  • 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 folgenden Befehl 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 lokale Composer-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 folgenden Befehl 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 folgenden Befehl aus, um eine lokale Airflow-Umgebung zu beenden:

composer-dev stop LOCAL_ENVIRONMENT_NAME

DAGs hinzufügen und aktualisieren

DAG-Dateien 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 Befehl describe abrufen.

Ändern Sie die Dateien in diesem Verzeichnis, um DAGs hinzuzufügen und zu aktualisieren. Sie müssen Ihre lokale Airflow-Umgebung nicht neu starten.

Logs der lokalen Airflow-Umgebung ansehen

Sie können aktuelle Logs aus einem Docker-Container aufrufen, der Ihre lokale Airflow-Umgebung ausführt. Auf diese Weise können Sie containerbezogene Ereignisse überwachen und Airflow-Logs auf Fehler wie Abhängigkeitskonflikte prüfen, die durch die Installation von PyPI-Paketen verursacht werden.

Führen Sie folgenden Befehl aus, um Logs aus einem Docker-Container anzusehen, der Ihre lokale Airflow-Umgebung ausführt:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Lassen Sie das Argument --max-lines weg, um dem Logstream zu folgen:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Airflow-CLI-Befehl ausführen

Sie können Airflow-Befehlszeilenbefehle in Ihrer lokalen Airflow-Umgebung ausführen.

So führen Sie einen Airflow-Befehl aus der 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-Befehlszeilentool für die lokale Entwicklung 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 widersprüchliche PyPI-Paketanforderungen hinzufügen, meldet das Composer-CLI-Tool für die lokale Entwicklung Fehler beim Starten der lokalen Umgebung.

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

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 DAGs-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.

Images auflisten, die von lokalen Airflow-Umgebungen verwendet werden

Führen Sie folgenden Befehl aus, um alle Images aufzulisten, die von der lokalen Composer-Befehlszeile 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 entnommen: ./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 in diesen Verzeichnissen Dateien hinzu oder entfernen Sie sie. Docker leitet Dateiänderungen automatisch an Ihre lokale Airflow-Umgebung weiter.

Das Composer-Befehlszeilentool für die lokale Entwicklung unterstützt nicht die Angabe eines anderen Verzeichnisses für Daten und Plug-ins.

Umgebungsvariablen konfigurieren

Zum Konfigurieren von Umgebungsvariablen 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 Umgebungsvariablen). Verwenden Sie das Format AIRFLOW__SECTION__KEY, um die Airflow-Konfigurationsoptionen zu ändern. Weitere Informationen zu den verfügbaren Umgebungsvariablen finden Sie in der Referenz zur Airflow-Konfiguration.

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

Zum Installieren oder Entfernen von PyPI-Paketen ä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. Dabei werden alle Anforderungen in Kleinbuchstaben angegeben und bestehen aus dem Paketnamen mit optionalen Extras und Versionsspezifizierern.

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

Zu einem anderen Cloud Composer-Image wechseln

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

Nachdem beispielsweise eine neue Cloud Composer-Version veröffentlicht wurde, können Sie Ihre Umgebung auf die neue Version umstellen und die vorhandene Konfiguration der lokalen Airflow-Umgebung beibehalten. Ein weiteres Beispiel: Sie können innerhalb einer bestimmten Cloud Composer-Version zwischen verschiedenen Airflow-Versionen wechseln.

So ändern Sie das von Ihrer lokalen Airflow-Umgebung verwendete Image der Umgebung:

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

  2. Ändern Sie den Wert des Parameters composer_image_version. Zum Ansehen der verfügbaren Werte können Sie die verfügbaren Cloud Composer-Versionen 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, z. B. Logs und Konfigurationen, gespeichert haben.

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 folgenden Befehl aus, um alle Images zu löschen, die von der lokalen Composer-Befehlszeile heruntergeladen wurden:

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

Fehlerbehebung

Dieser Abschnitt enthält Lösungen für häufige Probleme.

Lokale Umgebung kann unter macOS nicht gestartet werden

Wenn Sie das Paket composer-dev in einem Verzeichnis installiert haben, in dem Docker nicht darauf 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 auch im Verzeichnis /opt installiert. Da Docker den Sandbox-Regeln von Apple entspricht, ist das Verzeichnis /opt standardmäßig nicht verfügbar. Außerdem kann es nicht über die UI hinzugefügt werden (Einstellungen > Ressourcen > Dateifreigabe).

In diesem Fall generiert das Composer-Befehlszeile für die lokale Entwicklung 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 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.