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.

Composer Local Development CLI-Tool

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

Sie können eine lokale Airflow-Umgebung auf Grundlage 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. zum Testen von neuem DAG-Code, PyPI-Paketen oder Airflow-Konfigurationsoptionen.

Hinweis

  • Mit dem Composer Local Development-CLI-Tool 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 Tool-Befehle 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 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-Befehlszeilentool zwei Managed Airflow-Images.

  • Das Composer Local Development CLI-Tool verwendet farbige Ausgaben. 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 mit Ausnahme von run-airflow-cmd weglassen.

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

  • 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-CLI- oder Podman-CLI-Befehl 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 ab, die als Standardanmeldedaten für Anwendungen 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, erfolgen über das Konto, 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. Das ist anders als bei Managed Airflow-Umgebungen, in denen das Dienstkonto einer Umgebung die Aufrufe ausführt.

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 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 aus dieser Warnmeldung können Sie das Verzeichnis der PATH-Variablen 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 emulieren.

    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. Konfigurieren Sie WSL2 (.wslconfig). Bevor Sie Ihre Podman-Maschine initialisieren, prüfen Sie, ob für WSL2 eine Speicher- und Swap-Grenze definiert ist. Andernfalls kann es bei Bereitstellungen mit mehreren Containern während der Bildextraktion zu Memory-Spikes kommen. Es ist auch wichtig, ein Limit für gleichzeitige Downloads festzulegen.

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

    [wsl2]
memory=4GB
swap=2GB

[registry]
max_concurrent_downloads = 2

  2. Initialisieren Sie die Podman-Maschine in PowerShell:

    podman machine init

  3. Gerät starten:

    podman machine start

Danach 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

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 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, an dem der Airflow-Webserver auf Anfragen warten 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 (Standardeinstellung) 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 im aktuellen Arbeitsverzeichnis aufgelöst). Auf dieses Verzeichnis muss die Container-Engine zugreifen 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 angewendet.

Beispiel:

composer-dev create \
  --from-image-version composer-2.17.11-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.

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

Andere Informationen und Konfigurationsparameter aus der Umgebung, z. B. DAG-Dateien, der 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 (Standardeinstellung) 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 im aktuellen Arbeitsverzeichnis aufgelöst). Auf dieses Verzeichnis muss die Container-Engine zugreifen 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 angewendet.

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

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

So starten Sie eine angehaltene lokale Airflow-Umgebung neu oder starten sie:

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

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

Lokale Airflow-Umgebungsprotokolle ansehen

Sie können sich die letzten Logs eines Docker-Containers ansehen, in dem Ihre lokale Airflow-Umgebung ausgeführt wird. So können Sie containerbezogene Ereignisse überwachen und in Airflow-Logs nach Fehlern wie Abhängigkeitskonflikten suchen, die durch die Installation von PyPI-Paketen verursacht werden.

So rufen Sie Logs aus einem Docker-Container auf, 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 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-Paketanforderungen, 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 Airflow-Befehlszeilenbefehl 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 zeigen ihren Status an:

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.

Bilder auflisten, die von lokalen Airflow-Umgebungen verwendet werden

Führen Sie Folgendes aus, um alle vom Composer Local Development CLI-Tool 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 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. 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, damit die Änderungen übernommen werden.

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.

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

Zu einem anderen Managed Airflow-Image wechseln

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

Nachdem beispielsweise eine neue Managed Airflow-Version veröffentlicht wurde, können Sie Ihre Umgebung so umstellen, dass sie diese verwendet, und die vorhandene lokale Airflow-Umgebungskonfiguration beibehalten. Sie können beispielsweise 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 der lokalen Umgebung: ./composer/<local_environment_name>/config.json.

  2. Ändern Sie den Wert des Parameters composer_image_version. Verfügbare 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 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

So löschen Sie alle Bilder, die mit dem 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 ermitteln, ohne den Hilfetext zu lesen.

Zsh

Generieren Sie das Vervollständigungsskript und führen Sie es in Ihrer ~/.zshrc aus:

_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 führen Sie es in Ihrer ~/.bashrc aus:

_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-Verzeichnis für Vervollständigungen:

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

Interaktion mit Kubernetes-Clustern

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 aufgrund der Funktionsweise des Netzwerks in Docker- oder Podman-Containern auf den Container selbst und nicht auf den Hostcomputer. Das CLI-Tool „composer-dev“ 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 an Port 6379 ausgeführt wird.
  • PostgreSQL: Verwenden Sie host.docker.internal:25432 anstelle von localhost:25432, wenn PostgreSQL auf Port 25432 ausgeführt wird.
  • Andere 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, wie es bei der Installation mit der Standardkonfiguration von Homebrew unter macOS der Fall ist, 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 sie 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 gemountet wurden, 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 in der Hostdatei ~/.config/gcloud/application_default_credentials.json die Leseberechtigung für den Nutzer fehlt.

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. 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 rootless Podman nicht automatisch Nutzer-Namespaces zuweist, die sich mit Ihrer primären geschäftlichen 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 oder fügen Sie Ihren Nutzernamen-Eintrag so hinzu, dass 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) Festsitzende Dateien entfernen und Fehler „Berechtigung verweigert“ beheben

Wenn Sie Ihre subuid-Bereiche aktualisiert haben, während alte Container vorhanden waren, kann Ihr aktueller Namespace nicht auf seinen eigenen Datencache zugreifen.

Erzwingen Sie das Löschen des lokalen Speicherdiagramms 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-Fehler generiert, der besagt, 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 saubere Routingtabellen neu 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-Berechtigungen verwaltet und Ihre Konfiguration nicht an das System-Docker weiterleitet:

  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 Prozessinhaberschaft. Prüfen Sie, während Ihre Umgebung ausgeführt wird, 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 Ihrem SubUID-Bereich entspricht. Das beweist, dass der Prozess vollständig ohne Root-Berechtigungen ausgeführt wird.

(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 Speicherlimit erreicht. Um das Problem zu beheben, können Sie versuchen, die Speicher- und Swap-Limits in der Datei .wslconfig zu erhöhen:

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

    podman machine stop
wsl --shutdown

  2. Nehmen Sie Änderungen in der Datei %USERPROFILE%\.wslconfig vor, um Ihre Swap- und Speicherlimits 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 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