Commandes Apache Airflow de base avec exemples pratiques : un guide pour les opérateurs quotidiens

Introduction

Apache Airflow est une plateforme puissante d'orchestration de workflows, mais les opérations quotidiennes reposent souvent sur la connaissance des bonnes commandes et leur utilisation sécuritaire. Une commande de base exécutée au mauvais moment ou sur le mauvais composant peut transformer un petit problème en panne. Ce guide se concentre sur les commandes pratiques que les opérateurs, les ingénieurs DevOps et les équipes techniques de startups utilisent pour vérifier, diagnostiquer et gérer en toute sécurité les déploiements Airflow. Vous apprendrez à vérifier les versions, évaluer la santé, inspecter les tâches et récupérer des défaillances courantes, avec des exemples concrets et les sorties attendues.

Nous mettons l'accent sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier les résultats et documenter les procédures de récupération. À la fin, vous disposerez d'une liste de contrôle réutilisable pour les opérations quotidiennes Airflow.

Inventaire des versions et de l'environnement

Avant d'exécuter une commande, établissez la version exacte et la topologie de votre installation Airflow. Les différentes versions ont des commandes et des comportements différents. Par exemple, Airflow 3 a introduit un serveur d'API et un processeur de DAG fonctionnant séparément, ce qui modifie la façon d'inspecter et de gérer le système. Commencez par :

airflow version

Sortie attendue pour une version récente :

2.10.3

Si vous utilisez Airflow 3, la sortie peut ressembler à 3.0.0. Notez la version majeure car de nombreuses commandes diffèrent. Documentez également l'exécuteur, la base de données de métadonnées et la méthode de déploiement (par exemple, Docker, Kubernetes, bare metal). Un moyen rapide d'obtenir les détails de configuration :

airflow config get-value core executor

Sortie attendue :

CeleryExecutor

ou LocalExecutor, KubernetesExecutor, etc. Cela vous indique comment les tâches sont exécutées et quels composants sont impliqués.

Pour Airflow 3, vérifiez la santé du serveur d'API et du processeur de DAG séparément. Utilisez l'endpoint de santé avec curl :

curl -s http://localhost:8080/api/v2/monitor/health

La réponse est un objet JSON ; ne considérez pas un HTTP 200 seul comme preuve de santé. Inspectez les champs comme scheduler, triggerer, dag_processor et metadata_db. Un planificateur sain peut afficher :

{
  "scheduler": {
    "status": "healthy",
    "latest_scheduler_heartbeat": "2025-03-25T12:00:00Z"
  },
  "metadata_db": {
    "status": "healthy"
  }
}

Si un composant est en mauvaise santé, enquêtez avant d'apporter des modifications.

Pour les mises à niveau, en particulier de Airflow 2.7+ vers 3.x, consultez toujours les notes de version et la compatibilité des fournisseurs. Sauvegardez votre base de données de métadonnées avant la migration. Testez des DAG représentatifs sur un environnement de préproduction. Ensuite, exécutez :

airflow db migrate

Ne remplacez pas une migration par un redémarrage. Après la migration, vérifiez avec airflow db check et exécutez quelques DAG manuellement.

Chemin de configuration sécurisé

Les modifications de configuration peuvent affecter l'ensemble du cluster. Utilisez un processus contrôlé : observer, planifier, modifier un élément, vérifier et documenter le retour en arrière. Commencez par afficher la configuration actuelle sans exposer les secrets. Utilisez :

airflow config list

Cela imprime toutes les options, mais les valeurs peuvent être masquées pour les éléments sensibles. Pour voir une option spécifique :

airflow config get-value core dags_folder

Sortie attendue :

/opt/airflow/dags

Lors d'un changement de configuration, utilisez la variable d'environnement ou airflow.cfg, mais évitez de modifier directement les fichiers en direct si vous utilisez un système de gestion de configuration. Par exemple, pour augmenter l'intervalle de battement de cœur du planificateur dans Airflow 2, vous pouvez définir scheduler.heartbeat_sec = 5 dans airflow.cfg. Après le changement, redémarrez uniquement le processus du planificateur (s'il fonctionne comme un service séparé), pas toute la pile. Vérifiez avec :

airflow jobs check --job-type SchedulerJob --hostname $(hostname)

Sortie attendue en cas de succès :

Found one alive job.

Pour Airflow 3, certaines configurations sont appliquées via des variables d'environnement. Exemple : définissez AIRFLOW__CORE__DAGS_FOLDER=/new/path et redémarrez le processeur de DAG. Vérifiez que le nouveau chemin est pris en compte en consultant les journaux du processeur de DAG ou en exécutant airflow dags list.

Conservez toujours une trace de la valeur précédente et de la raison du changement. Si le changement dégrade les performances, revenez rapidement en arrière.

Vérification et diagnostics

Les opérations quotidiennes nécessitent des vérifications fréquentes que le système fonctionne et que les DAG s'exécutent comme prévu. Utilisez d'abord des commandes en lecture seule.

Vérifiez la santé du planificateur :

airflow jobs check --job-type SchedulerJob --hostname $(hostname)

Si elle renvoie Found one alive job., le planificateur est vivant. Sinon, vérifiez les journaux dans $AIRFLOW_HOME/logs/scheduler/latest/.

Pour la connectivité de la base de données de métadonnées :

airflow db check

Sortie attendue :

Connection successful.

En cas d'erreur, vérifiez les informations d'identification de la base de données et le réseau.

Listez les DAG et leurs états :

airflow dags list

Exemple de sortie :

dag_id              | filepath          | owner   | paused
====================+===================+=========+=======
example_dag         | example_dag.py    | airflow | False
data_pipeline       | data_pipeline.py  | data_team | False

Faites attention à la colonne paused. Un DAG en pause ne s'exécutera pas selon le calendrier ; dépausez avec airflow dags unpause data_pipeline.

Inspectez les instances de tâche pour une exécution de DAG spécifique :

airflow tasks list data_pipeline

Ensuite, vérifiez l'état d'une instance de tâche :

airflow tasks state data_pipeline transform_data 2025-03-25T00:00:00+00:00

Sortie attendue :

success

Si c'est failed, examinez les journaux :

airflow tasks logs data_pipeline transform_data 2025-03-25T00:00:00+00:00

Pour Airflow 3, utilisez les endpoints de l'API pour des diagnostics similaires. Par exemple, GET /api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances renvoie les détails d'état des tâches en JSON.

Modes de défaillance et récupération

Comprenez les modes de défaillance courants et comment récupérer à l'aide des commandes.

Planificateur en panne

Si le planificateur ne fonctionne pas, les DAG ne seront pas déclenchés. Vérifiez avec airflow jobs check. S'il n'y a pas de travail vivant, démarrez le planificateur :

airflow scheduler

Exécutez-le dans un processus supervisé (par exemple, systemd, Docker) pour un redémarrage automatique.

Base de données de métadonnées indisponible

Si airflow db check échoue, vérifiez que le service de base de données fonctionne et que les informations d'identification sont correctes. Si la base de données est en panne, restaurez à partir de la sauvegarde ou redémarrez le service de base de données. N'exécutez pas airflow db migrate à moins de vouloir intentionnellement mettre à niveau ; cela peut modifier le schéma.

Erreurs d'analyse des DAG

Si un fichier DAG a une erreur de syntaxe, il n'apparaîtra pas dans airflow dags list ou affichera une erreur d'importation. Utilisez :

export AIRFLOW__CORE__DAGBAG_IMPORT_TIMEOUT=60
airflow dags list

Vérifiez les journaux du planificateur pour les traces. Corrigez la syntaxe, puis exécutez :

airflow dags reserialize

Cela force la sérialisation et peut révéler des erreurs.

Échec de tâche

Une tâche peut échouer en raison de bugs de code, de limites de ressources ou de dépendances externes. Après avoir identifié l'instance de tâche en échec, vous pouvez la nettoyer pour la réexécuter :

airflow tasks clear data_pipeline --task-regex transform_data --start-date 2025-03-25T00:00:00+00:00 --end-date 2025-03-25T01:00:00+00:00

Cela nettoie les instances de tâche dans cette plage et permet au planificateur de les réexécuter. Pour une seule exécution de DAG, utilisez --dag-run-id.

Vérifiez toujours les journaux avant de nettoyer pour éviter de répéter la même défaillance.

Tâches zombies

Si une tâche est bloquée dans l'état running mais que le worker est mort, marquez-la comme échouée :

airflow tasks failed data_pipeline transform_data 2025-03-25T00:00:00+00:00

Ensuite, nettoyez-la si approprié.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour les opérations Airflow quotidiennes ou hebdomadaires. Chaque élément inclut un propriétaire et une fréquence.

Pièges courants et comment les éviter

1. Traiter le HTTP 200 comme une santé complète

Pourquoi cela arrive : Les opérateurs supposent souvent que si le serveur web Airflow répond, l'ensemble du système est sain. Cependant, le serveur web peut fonctionner alors que le planificateur est en panne.

Comment éviter : Utilisez l'endpoint de santé (/api/v2/monitor/health dans Airflow 3) et vérifiez l'état de chaque composant. Exécutez également airflow jobs check.

2. Exécuter airflow db migrate inutilement

Pourquoi cela arrive : Certains opérateurs croient que l'exécution de db migrate est une solution rapide aux problèmes de base de données. Elle est destinée aux mises à niveau de schéma et peut causer des problèmes si elle est exécutée au mauvais moment.

Comment éviter : N'exécutez db migrate que dans le cadre d'une procédure de mise à niveau, après avoir sauvegardé la base de données. Pour les problèmes de connectivité, utilisez db check.

3. Ignorer les différences de version

Pourquoi cela arrive : Les commandes et le comportement changent entre les versions d'Airflow, surtout le passage de 2 à 3. Les opérateurs peuvent utiliser d'anciennes commandes qui n'existent plus ou se comportent différemment.

Comment éviter : Vérifiez toujours airflow version et consultez la documentation de votre version spécifique. Testez les commandes dans un environnement hors production.

4. Nettoyer les instances de tâche sans enquêter

Pourquoi cela arrive : Lorsqu'une tâche échoue, la réaction immédiate est de la nettoyer et d'espérer qu'elle réussisse. Sans comprendre la cause profonde, la tâche peut échouer à nouveau et gaspiller des ressources.

Comment éviter : Examinez les journaux avec airflow tasks logs avant de nettoyer. Vérifiez les erreurs de code, les problèmes de données ou l'épuisement des ressources.

5. Exposer les secrets dans les commandes

Pourquoi cela arrive : Les opérateurs peuvent imprimer par inadvertance des chaînes de connexion ou des mots de passe dans la sortie des commandes ou les journaux. Par exemple, airflow config list peut montrer certains secrets s'ils ne sont pas masqués.

Comment éviter : Utilisez le backend de secrets Airflow (par exemple, variables d'environnement, Vault) et évitez de passer des informations d'identification comme arguments de commande. Examinez toujours la sortie des commandes avant de la partager.

6. Ne pas sauvegarder avant les modifications

Pourquoi cela arrive : Dans la précipitation pour résoudre un problème, les opérateurs peuvent modifier la configuration ou exécuter des migrations sans sauvegarde.

Comment éviter : Établissez une sauvegarde de routine de la base de données de métadonnées et des fichiers DAG. Pour les modifications critiques, prenez un instantané de la base de données manuellement.

Conclusion

Maîtriser les commandes Airflow de base est essentiel pour des opérations quotidiennes sûres et efficaces. En suivant une approche structurée—inventaire, observation, intervention ciblée et vérification—vous réduisez les risques et améliorez la fiabilité. Utilisez les commandes et les listes de contrôle de ce guide comme point de départ, et adaptez-vous toujours à votre version et à votre déploiement spécifiques.

Comme prochaine étape, choisissez une commande de vérification à faible risque de ce guide, exécutez-la contre votre environnement Airflow et documentez l'état actuel et la sortie attendue. Ensuite, examinez vos procédures de récupération en cas de défaillance pour vous assurer d'être préparé aux incidents courants.