Exécuter un environnement Airflow local avec l'outil de CLI de développement local Composer

Managed Airflow (3e génération) | Managed Airflow (2e génération) | Managed Airflow (1re génération héritée)

Cette section explique comment créer, configurer et exécuter un environnement Airflow local à l'aide de l'outil de ligne de commande Composer Local Development.

À propos de l'outil de ligne de commande Composer Local Development

L'outil de ligne de commande Composer Local Development simplifie le développement de DAG Apache Airflow pour Managed Airflow en exécutant un environnement Airflow localement. Cet environnement Airflow local utilise une image de compilation Airflow utilisée par une version spécifique de Managed Airflow.

Vous pouvez créer un environnement Airflow local basé sur un environnement Managed Airflow existant. Dans ce cas, l'environnement Airflow local prend la liste des packages PyPI installés et les noms des variable d'environnement de votre environnement Managed Airflow.

Vous pouvez utiliser cet environnement Airflow local à des fins de test et de développement, par exemple pour tester un nouveau code DAG, des packages PyPI ou des options de configuration Airflow.

Avant de commencer

  • L'outil de ligne de commande Composer Local Development est compatible avec les builds Aiflow 3 à partir de composer-3-airflow-3.1.0-build.8.

  • L'outil de ligne de commande Composer Local Development crée des environnements Airflow locaux dans un répertoire où vous exécutez la commande composer-dev create. Pour accéder ultérieurement à votre environnement Airflow local, exécutez les commandes de l'outil dans le chemin d'accès où vous avez créé l'environnement local. Toutes les données de l' environnement local sont stockées dans un sous-répertoire au chemin d'accès où vous avez créé l'environnement local : ./composer/<local_environment_name>.

  • Votre ordinateur doit disposer de suffisamment d'espace disque pour stocker les images de compilation Airflow. L'outil de ligne de commande Composer Local Development stocke un fichier image pour chaque compilation Airflow. Par exemple, si vous disposez de deux environnements Airflow locaux avec des compilations Airflow différentes, l'outil de CLI Composer Local Development stocke deux images de compilation Airflow.

  • L'outil de ligne de commande Composer Local Development utilise une sortie colorisée. Vous pouvez désactiver la sortie colorisée avec la NO_COLOR=1 variable: NO_COLOR=1 composer-dev <other commands>.

  • Si vous ne disposez que d'un seul environnement local, vous pouvez omettre le nom de l'environnement local de toutes les commandes composer-dev, à l'exception de run-airflow-cmd.

  • Installez les dépendances de l'outil de ligne de commande Composer Local Development :

  • Installez Docker. Docker doit être installé et exécuté dans le système local. Pour vérifier que Docker est en cours d'exécution, vous pouvez exécuter n'importe quelle commande Docker CLI, telle que docker ps.

Configurer les identifiants

Si ce n'est pas déjà fait, procurez-vous de nouveaux identifiants utilisateur à utiliser comme identifiants par défaut de l'application :

gcloud auth application-default login

Connectez-vous à gcloud CLI à l'aide de votre compte Google :

gcloud auth login

Tous les appels d'API effectués par l'outil de ligne de commande Composer Local Development et les DAG sont exécutés à partir du compte que vous utilisez dans gcloud CLI. Par exemple, si un DAG de votre environnement Airflow local lit le contenu d'un bucket Cloud Storage, ce compte doit disposer des autorisations nécessaires pour accéder au bucket. Cela diffère des environnements Managed Airflow, où le compte de service d'un environnement effectue les appels.

Installer l'outil de ligne de commande Composer Local Development

Clonez le dépôt de l'outil de ligne de commande Composer Local Development :

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

Dans le répertoire de premier niveau du dépôt cloné, exécutez :

pip install .

En fonction de votre configuration pip, le chemin d'accès où l'outil est installé peut ne pas se trouver dans la variable PATH. Dans ce cas, pip affiche un message d'avertissement. Vous pouvez utiliser les informations de ce message d'avertissement pour ajouter ce répertoire à la variable PATH de votre système d'exploitation.

Créer un environnement Airflow local avec une image de compilation Airflow

Pour répertorier les images de compilation Airflow disponibles, exécutez :

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

Pour créer un environnement Airflow local avec des paramètres par défaut, exécutez :

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

Autres paramètres :

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

Remplacez :

  • IMAGE_VERSION par le nom de l'image de compilation Airflow.
  • PROJECT_ID par l'ID du projet.
  • WEB_SERVER_PORT par le port sur lequel le serveur Web Airflow doit écouter.
  • LOCAL_DAGS_PATH par le chemin d'accès à un répertoire local où se trouvent les fichiers DAG.
  • LOCAL_ENVIRONMENT_NAME par le nom de cet environnement Airflow local.

Exemple :

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

Créer un environnement Airflow local à partir d'un environnement Managed Airflow

Seules les informations suivantes sont extraites d'un environnement Managed Airflow :

  • Compilation Airflow spécifique utilisée par votre environnement.

  • Liste des packages PyPI personnalisés installés dans votre environnement.

  • Liste commentée des noms des variables d'environnement définies dans votre environnement.

Les autres informations et paramètres de configuration de l'environnement, tels que les fichiers DAG, l'historique d'exécution des DAG, les variables Airflow et les connexions, ne sont pas copiés à partir de votre environnement Managed Airflow.

Pour créer un environnement Airflow local à partir d'un environnement Managed Airflow existant :

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

Remplacez :

  • LOCAL_ENVIRONMENT_NAME par un nom pour l'environnement Airflow local.
  • ENVIRONMENT_NAME par le nom de l'environnement Managed Airflow.
  • LOCATION par la région dans laquelle se trouve l'environnement Managed Airflow.
  • PROJECT_ID par l'ID du projet.
  • WEB_SERVER_PORT par un port pour le serveur Web Airflow local.
  • LOCAL_DAGS_PATH par un chemin d'accès à un répertoire local où se trouvent les DAG.

Exemple :

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

Démarrer un environnement Airflow local

Pour démarrer un environnement Airflow local, exécutez :

composer-dev start LOCAL_ENVIRONMENT_NAME

Remplacez :

  • LOCAL_ENVIRONMENT_NAME par le nom d'un environnement Airflow local.

Arrêter ou redémarrer un environnement Airflow local

Lorsque vous redémarrez un environnement Airflow local, l'outil de ligne de commande Composer Local Development redémarre le conteneur Docker dans lequel l'environnement s'exécute. Tous les composants Airflow sont arrêtés et redémarrés. Par conséquent, toutes les exécutions de DAG qui sont exécutées lors d'un redémarrage sont marquées comme ayant échoué .

Pour redémarrer ou démarrer un environnement Airflow local arrêté, exécutez :

composer-dev restart LOCAL_ENVIRONMENT_NAME

Remplacez :

  • LOCAL_ENVIRONMENT_NAME par le nom d'un environnement Airflow local.

Pour arrêter un environnement Airflow local, exécutez :

composer-dev stop LOCAL_ENVIRONMENT_NAME

Ajouter et mettre à jour des DAG

Les DAG sont stockés dans le répertoire que vous avez spécifié dans le paramètre --dags-path lorsque vous avez créé votre environnement Airflow local. Par défaut, ce répertoire est ./composer/<local_environment_name>/dags. Vous pouvez obtenir le répertoire utilisé par votre environnement avec la describe commande.

Pour ajouter et mettre à jour des DAG, modifiez les fichiers de ce répertoire. Vous n'avez pas besoin de redémarrer votre environnement Airflow local.

Afficher les journaux de l'environnement Airflow local

Vous pouvez afficher les journaux récents d'un conteneur Docker qui exécute votre environnement Airflow local. Vous pouvez ainsi surveiller les événements liés aux conteneurs et vérifier les journaux Airflow pour détecter les erreurs telles que les conflits de dépendances causés par l'installation de packages PyPI.

Pour afficher les journaux d'un conteneur Docker qui exécute votre environnement Airflow local, exécutez :

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Pour suivre le flux de journaux, omettez l'argument --max-lines :

composer-dev logs LOCAL_ENVIRONMENT_NAME

Exécuter une commande de CLI Airflow

Vous pouvez exécuter des commandes de CLI Airflow dans votre environnement Airflow local.

Pour exécuter une commande de CLI Airflow :

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

Exemple :

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

Configurer des environnements Airflow locaux

L'outil de ligne de commande Composer Local Development stocke les paramètres de configuration d'un environnement Airflow local, tels que les variables d'environnement et les exigences de package PyPI dans le répertoire de l'environnement local (./composer/<local_environment_name>).

La configuration est appliquée lorsqu'un environnement Airflow local est démarré. Par exemple, si vous ajoutez des exigences de package PyPI conflictuelles, l'outil de ligne de commande Composer Local Development signale des erreurs lorsque vous démarrez l'environnement local.

Les connexions Airflow sont stockées dans la base de données de l'environnement Airflow local. Vous pouvez les configurer en exécutant une commande de CLI Airflow ou en stockant les paramètres de connexion dans des variables d'environnement. Pour en savoir plus sur la création et la configuration des connexions, consultez Gérer les connexions dans la documentation Airflow.

Obtenir la liste et l'état des environnements Airflow locaux

Pour répertorier tous les environnements Airflow locaux disponibles et afficher leur état :

composer-dev list

Pour décrire un environnement spécifique et obtenir des détails tels que la version de l'image, le chemin d'accès aux DAG et l'URL du serveur Web d'un environnement :

composer-dev describe LOCAL_ENVIRONMENT_NAME

Remplacez :

  • LOCAL_ENVIRONMENT_NAME par le nom de l'environnement Airflow local.

Répertorier les images utilisées par les environnements Airflow locaux

Pour répertorier toutes les images utilisées par l'outil de ligne de commande Composer Local Development, exécutez :

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

Installer des plug-ins et modifier des données

Les plug-ins et les données d'un environnement Airflow local sont extraits du répertoire de l'environnement local : ./composer/<local_environment_name>/data et ./composer/<local_environment_name>/plugins).

Pour modifier le contenu des répertoires /data et /plugins, ajoutez ou supprimez des fichiers dans ces répertoires. Docker propage automatiquement les modifications de fichiers à votre environnement Airflow local.

L'outil de ligne de commande Composer Local Development n'est pas compatible avec la spécification d'un répertoire différent pour les données et les plug-ins.

Configurer les variables d'environnement

Pour configurer des variables d'environnement, modifiez le variables.env fichier dans le répertoire de l'environnement : ./composer/<local_environment_name>/variables.env.

Le fichier variables.env doit contenir des définitions clé-valeur, une ligne pour chaque variable d'environnement. Pour modifier les options de configuration Airflow, utilisez le format AIRFLOW__SECTION__KEY. Pour en savoir plus sur les variables d'environnement disponibles, consultez la documentation de référence sur la configuration Airflow.

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

Pour appliquer les modifications, redémarrez votre environnement Airflow local.

Installer ou supprimer des packages PyPI

Pour installer ou supprimer des packages PyPI, modifiez le fichier requirements.txt dans le répertoire de l'environnement : ./composer/<local_environment_name>/requirements.txt.

Les exigences doivent respecter le format indiqué dans PEP-508, où chaque exigence est spécifiée en minuscules et consiste en un nom de package avec des options et des spécificateurs de version facultatifs.

Pour appliquer les modifications, redémarrez votre environnement Airflow local.

Passer à une autre image de compilation Airflow

Vous pouvez utiliser n'importe quelle image de compilation Airflow avec l'outil de CLI Composer Local Development et passer d'une image à l'autre. Cette approche est différente de la mise à niveau de votre environnement Managed Airflow, car les paramètres de configuration de votre environnement Airflow local sont appliqués lorsqu'il démarre.

Par exemple, après la publication d'une nouvelle compilation Airflow, vous pouvez configurer votre environnement pour l'utiliser et conserver la configuration existante de l'environnement Airflow local.

Pour modifier l'image de l'environnement utilisée par votre environnement Airflow local :

  1. Modifiez le fichier de configuration de l'environnement local : ./composer/<local_environment_name>/config.json.

  2. Modifiez la valeur du paramètre composer_image_version. Pour afficher les valeurs disponibles, vous pouvez répertorier les images disponibles.

  3. Pour appliquer les modifications, redémarrez votre environnement Airflow local.

Supprimer un environnement Airflow local

Attention : Assurez-vous d'avoir enregistré toutes les données requises de l'environnement, telles que les journaux et la configuration.

Pour supprimer un environnement Airflow local, exécutez la commande suivante :

composer-dev remove LOCAL_ENVIRONMENT_NAME

Si l'environnement est en cours d'exécution, ajoutez l'option --force pour forcer sa suppression.

Supprimer des images Docker

Pour supprimer toutes les images téléchargées par l'outil de ligne de commande Composer Local Development, exécutez :

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

Dépannage

Cette section fournit des solutions aux problèmes courants.

Impossible de démarrer un environnement local sur macOS

Si vous avez installé le package composer-dev dans un répertoire auquel Docker ne peut pas accéder, votre environnement local risque de ne pas démarrer.

Par exemple, si Python est installé dans le répertoire /opt, comme lorsque vous l'installez avec la configuration Homebrew par défaut sur macOS, le package composer-dev est également installé dans le répertoire /opt. Étant donné que Docker est conforme aux règles de bac à sable d'Apple, le répertoire /opt n'est pas disponible par défaut. De plus, vous ne pouvez pas l'ajouter via l'interface utilisateur (Settings > Resources > File sharing) (Paramètres > Ressources > Partage de fichiers).

Dans ce cas, l'outil de ligne de commande Composer Local Development génère un message d'erreur semblable à l'exemple suivant :

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

Vous pouvez utiliser l'une des solutions suivantes :

  • Installez Python ou le package composer-dev dans un autre répertoire afin que Docker puisse accéder au package.
  • Modifiez manuellement le fichier ~/Library/Group\ Containers/group.com.docker/settings.json et ajoutez /opt à filesharingDirectories.

Étape suivante