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 Befehlszeilentool für die lokale Entwicklung von Composer eine lokale Airflow-Umgebung erstellen, konfigurieren und ausführen.

CLI-Tool für die lokale Entwicklung mit Composer

Mit dem Befehlszeilentool für die lokale Entwicklung von Composer wird die Entwicklung von Apache Airflow-DAGs für Cloud Composer optimiert, da eine Airflow-Umgebung lokal ausgeführt wird. Diese lokale Airflow-Umgebung verwendet ein Image einer bestimmten Cloud Composer-Version.

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

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

Hinweise

  • Mit dem Befehlszeilentool „Composer Local Development“ 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 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 unter dem Pfad gespeichert, unter dem Sie die lokale Umgebung erstellt haben: ./composer/<local_environment_name>.

  • Auf Ihrem Computer muss genügend Speicherplatz vorhanden sein, um Cloud Composer-Images zu speichern. Das CLI-Tool für die lokale Entwicklung von Composer speichert eine Imagedatei für jede Cloud Composer-Version. Wenn Sie beispielsweise zwei lokale Airflow-Umgebungen mit unterschiedlichen Cloud Composer-Versionen haben, speichert das CLI-Tool „Composer Local Development“ zwei Cloud Composer-Images.

  • Das lokale Entwicklungs-Befehlszeilentool von Composer verwendet eine farblich hervorgehobene Ausgabe. 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 aus allen composer-dev-Befehlen außer run-airflow-cmd weglassen.

  • Abhängigkeiten des Befehlszeilentools für die lokale Entwicklung mit Composer installieren:

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

Anmeldedaten konfigurieren

Rufen Sie neue Nutzeranmeldedaten für die Standardanmeldedaten für Anwendungen ab, falls Sie das noch nicht getan haben:

gcloud auth application-default login

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

gcloud auth login

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

Befehlszeilentool für die lokale Entwicklung mit Composer installieren

Klonen Sie das Repository der Composer Local Development-Befehlszeile:

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

Führen Sie im übergeordneten Verzeichnis des geklonten Repositorys Folgendes 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 dieses Verzeichnis der Variablen PATH in Ihrem Betriebssystem hinzufügen.

Lokale Airflow-Umgebung mit einer bestimmten Cloud Composer-Version erstellen

Führen Sie Folgendes aus, um eine Liste der verfügbaren Cloud Composer-Versionen aufzurufen:

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 Cloud Composer-Images.
  • PROJECT_ID durch die Projekt-ID.
  • WEB_SERVER_PORT mit dem 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.11.5-airflow-2.10.2 \
  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 benutzerdefinierten PyPI-Pakete, die in Ihrer Umgebung installiert sind.

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

Andere Informationen und Konfigurationsparameter aus der Umgebung, z. B. DAG-Dateien, DAG-Ausführungsverlauf, 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 den Namen der lokalen 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 mit einem 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

So starten Sie eine lokale Airflow-Umgebung:

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, wird mit dem Composer Local Development CLI-Tool der Docker-Container neu gestartet, in dem die Umgebung ausgeführt wird. Alle Airflow-Komponenten werden angehalten und wieder gestartet. Daher werden alle DAG-Ausführungen, die während eines Neustarts ausgeführt werden, als fehlgeschlagen gekennzeichnet .

Wenn Sie eine angehaltene lokale Airflow-Umgebung neu starten oder starten möchten, führen Sie Folgendes aus:

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 im Verzeichnis gespeichert, das Sie beim Erstellen Ihrer lokalen Airflow-Umgebung im Parameter --dags-path angegeben haben. Standardmäßig ist das ./composer/<local_environment_name>/dags. Sie können das von Ihrer Umgebung verwendete Verzeichnis mit dem Befehl describe 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 sich die letzten Logs aus einem Docker-Container ansehen, in dem Ihre lokale Airflow-Umgebung ausgeführt wird. So können Sie containerbezogene Ereignisse überwachen und Airflow-Protokolle auf Fehler wie Abhängigkeitskonflikte prüfen, die durch die Installation von PyPI-Paketen verursacht werden.

Führen Sie den folgenden Befehl aus, um Logs aus einem Docker-Container aufzurufen, 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 Argument --max-lines 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 CLI-Tool „Composer Local Development“ speichert Konfigurationsparameter für eine lokale Airflow-Umgebung, z. B. Umgebungsvariablen und PyPI-Paketvoraussetzungen, im Verzeichnis der lokalen Umgebung (./composer/<local_environment_name>).

Die Konfiguration wird angewendet, wenn eine lokale Airflow-Umgebung gestartet wird. Wenn Sie beispielsweise in Konflikt stehende PyPI-Paketanforderungen hinzufügen, meldet das Befehlszeilentool für die lokale Entwicklung von Composer beim Starten der lokalen Umgebung Fehler.

Airflow-Verbindungen werden in der Datenbank der lokalen Airflow-Umgebung gespeichert. Sie können sie durch Ausführen eines Airflow-Befehlszeilenbefehls oder durch Speichern der Verbindungsparameter in Umgebungsvariablen konfigurieren. Weitere Informationen zum Erstellen und Konfigurieren von Verbindungen finden Sie in der Airflow-Dokumentation unter Verbindungen verwalten.

Liste und Status lokaler Airflow-Umgebungen abrufen

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

composer-dev list

So beschreiben Sie eine bestimmte Umgebung und rufen Details wie die Imageversion, 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.

Liste der von lokalen Airflow-Umgebungen verwendeten Bilder

Führen Sie Folgendes aus, um alle vom CLI-Tool für die lokale Entwicklung von Composer 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 (./composer/<local_environment_name>/data und ./composer/<local_environment_name>/plugins) übernommen.

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 an Ihre lokale Airflow-Umgebung.

Das CLI-Tool für die lokale Entwicklung von Composer 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 pro 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

Um die Änderungen anzuwenden, starten Sie Ihre lokale Airflow-Umgebung neu.

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.

Um die Änderungen anzuwenden, starten Sie Ihre lokale Airflow-Umgebung neu.

Zu einem anderen Cloud Composer-Image wechseln

Sie können jedes Cloud Composer-Image mit dem CLI-Tool für die lokale Entwicklung von Composer verwenden und zwischen den Images wechseln. Dieser Ansatz unterscheidet sich vom Upgrade Ihrer Cloud Composer-Umgebung, da die Konfigurationsparameter Ihrer lokalen Airflow-Umgebung beim Starten angewendet werden.

Wenn beispielsweise eine neue Cloud Composer-Version veröffentlicht wird, können Sie Ihre Umgebung auf die neue Version umstellen und die vorhandene lokale Airflow-Umgebungskonfiguration beibehalten. Außerdem können Sie innerhalb einer bestimmten Cloud Composer-Version zwischen verschiedenen Airflow-Versionen wechseln.

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

  1. Bearbeiten Sie die Konfigurationsdatei für die lokale Umgebung: ./composer/<local_environment_name>/config.json.

  2. Ändern Sie den Wert des Parameters composer_image_version. Eine Liste der verfügbaren Werte finden Sie unter Verfügbare Cloud Composer-Versionen auflisten.

  3. Um die Änderungen anzuwenden, starten Sie Ihre lokale Airflow-Umgebung neu.

Lokale Airflow-Umgebung löschen

Achtung:Achten Sie darauf, dass Sie alle erforderlichen Daten aus der Umgebung gespeichert haben, z. B. Protokolle und Konfigurationen.

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 die Entfernung zu erzwingen.

Docker-Images löschen

Wenn Sie alle vom lokalen Entwicklungs-CLI-Tool von Composer heruntergeladenen Images löschen möchten, führen Sie Folgendes aus:

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 auf macOS kann 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, z. B. wenn Sie es unter macOS mit der Standard-Homebrew-Konfiguration installieren, wird das composer-dev-Paket 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 sie nicht über die Benutzeroberfläche hinzufügen (Einstellungen > Ressourcen > Dateifreigabe).

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