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.

Wenn Sie stattdessen eine Managed Airflow-Umgebung für Entwicklungszwecke ausführen möchten, sollten Sie eine Umgebung im Entwicklermodus erstellen, die Sie in den Ruhezustand versetzen können, wenn Sie sie nicht verwenden.

Composer Local Development CLI-Tool

Das Composer Local Development CLI-Tool optimiert die Entwicklung von Apache Airflow-DAGs für Managed Airflow, indem eine Airflow-Umgebung lokal ausgeführt wird. Diese lokale Airflow-Umgebung verwendet ein Airflow-Build-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 Umgebungsvariablennamen aus Ihrer Managed Airflow-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.

Hinweis

  • Das Composer Local Development-Befehlszeilentool unterstützt Airflow 3-Builds folgendermaßen:

    • Airflow 3.3.1 und höhere Versionen werden ab composer-3-airflow-3.3.1-build.0 unterstützt.
    • Airflow 3.2.2 wird ab composer-3-airflow-3.2.2-build.3 unterstützt.
    • Airflow 3.1.8 wird nicht unterstützt.
    • Frühere Airflow 3-Builds werden ab composer-3-airflow-3.1.0-build.8 unterstützt.

  • 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 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 des Pfads 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 CLI-Tool speichert eine Image-Datei für jeden Airflow-Build. Wenn Sie beispielsweise zwei lokale Airflow-Umgebungen mit unterschiedlichen Airflow-Builds haben, speichert das Composer Local Development-CLI-Tool zwei Airflow-Build-Images.

  • Das Composer Local Development CLI-Tool verwendet eine farbige 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 in allen composer-dev-Befehlen weglassen, mit Ausnahme von run-airflow-cmd.

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

  • Docker (Linux/macOS/Windows) oder Podman (Linux oder Windows) muss auf Ihrem Computer installiert sein und ausgeführt werden.

    Führen Sie einen beliebigen Docker- oder Podman-Befehlszeilenbefehl wie docker ps oder podman ps aus, um zu prüfen, ob Docker oder Podman ausgeführt wird. Alle Anleitungen gelten sowohl für Docker als auch für Podman, sofern nicht anders angegeben. Alle Docker-Befehle können durch entsprechende Podman-Befehle ersetzt werden.

Anmeldedaten konfigurieren

Falls noch nicht geschehen, rufen Sie neue Nutzeranmeldedaten für die Verwendung mit Standardanmeldedaten für Anwendungen ab:

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 ein DAG in Ihrer lokalen Airflow-Umgebung beispielsweise Inhalte eines 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 das Dienstkonto einer Umgebung die Aufrufe ausführt.

Composer Local Development CLI-Tool installieren

Klonen Sie das Repository der Composer Local Development CLI:

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 dieses Verzeichnis der Variablen PATH in Ihrem Betriebssystem hinzufügen.

(Podman) Podman konfigurieren

Wenn Sie Podman verwenden, gehen Sie so vor, um es zu konfigurieren:

Linux

  1. Aktivieren Sie den Podman-Nutzerdienst-Socket.

    Die composer-dev-Befehlszeile kommuniziert über Standard-Docker-API-Aufrufe. Sie müssen den Socket-Wrapper des Podman-Hintergrunddienstes auf Nutzerebene aktivieren, um den Docker-Daemon zu simulieren.

    Prüfen Sie zuerst, ob der Socket auf Nutzerebene bereits aktiv ist:

    systemctl --user is-active podman.socket

    Wenn der Befehl inactive oder failed zurückgibt, aktivieren und starten Sie den Socket:

    # Enable and start Podman's user-level systemd socket
systemctl --user enable --now podman.socket

  2. Konfigurieren Sie Umgebungsvariablen für Podman.

    Fügen Sie Ihrer Shell-Konfigurationsdatei (z. B. .bashrc oder .zshrc) den folgenden Befehl hinzu:

    export DOCKER_HOST="unix:///run/user/$UID/podman/podman.sock"

Windows

  1. Legen Sie die WSL 2-Konfiguration (.wslconfig) fest. Prüfen Sie vor dem Initialisieren Ihrer Podman-Maschine, ob für WSL 2 ein definierter Arbeitsspeicher und eine Swap-Grenze vorhanden sind. Ohne diese Funktion können Bereitstellungen mit mehreren Containern während der Image-Extraktion zu Speicherspitzen führen. Außerdem ist es wichtig, eine Einschränkung für die Anzahl gleichzeitiger Downloads festzulegen.

    Ändern oder erstellen Sie die Datei %USERPROFILE%\.wslconfig:

    [wsl2]
memory=4GB
swap=2GB

[registry]
max_concurrent_downloads = 2

  2. Initialisieren Sie in PowerShell die Podman-Maschine:

    podman machine init

  3. Starten Sie die Maschine:

    podman machine start

Nachdem Sie diese Schritte ausgeführt haben, können Sie mit composer-dev-CLI-Befehlen arbeiten. Das Tool erkennt Ihre Podman-Umgebung unter Windows automatisch und passt die Architekturzuordnungen an.

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

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

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

Führen Sie den folgenden Befehl 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 LOCAL_ENVIRONMENT_NAME \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  --plugins-path LOCAL_PLUGINS_PATH \
  --database DATABASE_ENGINE \
  --editable-dependencies EDITABLE_DEPENDENCY_PATH

Ersetzen Sie:

  • LOCAL_ENVIRONMENT_NAME durch den Namen dieser lokalen Airflow-Umgebung.
  • IMAGE_VERSION durch den Namen des Airflow-Build-Images.
  • PROJECT_ID durch die Projekt-ID.
  • WEB_SERVER_PORT: Der 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_PLUGINS_PATH durch den Pfad zu einem lokalen Verzeichnis, in dem sich die Plug-in-Dateien befinden.

  • DATABASE_ENGINE durch das zu verwendende Datenbankmodul. Mögliche Werte sind postgresql (Standard) und sqlite.

  • (Nur Linux/macOS) EDITABLE_DEPENDENCY_PATH mit dem Pfad zu einem lokalen Verzeichnis, das ein Python-Paket enthält, das im bearbeitbaren Modus installiert werden soll. Dieses Argument wird unter Windows nicht unterstützt.

    Pfade können absolut oder relativ sein (relative Pfade werden anhand des aktuellen Arbeitsverzeichnisses aufgelöst). Auf dieses Verzeichnis muss über die Container-Engine zugegriffen werden können.

    Wenn Sie mehrere bearbeitbare Pakete angeben möchten, wiederholen Sie die Option. Beispiel: --editable-dependencies ./pkg1 --editable-dependencies ./pkg2.

    Wenn Sie die Pakete mit pip install -e installieren, werden Änderungen an diesen Paketen im Projekt sofort übernommen.

Beispiel:

composer-dev create \
  --from-image-version composer-3-airflow-2.11.1-build.20 \
  example-local-environment

Lokale Airflow-Umgebung aus einer Managed Airflow-Umgebung erstellen

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

  • Spezifischer Airflow-Build, der von Ihrer Umgebung verwendet wird.

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

  • Kommentierte Liste der Namen von 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 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 \
    --plugins-path LOCAL_PLUGINS_PATH \
    --database DATABASE_ENGINE \
    --editable-dependencies EDITABLE_DEPENDENCY_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.
  • LOCAL_PLUGINS_PATH durch den Pfad zu einem lokalen Verzeichnis, in dem sich die Plug-in-Dateien befinden.

  • DATABASE_ENGINE durch das zu verwendende Datenbankmodul. Mögliche Werte sind postgresql (Standard) und sqlite.

  • (Nur Linux/macOS) EDITABLE_DEPENDENCY_PATH mit dem Pfad zu einem lokalen Verzeichnis, das ein Python-Paket enthält, das im bearbeitbaren Modus installiert werden soll. Dieses Argument wird unter Windows nicht unterstützt.

    Pfade können absolut oder relativ sein (relative Pfade werden anhand des aktuellen Arbeitsverzeichnisses aufgelöst). Auf dieses Verzeichnis muss über die Container-Engine zugegriffen werden können.

    Wenn Sie mehrere bearbeitbare Pakete angeben möchten, wiederholen Sie die Option. Beispiel: --editable-dependencies ./pkg1 --editable-dependencies ./pkg2.

    Wenn Sie die Pakete mit pip install -e installieren, werden Änderungen an diesen Paketen im Projekt sofort übernommen.

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 \
  --plugins-path ./example_directory/plugins \
  --database postgresql \
  --editable-dependencies ./pkg1

Lokale Airflow-Umgebung starten

Führen Sie den 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 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 den folgenden Befehl aus, um eine angehaltene 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 den folgenden Befehl 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.

Lokale Airflow-Umgebungslogs ansehen

Sie können sich die aktuellen Logs aus einem Docker-Container ansehen, in dem Ihre lokale Airflow-Umgebung ausgeführt wird. So 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 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 --max-lines-Argument weg:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Airflow-Befehlszeilenbefehl ausführen

Sie können Airflow-Befehlszeilenbefehle 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 in Konflikt stehende 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-CLI-Befehl ausführen oder die Verbindungsparameter in Umgebungsvariablen speichern. 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 ihren Status ab:

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.

Von lokalen Airflow-Umgebungen verwendete Images auflisten

Führen Sie den folgenden Befehl 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 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. Wenn Sie Airflow-Konfigurationsoptionen ändern möchten, verwenden Sie das Format AIRFLOW__SECTION__KEY. 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 Datei requirements.txt im Umgebungsverzeichnis: ./composer/<local_environment_name>/requirements.txt.

Anforderungen müssen dem Format entsprechen, das in PEP-508 angegeben ist. Jede Anforderung wird in Kleinbuchstaben angegeben und besteht aus dem Paketnamen mit optionalen Extras und Versionsspezifizierern.

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

Zu einem anderen Airflow-Build-Image wechseln

Sie können jedes Airflow-Build-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.

Nachdem beispielsweise ein neuer Airflow-Build veröffentlicht wurde, können Sie Ihre Umgebung so umstellen, dass sie diesen verwendet, 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. Wenn Sie die verfügbaren Werte aufrufen möchten, können Sie die verfügbaren Images auflisten.

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

Lokale Airflow-Umgebung löschen

Achtung: Achten Sie darauf, dass Sie alle erforderlichen Daten aus der Umgebung gespeichert haben, z. B. Logs 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 das Entfernen zu erzwingen.

Docker-Images löschen

Führen Sie den folgenden Befehl aus, um alle Images zu löschen, die vom Composer Local Development CLI-Tool heruntergeladen wurden:

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

Zusätzliche Konfiguration und Fehlerbehebung

In diesem Abschnitt finden Sie Lösungen für häufige Probleme und zusätzliche Konfigurationsschritte für die Interaktion des Composer Local Development CLI-Tools mit anderen Tools und Diensten.

Shell-Tab-Vervollständigung

Die composer-dev-Befehlszeile unterstützt die Tab-Vervollständigung für Bash-, Zsh- und Fish-Shells. Mit der Tab-Vervollständigung können Sie verfügbare Unterbefehle und Optionen finden, ohne den Hilfetext aufrufen zu müssen.

Zsh

Generieren Sie das Vervollständigungsskript und rufen Sie es in Ihrer ~/.zshrc auf:

_COMPOSER_DEV_COMPLETE=zsh_source composer-dev > ~/.composer-dev-complete.zsh

Fügen Sie sie dann Ihrer ~/.zshrc hinzu:

echo 'source ~/.composer-dev-complete.zsh' >> ~/.zshrc

Bash

Generieren Sie das Vervollständigungsskript und rufen Sie es in Ihrer ~/.bashrc auf:

_COMPOSER_DEV_COMPLETE=bash_source composer-dev > ~/.composer-dev-complete.bash

Fügen Sie sie dann Ihrer ~/.bashrc hinzu:

echo 'source ~/.composer-dev-complete.bash' >> ~/.bashrc

Fisch

Generieren Sie das Vervollständigungsskript und speichern Sie es im Fish-Verzeichnis für Vervollständigungen:

_COMPOSER_DEV_COMPLETE=fish_source composer-dev > ~/.config/fish/completions/composer-dev.fish

Mit Kubernetes-Clustern interagieren

Standardmäßig wird die Datei ~/.kube/config nicht eingebunden. Sie können den Pfad zur Kubernetes-Konfigurationsdatei angeben, indem Sie die Umgebungsvariable KUBECONFIG exportieren, bevor Sie die Umgebung starten.

export KUBECONFIG=~/.kube/config

Interaktion mit anderen Diensten auf dem Hostcomputer

Der localhost in einer Managed Airflow-Umgebung verweist auf den Container selbst, nicht auf den Hostcomputer, da das Netzwerk auf Docker- oder Podman-Containern funktioniert. Das composer-dev-Befehlszeilentool konfiguriert das Netzwerk des Containers so, dass über den Domainalias host.docker.internal auf den Computer zugegriffen werden kann. Beispiele:

  • Redis: Verwenden Sie host.docker.internal:6379 anstelle von localhost:6379, wenn Redis auf Port 6379 ausgeführt wird.
  • PostgreSQL: Verwenden Sie host.docker.internal:25432 anstelle von localhost:25432, wenn PostgreSQL auf Port 25432 ausgeführt wird.
  • Alle anderen Dienste: Folgen Sie diesem Muster: host.docker.internal:<PORT>

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, z. B. wenn Sie es mit der Standard-Homebrew-Konfiguration 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. Sie können sie auch 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.

Container-Nutzerzugriff auf bereitgestellte Dateien und Verzeichnisse vom Host

Standardmäßig wird der Container der Managed Airflow-Umgebung als Nutzer airflow mit der UID 999 ausgeführt. Der Nutzer muss Zugriff auf Dateien und Verzeichnisse haben, die vom Host bereitgestellt werden, z. B. ~/.config/gcloud/application_default_credentials.json.

Bekannte Probleme:

  • google.auth.exceptions.DefaultCredentialsError: Your default credentials were not found: kann generiert werden, wenn der Container mit dem Standardnutzer airflow (999) ausgeführt wird und für das Hostverzeichnis ~/.config/gcloud/ die Ausführungsberechtigung für den Nutzer fehlt.
  • [Errno 13] Permission denied: '/home/airflow/.config/gcloud/application_default_credentials.json': Kann generiert werden, wenn Sie den Container mit dem Standardnutzer airflow (999) ausführen und die hosts-Datei ~/.config/gcloud/application_default_credentials.json keine Leseberechtigung für den Nutzer hat.

Unter Linux oder macOS wird empfohlen, den Container als aktuellen Hostnutzer auszuführen. Fügen Sie dazu COMPOSER_CONTAINER_RUN_AS_HOST_USER=True zu composer/<LOCAL_ENVIRONMENT_NAME>/variables.env hinzu. Diese Funktion ist unter Windows nicht verfügbar. Möglicherweise müssen Sie die Berechtigungen der bereitgestellten Dateien und Verzeichnisse auf dem Host aktualisieren, um den Zugriff durch den Nutzer im Container zu ermöglichen.

(Podman) Berechtigungs- oder lchown-Fehler für Unternehmensnutzer beheben

Damit Podman ohne Root-Berechtigungen keine Nutzer-Namespaces automatisch zuweist, die sich mit Ihrer primären Unternehmens-Nutzer-ID überschneiden (was zu lchown: invalid argument- oder Berechtigungsfehlern führt), müssen Sie Ihre untergeordneten Bereiche manuell über den 4-Millionen-Block verschieben.

  1. Öffnen Sie /etc/subuid und /etc/subgid mit Root-Berechtigungen (z. B. sudo nano /etc/subuid).

  2. Aktualisieren Sie den Eintrag für Ihren Nutzernamen oder fügen Sie ihn hinzu, sodass er genau so aussieht:

    YOUR_USERNAME:4000000:3000000

  3. Speichern Sie beide Dateien und führen Sie Folgendes aus, um die neuen Namespace-Zuweisungsregeln auf Podman anzuwenden:

    podman system migrate

(Podman) Hängende Dateien und Fehler „Berechtigung verweigert“ entfernen

Wenn Sie Ihre subuid-Bereiche aktualisiert haben, während alte Container vorhanden waren, wird der Zugriff auf den eigenen Datencache für Ihren aktuellen Namespace blockiert.

Erzwingen Sie das Löschen des lokalen Speichergraphen mit Root-Berechtigungen auf Hostebene:

podman rm -fa
podman volume rm --all --force
podman system migrate

(Podman) DNS-Fehler beheben („Name oder Dienst nicht bekannt“)

Wenn Ihr Airflow-Container eine psycopg2.OperationalError generiert, in der angegeben wird, dass der Hostname für den Datenbankcontainer (your-environment-name) nicht übersetzt oder aufgelöst werden kann, ist das interne virtuelle Brückennetzwerk von Podman nicht synchron.

Löschen Sie die Laufzeitstatus und erzwingen Sie, dass netavark und aardvark-dns neue Routingtabellen generieren.

podman rm -fa
podman network prune --force

rm -rf /run/user/$UID/containers/*
rm -rf /run/user/$UID/netavark/*
rm -rf COMPOSER_LOCAL_DEV_PATH/composer/*

podman system migrate

(Podman) Engine-Status prüfen

So prüfen Sie, ob Podman Ihren Workflow ohne Root-Rechte verwaltet und Ihre Konfiguration nicht in System-Docker umgeht:

  1. DNS-Backend des Netzwerks prüfen:

    podman info | grep -A 3 -i "dns"

    Die Ausgabe muss backend: netavark und einen gültigen ausführbaren Pfad zu aardvark-dns enthalten.

  2. Überprüfen Sie die Zuordnung der Prozessverantwortlichen. Prüfen Sie bei laufender Umgebung den Inhaber des Hostprozesses:

    ps -ef | grep -i "postgres"

    In der Spalte ganz links sollte eine hohe UID-Nummer (z. B. 4000069) angezeigt werden, die dem Bereich Ihrer subuid-Zuordnung entspricht. Das beweist, dass die Ausführung vollständig ohne Root-Rechte erfolgt.

(Podman, Windows) Pipe-Fehler bei der Bereitstellung beheben

Wenn der Datenbank- oder Airflow-Container während der Bereitstellung sofort mit Pipe-Fehlern beendet wird, hat Podman möglicherweise ein Arbeitsspeicherlimit erreicht. Sie können versuchen, das Problem zu beheben, indem Sie die Speicher- und Swap-Limits in der Datei .wslconfig erhöhen:

  1. Beenden Sie Ihre Podman-Maschine und die virtuelle WSL 2-Maschine, indem Sie den folgenden Befehl in PowerShell ausführen:

    podman machine stop
wsl --shutdown

  2. Nehmen Sie Änderungen an der Datei %USERPROFILE%\.wslconfig vor, um die Swap- und Arbeitsspeicherlimits anzupassen. Weitere Informationen finden Sie in der WSL-Konfigurationsreferenz.

  3. Starten Sie Ihre Podman-Maschine mit dem folgenden Befehl:

    podman machine start

Wenn Fehler auftreten, können Sie versuchen, den Windows-Virtualisierungs- und Netzwerk-Stack zurückzusetzen. Öffnen Sie dazu PowerShell als Administrator und führen Sie folgenden Befehl aus:

Restart-Service -Name vmms -Force
Restart-Service -Name hns -Force
wsl --shutdown

Nächste Schritte