Esegui un ambiente Airflow locale con lo strumento CLI Composer Local Development

Managed Airflow (terza generazione) | Managed Airflow (seconda generazione) | Managed Airflow (prima generazione legacy)

Questa sezione descrive come creare, configurare ed eseguire un ambiente Airflow locale utilizzando lo strumento CLI di sviluppo locale di Composer.

Informazioni sullo strumento CLI di sviluppo locale di Composer

Lo strumento CLI di sviluppo locale di Composer semplifica lo sviluppo di DAG Apache Airflow per Airflow gestito eseguendo un ambiente Airflow in locale. Questo ambiente Airflow locale utilizza un'immagine di build di Airflow utilizzata da una specifica versione di Airflow gestito.

Puoi creare un ambiente Airflow locale basato su un ambiente Airflow gestito esistente. In questo caso, l'ambiente Airflow locale prende l'elenco dei pacchetti PyPI installati e i nomi variabile di ambiente dal tuo ambiente Airflow gestito.

Puoi utilizzare questo ambiente Airflow locale per scopi di test e sviluppo, ad esempio per testare nuovo codice DAG, pacchetti PyPI o opzioni di configurazione di Airflow.

Prima di iniziare

  • Lo strumento CLI di sviluppo locale di Composer supporta le build di Airflow 3 a partire da composer-3-airflow-3.1.0-build.8.

  • Lo strumento CLI di sviluppo locale di Composer crea ambienti Airflow locali in una directory in cui esegui il comando composer-dev create. Per accedere all'ambiente Airflow locale in un secondo momento, esegui i comandi dello strumento nel percorso in cui hai creato inizialmente l'ambiente locale. Tutti i dati dell' ambiente locale vengono archiviati in una sottodirectory nel percorso in cui hai creato l'ambiente locale: ./composer/<local_environment_name>.

  • Il computer deve avere spazio su disco sufficiente per archiviare le immagini di build di Airflow. Lo strumento CLI di sviluppo locale di Composer archivia un file immagine per ogni build di Airflow. Ad esempio, se hai due ambienti Airflow locali con build di Airflow diverse, lo strumento CLI di sviluppo locale di Composer archivia due immagini di build di Airflow.

  • Lo strumento CLI di sviluppo locale di Composer utilizza un output colorato. Puoi disattivare l'output colorato con la variabile NO_COLOR=1: NO_COLOR=1 composer-dev <other commands>.

  • Se hai un solo ambiente locale, puoi omettere il nome dell'ambiente locale da tutti i comandi composer-dev, ad eccezione di run-airflow-cmd.

  • Installa le dipendenze dello strumento CLI di sviluppo locale di Composer:

  • Installa Docker. Docker deve essere installato ed essere in esecuzione nel sistema locale. Per verificare che Docker sia in esecuzione, puoi eseguire qualsiasi comando dell'interfaccia a riga di comando di Docker, ad esempio docker ps.

Configura le credenziali

Se non l'hai già fatto, recupera le nuove credenziali utente da utilizzare per le Credenziali predefinite dell'applicazione:

gcloud auth application-default login

Accedi a gcloud CLI utilizzando il tuo Account Google:

gcloud auth login

Tutte le chiamate API eseguite dallo strumento CLI di sviluppo locale di Composer e dai DAG vengono eseguite dall'account che utilizzi in gcloud CLI. Ad esempio, se un DAG nel tuo ambiente Airflow locale legge i contenuti di un bucket Cloud Storage, questo account deve disporre delle autorizzazioni per accedere al bucket. Questo è diverso dagli ambienti Managed Airflow, in cui le chiamate vengono effettuate dal account di servizio di un ambiente.

Installa lo strumento CLI di sviluppo locale di Composer

Clona il repository dello strumento CLI di sviluppo locale di Composer:

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

Nella directory di primo livello del repository clonato, esegui:

pip install .

A seconda della configurazione di pip, il percorso in cui è installato lo strumento potrebbe non essere nella variabile PATH. In questo caso, pip visualizza un messaggio di avviso. Puoi utilizzare le informazioni di questo messaggio di avviso per aggiungere questa directory alla variabile PATH nel tuo sistema operativo.

Crea un ambiente Airflow locale con un'immagine di build di Airflow

Per elencare le immagini di build di Airflow disponibili, esegui:

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

Per creare un ambiente Airflow locale con i parametri predefiniti, esegui:

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

Altri parametri:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

Sostituisci:

  • IMAGE_VERSION con il nome dell'immagine di build di Airflow.
  • PROJECT_ID con l'ID progetto.
  • WEB_SERVER_PORT con la porta su cui deve essere in ascolto il server web di Airflow.
  • LOCAL_DAGS_PATH con il percorso di una directory locale in cui si trovano i file DAG.
  • LOCAL_ENVIRONMENT_NAME con il nome di questo ambiente Airflow locale.

Esempio:

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

Crea un ambiente Airflow locale da un ambiente Airflow gestito

Da un ambiente Airflow gestito vengono prese solo le seguenti informazioni:

  • Build di Airflow specifica utilizzata dal tuo ambiente.

  • Elenco dei pacchetti PyPI personalizzati installati nel tuo ambiente.

  • Elenco commentato dei nomi delle variabili di ambiente impostate nel tuo ambiente.

Altre informazioni e parametri di configurazione dell'ambiente, come i file DAG, la cronologia di esecuzione dei DAG, le variabili Airflow e le connessioni, non vengono copiati dal tuo ambiente Airflow gestito.

Per creare un ambiente Airflow locale da un ambiente Airflow gestito esistente:

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

Sostituisci:

  • LOCAL_ENVIRONMENT_NAME con un nome per l'ambiente Airflow locale.
  • ENVIRONMENT_NAME con il nome dell'ambiente Airflow gestito.
  • LOCATION con la regione in cui si trova l'ambiente Airflow gestito.
  • PROJECT_ID con l'ID progetto.
  • WEB_SERVER_PORT con una porta per il server web di Airflow locale.
  • LOCAL_DAGS_PATH con un percorso di una directory locale in cui si trovano i DAG.

Esempio:

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

Avvia un ambiente Airflow locale

Per avviare un ambiente Airflow locale, esegui:

composer-dev start LOCAL_ENVIRONMENT_NAME

Sostituisci:

  • LOCAL_ENVIRONMENT_NAME con il nome di un ambiente Airflow locale.

Arresta o riavvia un ambiente Airflow locale

Quando riavvii un ambiente Airflow locale, lo strumento CLI di sviluppo locale di Composer riavvia il container Docker in cui è in esecuzione l'ambiente. Tutti i componenti di Airflow vengono arrestati e riavviati. Di conseguenza, tutte le esecuzioni dei DAG eseguite durante un riavvio vengono contrassegnate come non riuscite .

Per riavviare o avviare un ambiente Airflow locale arrestato, esegui:

composer-dev restart LOCAL_ENVIRONMENT_NAME

Sostituisci:

  • LOCAL_ENVIRONMENT_NAME con il nome di un ambiente Airflow locale.

Per arrestare un ambiente Airflow locale, esegui:

composer-dev stop LOCAL_ENVIRONMENT_NAME

Aggiungi e aggiorna i DAG

I DAG vengono archiviati nella directory che hai specificato nel parametro --dags-path quando hai creato l'ambiente Airflow locale. Per impostazione predefinita, questa directory è ./composer/<local_environment_name>/dags. Puoi recuperare la directory utilizzata dal tuo ambiente con il describe comando.

Per aggiungere e aggiornare i DAG, modifica i file in questa directory. Non è necessario riavviare l'ambiente Airflow locale.

Visualizza i log dell'ambiente Airflow locale

Puoi visualizzare i log recenti da un container Docker che esegue il tuo ambiente Airflow locale. In questo modo, puoi monitorare gli eventi correlati ai container e controllare i log di Airflow per verificare la presenza di errori, ad esempio conflitti di dipendenze causati dall'installazione di pacchetti PyPI.

Per visualizzare i log di un container Docker che esegue il tuo ambiente Airflow locale, esegui:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Per seguire lo stream di log, ometti l'argomento --max-lines:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Esegui un comando dell'interfaccia a riga di comando di Airflow

Puoi eseguire i comandi dell'interfaccia a riga di comando di Airflow nel tuo ambiente Airflow locale.

Per eseguire un comando dell'interfaccia a riga di comando di Airflow:

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

Esempio:

composer-dev run-airflow-cmd example-local-environment dags list -o table

Configura gli ambienti Airflow locali

Lo strumento CLI di sviluppo locale di Composer archivia i parametri di configurazione per un ambiente Airflow locale, come le variabili di ambiente e i requisiti dei pacchetti PyPI nella directory dell'ambiente locale (./composer/<local_environment_name>).

La configurazione viene applicata all'avvio di un ambiente Airflow locale. Ad esempio, se aggiungi requisiti di pacchetti PyPI in conflitto, lo strumento CLI di sviluppo locale di Composer segnala errori all'avvio dell'ambiente locale.

Le connessioni Airflow vengono archiviate nel database dell'ambiente Airflow locale. Puoi configurarli eseguendo un comando dell'interfaccia a riga di comando di Airflow o memorizzando i parametri di connessione nelle variabili di ambiente. Per saperne di più sui modi per creare e configurare le connessioni, consulta Gestione delle connessioni nella documentazione di Airflow.

Recupera un elenco e lo stato degli ambienti Airflow locali

Per elencare tutti gli ambienti Airflow locali disponibili e visualizzarne lo stato:

composer-dev list

Per descrivere un ambiente specifico e ottenere dettagli come la versione dell'immagine, il percorso dei DAG e l'URL del server web di un ambiente:

composer-dev describe LOCAL_ENVIRONMENT_NAME

Sostituisci:

  • LOCAL_ENVIRONMENT_NAME con il nome dell'ambiente Airflow locale.

Elenca le immagini utilizzate dagli ambienti Airflow locali

Per elencare tutte le immagini utilizzate dallo strumento CLI di sviluppo locale di Composer, esegui:

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

Installa i plug-in e modifica i dati

I plug-in e i dati per un ambiente Airflow locale vengono presi dalla directory dell'ambiente locale: ./composer/<local_environment_name>/data e ./composer/<local_environment_name>/plugins).

Per modificare i contenuti delle directory /data e /plugins, aggiungi o rimuovi i file in queste directory. Docker propaga automaticamente le modifiche dei file al tuo ambiente Airflow locale.

Lo strumento CLI di sviluppo locale di Composer non supporta la specifica di una directory diversa per dati e plug-in.

Configura le variabili di ambiente

Per configurare le variabili di ambiente, modifica il variables.env file nella directory dell'ambiente: ./composer/<local_environment_name>/variables.env.

Il file variables.env deve contenere definizioni coppia chiave-valore, una riga per ogni variabile di ambiente. Per modificare le opzioni di configurazione di Airflow, utilizza il formato AIRFLOW__SECTION__KEY. Per saperne di più sulle variabili di ambiente disponibili, consulta il riferimento alla configurazione di Airflow.

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

Per applicare le modifiche, riavvia l'ambiente Airflow locale.

Installa o rimuovi i pacchetti PyPI

Per installare o rimuovere i pacchetti PyPI, modifica il file requirements.txt nella directory dell'ambiente: ./composer/<local_environment_name>/requirements.txt.

I requisiti devono seguire il formato specificato in PEP-508, in cui ogni requisito è specificato in minuscolo e consiste nel nome del pacchetto con extra e specificatori di versione facoltativi.

Per applicare le modifiche, riavvia l'ambiente Airflow locale.

Passa a un'altra immagine di build di Airflow

Puoi utilizzare qualsiasi immagine di build di Airflow con lo strumento CLI di sviluppo locale di Composer e passare da un'immagine all'altra. Questo approccio è diverso da l'upgrade dell'ambiente Airflow gestito, perché i parametri di configurazione dell'ambiente Airflow locale vengono applicati all'avvio.

Ad esempio, dopo il rilascio di una nuova build di Airflow, puoi passare all'ambiente per utilizzarla e mantenere la configurazione esistente dell'ambiente Airflow locale.

Per modificare l'immagine dell'ambiente utilizzata dall'ambiente Airflow locale:

  1. Modifica il file di configurazione dell'ambiente locale: ./composer/<local_environment_name>/config.json.

  2. Modifica il valore del parametro composer_image_version. Per visualizzare i valori disponibili, puoi elencare le immagini disponibili.

  3. Per applicare le modifiche, riavvia l'ambiente Airflow locale.

Elimina un ambiente Airflow locale

Attenzione: assicurati di aver salvato tutti i dati richiesti dall'ambiente, come log e configurazione.

Per eliminare un ambiente Airflow locale, esegui il comando seguente:

composer-dev remove LOCAL_ENVIRONMENT_NAME

Se l'ambiente è in esecuzione, aggiungi il flag --force per forzarne la rimozione.

Elimina le immagini Docker

Per eliminare tutte le immagini scaricate dallo strumento CLI di sviluppo locale di Composer, esegui:

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

Risoluzione dei problemi

Questa sezione fornisce soluzioni ai problemi comuni.

Impossibile avviare un ambiente locale su macOS

Se hai installato il pacchetto composer-dev in una directory a cui Docker non può accedere, l'ambiente locale potrebbe non avviarsi.

Ad esempio, se Python è installato nella directory /opt, come quando lo installi con la configurazione predefinita di Homebrew su macOS, anche il pacchetto composer-dev viene installato nella directory /opt. Poiché Docker è conforme alle regole della sandbox di Apple, la directory /opt non è disponibile per impostazione predefinita. Inoltre, non puoi aggiungerla tramite l'interfaccia utente (Impostazioni > Risorse > Condivisione file).

In questo caso, lo strumento CLI di sviluppo locale di Composer genera un messaggio di errore simile al seguente esempio:

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

Puoi utilizzare una delle seguenti soluzioni:

  • Installa Python o il pacchetto composer-dev in una directory diversa, in modo che Docker possa accedere al pacchetto.
  • Modifica manualmente il file ~/Library/Group\ Containers/group.com.docker/settings.json e aggiungi /opt a filesharingDirectories.

Passaggi successivi