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 Entwicklungsmodus erstellen, die Sie in den Ruhezustand versetzen können, wenn Sie sie nicht verwenden.

Informationen zum Composer Local Development CLI-Tool

Das Composer Local Development CLI-Tool optimiert die Apache Airflow-DAG-Entwicklung für Managed Airflow, indem eine Airflow-Umgebung lokal ausgeführt wird. 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 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 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>.

  • Ihr Computer muss genügend Speicherplatz haben, um Managed Airflow-Images zu speichern. 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 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, werden über das Konto ausgeführt, 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-Befehlszeilentool installieren

Klonen Sie das Repository für die Composer Local Development CLI:

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

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

pip install .

Je nach pip-Konfiguration befindet sich der Pfad, unter dem das Tool installiert ist, möglicherweise nicht in der Variablen PATH. 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 imitieren.

    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 der 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 der Initialisierung Ihrer Podman-Maschine, ob WSL 2 eine definierte Arbeitsspeicher- und Swap-Grenze hat. 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 Managed Airflow-Image erstellen

Führen Sie folgenden Befehl aus, um die verfügbaren Managed Airflow-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 Managed Airflow-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_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 durch den 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). Dieses Verzeichnis muss für die Container-Engine zugänglich sein.

    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-2.17.17-airflow-2.11.1 \
  example-local-environment

Lokale Airflow-Umgebung aus einer Managed Airflow-Umgebung erstellen

Aus einer Managed Airflow-Umgebung werden nur die folgenden Informationen übernommen:

  • In Ihrer Umgebung verwendete Versionen von Managed Airflow und Airflow.

  • 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, Verlauf der DAG-Ausführungen, 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 durch den 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). Dieses Verzeichnis muss für die Container-Engine zugänglich sein.

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

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 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 Airflow-Befehlszeilenbefehle in Ihrer lokalen Airflow-Umgebung ausführen.

So führen Sie einen Airflow-CLI-Befehl 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 Image-Version, DAG-Pfad und 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 ü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 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 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

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 in PEP-508 angegebenen Format entsprechen, wobei jede Anforderung in Kleinbuchstaben angegeben wird und aus dem Paketnamen mit optionalen Extras und Versionsspezifizierern besteht.

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.

Nachdem beispielsweise eine neue Managed Airflow-Version veröffentlicht wurde, können Sie Ihre Umgebung auf diese Version umstellen und die vorhandene lokale Airflow-Umgebungskonfiguration beibehalten. Ein weiteres Beispiel: Sie können innerhalb einer bestimmten Managed Airflow-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. 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, 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 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 Konfiguration der 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 ermitteln, ohne den Hilfetext aufrufen zu müssen.

Zsh

Generieren Sie das Vervollständigungsskript und binden Sie es in Ihre ~/.zshrc ein:

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

Fügen Sie es dann Ihrem ~/.zshrc hinzu:

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

Bash

Generieren Sie das Vervollständigungsskript und binden Sie es in Ihre ~/.bashrc ein:

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

Fügen Sie es dann Ihrem ~/.bashrc hinzu:

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

Fisch

Generieren Sie das Vervollständigungsskript und speichern Sie es im Fish-Vervollständigungs-Verzeichnis:

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

Mit Kubernetes-Clustern interagieren

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

export KUBECONFIG=~/.kube/config

Mit anderen Diensten auf dem Hostcomputer interagieren

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. Der Einfachheit halber konfiguriert das composer-dev-CLI-Tool das Netzwerk des Containers so, dass über den Domain-Alias host.docker.internal auf die Maschine 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 airflow-Nutzer 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, indem Sie COMPOSER_CONTAINER_RUN_AS_HOST_USER=True zu composer/<LOCAL_ENVIRONMENT_NAME>/variables.env hinzufügen. Diese Funktion ist unter Windows nicht verfügbar. Daher müssen Sie möglicherweise 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-Zugriff nicht automatisch Nutzer-Namespaces 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 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 den folgenden Befehl aus, um die neuen Namespace-Zuordnungsregeln 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 einen psycopg2.OperationalError generiert, der besagt, dass der Hostname für den Datenbankcontainer (your-environment-name) nicht übersetzt oder aufgelöst werden kann, ist das interne virtuelle Bridge-Netzwerk 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. Prüfen Sie das Netzwerk-DNS-Backend:

    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 während der Bereitstellung beheben

Wenn der Datenbank- oder Airflow-Container während der Bereitstellung sofort mit Pipe-Fehlern beendet wird, hat Podman möglicherweise ein Speicherlimit erreicht. Sie können versuchen, das Problem zu beheben, indem Sie die Speicher- und Auslagerungslimits 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 folgendem Befehl:

    podman machine start
    

Wenn Fehler auftreten, können Sie versuchen, die Windows-Virtualisierung und den Netzwerkstack 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