## Introduction Apache Airflow est devenu la norme de facto pour l'orchestration des pipelines de données, mais un cluster de production n'est pas l'endroit idéal pour expérimenter. Un laboratoire local vous permet de tester des DAG, d'explorer de nouvelles fonctionnalités et de répéter les procédures opérationnelles sans mettre en péril les flux de travail critiques. Ce guide présente une configuration locale d'Airflow versionnée, observable et réversible, avec des exemples pratiques que les développeurs, consultants DevOps et équipes de start-up peuvent utiliser immédiatement. Cet article n'est pas un tutoriel en une seule commande. C'est un manuel axé sur les opérations qui couvre l'inventaire des versions et de l'environnement, les changements de configuration sécurisés, la vérification et le diagnostic, les modes de défaillance et la récupération, ainsi qu'une liste de contrôle opérationnelle. Chaque section inclut des commandes concrètes, les résultats attendus et les étapes de récupération afin que vous puissiez observer avant de modifier, limiter la zone d'impact et vérifier les résultats. L'objectif est la sécurité opérationnelle : capturer l'état actuel, utiliser des variables d'environnement plutôt que des secrets, effectuer un changement ciblé à la fois et documenter comment récupérer si l'état attendu n'est pas atteint. À la fin, vous disposerez d'une méthode reproductible pour mettre en place et maintenir un environnement Airflow local. ## Inventaire des versions et de l'environnement Avant de toucher quoi que ce soit, vous avez besoin d'un inventaire précis. Exécutez cette commande en lecture seule : airflow version Sur une installation fraîche avec Airflow 2.8.1, vous pourriez voir : 2.8.1 Airflow 3.x a introduit des changements architecturaux importants : un serveur d'API REST et un processeur de DAG fonctionnant séparément. Votre version détermine quelles commandes et quels points de terminaison de santé sont valides. Pour obtenir plus de détails sur l'environnement, exécutez : airflow info Cela affiche les informations système, y compris la version de Python, le répertoire d'accueil Airflow et les chemins de configuration. Notez l'exécuteur utilisé. Pour un laboratoire local, le SequentialExecutor (par défaut pour SQLite) fonctionne pour les tests mais n'exécute pas les tâches simultanément. Pour un parallélisme réaliste, utilisez le LocalExecutor avec PostgreSQL ou MySQL comme base de données de métadonnées. Documentez le backend de la base de données de métadonnées : airflow config get-value database sql_alchemy_conn Résultat attendu pour une configuration locale typique avec SQLite : sqlite:////home/user/airflow/airflow.db Pour des tests proches de la production, passez à PostgreSQL, qui prend en charge le LocalExecutor et évite les problèmes de verrouillage de SQLite. Enregistrez également les fournisseurs installés : airflow providers list Cette sortie est longue, mais vous pouvez la canaliser vers grep pour vous concentrer sur les fournisseurs clés comme apache-airflow-providers-postgres ou amazon . Les fournisseurs étendent Airflow avec des opérateurs et des hooks pour les systèmes externes, et des problèmes de compatibilité surviennent souvent après des mises à niveau. Enfin, notez la méthode de déploiement. Avez-vous installé via pip , Docker ou le chart Helm officiel ? Pour un laboratoire local, Docker Compose basé sur le docker-compose.yaml officiel est un choix populaire et isolé. La méthode affecte la manière d'appliquer les changements et où les journaux sont stockés. ## Chemin de configuration sécurisé La configuration dans Airflow se trouve dans airflow.cfg (ou les variables d'environnement). Pour trouver le fichier de configuration actif : echo $AIRFLOW_HOME Si AIRFLOW_HOME n'est pas défini, il est par défaut ~/airflow . Inspectez les paramètres actuels sans rien modifier en utilisant airflow config list ou airflow config get-value . Par exemple, pour vérifier le dossier des DAG : airflow config get-value core dags_folder Résultat attendu : /home/user/airflow/dags Lorsque vous devez modifier un paramètre, évitez de modifier le fichier directement pour de petits changements reproductibles. À la place, exportez une variable d'environnement préfixée par AIRFLOW__SECTION__KEY . Par exemple, pour augmenter temporairement la verbosité de la journalisation : export AIRFLOW__LOGGING__LOGGING_LEVEL=DEBUG Ce changement s'applique uniquement à la session shell actuelle et est facile à annuler. Pour des changements permanents, modifiez airflow.cfg avec un commentaire de contrôle de version, mais sauvegardez toujours le fichier d'abord : cp airflow.cfg airflow.cfg.bak.$(date +%Y%m%d) Airflow prend également en charge un remplacement ~/.airflow/airflow.cfg . Après tout changement de configuration, vérifiez qu'Airflow peut toujours analyser la configuration : airflow config list > /dev/null && echo "Config OK" Si la commande se termine avec une erreur, annulez le changement. Les secrets ne doivent jamais apparaître en texte clair dans le fichier de configuration ou les variables d'environnement pour les configurations de type production. Pour un laboratoire local, vous pouvez utiliser l'utilisateur par défaut airflow avec le mot de passe airflow , mais pour tout ce qui dépasse un environnement jetable, utilisez les backends de secrets intégrés d'Airflow ou au moins des références de variables d'environnement. Par exemple, pour définir un mot de passe de connexion via une variable d'environnement, utilisez la forme URI structurée dans airflow connections add : airflow connections add my_postgres \ --conn-type postgres \ --conn-host localhost \ --conn-login airflow \ --conn-password "$POSTGRES_PASSWORD" \ --conn-port 5432 Ne mettez jamais le mot de passe réel dans un script qui est validé dans le contrôle de version. Utilisez un fichier .env ignoré par Git. ## Vérification et diagnostics Après tout changement, vérifiez que les processus de base sont sains. Démarrez le planificateur et le serveur web dans des terminaux séparés (ou utilisez Docker Compose) : airflow scheduler airflow webserver -p 8080 Vérifiez la santé du planificateur : airflow jobs check --job-type SchedulerJob --hostname $(hostname) Un planificateur sain affiche quelque chose comme : Trouvé un travail vivant. Si aucun travail vivant n'est trouvé, le planificateur n'est peut-être pas en cours d'exécution ou est bloqué. Vérifiez la connectivité de la base de données : airflow db check Résultat attendu : Connexion réussie. Pour Airflow 3, le point de terminaison de santé donne une vue plus granulaire. Interrogez-le avec curl : curl -s http://localhost:8080/api/v2/monitor/health | python -m json.tool Recherchez "status": true pour chaque composant comme scheduler , database et triggerer . Un simple 200 OK ne suffit pas ; inspectez la charge utile JSON. L'analyse des DAG est un autre point de défaillance courant. Listez les DAG et voyez s'il y a des erreurs d'importation : airflow dags list Si un DAG est manquant, exécutez : airflow dags list-import-errors Corrigez les erreurs de syntaxe Python ou de dépendances manquantes affichées. Testez les tâches d'un DAG spécifique sans les exécuter en utilisant airflow tasks test : airflow tasks test example_bash_operator runme_0 2024-01-01 Cela exécute la tâche en mode test, en contournant le planificateur et en affichant les journaux directement dans la console. ## Modes de défaillance et reprise Même un laboratoire local rencontre des échecs. Voici les modes de défaillance courants et comment les récupérer : ### Le planificateur ne prend pas en charge les DAG Symptômes : les DAG n'apparaissent pas dans l'interface utilisateur, airflow dags list ne montre rien. Causes possibles : - Les fichiers DAG ne sont pas dans le dags_folder . - Erreurs de syntaxe Python ou dépendances manquantes. - Le planificateur n'a pas été redémarré après l'ajout de nouveaux DAG (ou dag_dir_list_interval trop long). Reprise : - Vérifiez airflow config get-value core dags_folder et assurez-vous que votre fichier DAG est là. - Exécutez python votre_dag.py pour détecter les erreurs. - Redémarrez le planificateur ou définissez un dag_dir_list_interval plus court. ### Erreurs de verrouillage de base de données avec SQLite Symptômes : les journaux du planificateur affichent OperationalError: database is locked . Cause : SQLite ne gère pas bien les écritures simultanées, surtout avec plusieurs processus de planificateur ou un serveur web effectuant des écritures. Reprise : - Pour les tests locaux, passez au SequentialExecutor et limitez la concurrence à 1. - Pour des charges de travail réalistes, migrez vers PostgreSQL. Mettez à jour sql_alchemy_conn et exécutez airflow db migrate . ### Tâche bloquée en état de file d'attente Symptômes : une tâche reste en file d'attente indéfiniment. Cause : l'exécuteur n'est pas configuré pour exécuter les tâches, ou les ressources des travailleurs sont épuisées. Reprise : - Vérifiez l'exécuteur : airflow config get-value core executor . - Si SequentialExecutor, une seule tâche s'exécute à la fois. Attendez qu'elle se termine ou effacez les tâches bloquées. - Si LocalExecutor, assurez-vous que le processus du planificateur dispose de suffisamment de ressources et qu'aucune tâche ne dépasse les limites de parallélisme ( parallelism , dag_concurrency ). ### Interface web inaccessible Symptômes : le navigateur ne peut pas se connecter à localhost:8080 . Cause : le serveur web ne fonctionne pas, mauvais port ou pare-feu. Reprise : - Vérifiez la liste des processus : ps aux | grep airflow-webserver . - Consultez les journaux du serveur web pour les erreurs. - Si le port est utilisé, changez avec -p 8081 . ## Liste de contrôle des opérations Utilisez cette liste de contrôle pour tout changement dans votre laboratoire local Airflow. Chaque élément inclut un exemple concret et un responsable. Revisitez cette liste mensuellement ou avant tout changement important.
ÉtapeActionExemple concretResponsableFréquence de révision
1Enregistrez la version actuelle et les détails de l'environnement.airflow version -> 2.8.1; airflow info enregistré dans airflow_env.txtIngénieur DevOps (par ex., Priya Shah)Mensuelle
2Effectuez un bilan de santé en lecture seule.airflow jobs check --job-type SchedulerJob --hostname $(hostname) et curl -s http://localhost:8080/api/v2/monitor/healthIngénieur de garde (par ex., Alex Chen)Avant tout changement
3Sauvegardez la configuration et la base de données.cp airflow.cfg airflow.cfg.bak.$(date +%Y%m%d) et sqlite3 airflow.db .backup airflow.db.bakIngénieur DevOpsAvant tout changement de config
4Effectuez un changement ciblé ; utilisez un remplacement par variable d'environnement si possible.export AIRFLOW__CORE__DAG_CONCURRENCY=4 pour augmenter la concurrence du DAG pour les testsDéveloppeur effectuant le changement (par ex., Marcus Johnson)À chaque changement
5Vérifiez le changement avec une commande ou un signal spécifique.Après avoir augmenté la concurrence, exécutez airflow config get-value core dag_concurrency pour confirmer la valeur ; puis exécutez un DAG de test avec airflow tasks testMême développeurImmédiatement après le changement
6Vérifiez les erreurs d'importation de DAG avant l'activation.airflow dags list-import-errors renvoie videIngénieur de données (par ex., Sarah Lee)Chaque fois que de nouveaux DAG sont ajoutés
7Surveillez les métriques clés (par ex., pulsation du planificateur, taux de réussite des tâches) via les journaux ou l'interface utilisateur.Dans l'interface, vérifiez Admin -> Jobs pour la pulsation du planificateur dans les 5 minutesIngénieur DevOpsQuotidienne pendant le développement actif
8Documentez les étapes de reprise pour les pannes courantes.Ajoutez une entrée au runbook pour "Base de données verrouillée" avec les étapes pour passer à PostgreSQLChef technique (par ex., David Kim)Révision trimestrielle
## Pièges courants et comment les éviter Même les utilisateurs expérimentés tombent dans ces pièges. Voici comment les reconnaître et les éviter. ### Piège 1 : exécuter Airflow dans un environnement virtuel sans l'activer Pourquoi cela arrive : vous installez Airflow dans un venv mais oubliez de l'activer dans un nouveau shell, ce qui provoque "commande introuvable" ou l'utilisation d'un Python système avec des dépendances manquantes. Comment l'éviter : activez toujours le venv avant d'exécuter les commandes Airflow. Utilisez un script d'encapsulation ou un alias. Reprise : source /chemin/vers/venv/bin/activate et réexécutez la commande. ### Piège 2 : utiliser le même nom de fichier DAG avec des identifiants de DAG différents Pourquoi cela arrive : vous copiez un fichier DAG et changez l'ID du DAG mais oubliez que le nom de fichier doit être unique. Airflow charge les deux, provoquant des ID de DAG en double et de la confusion. Comment l'éviter : gardez un DAG par fichier et nommez le fichier pour correspondre à l'ID du DAG. Reprise : renommez l'un des fichiers ou changez l'ID du DAG. Supprimez l'ancien DAG de la base de données en utilisant airflow dags delete si nécessaire. ### Piège 3 : coder en dur les informations d'identification dans le code du DAG Pourquoi cela arrive : les tests rapides conduisent souvent à intégrer des mots de passe dans les chaînes de connexion ou les variables. Comment l'éviter : utilisez les connexions et variables Airflow. Ne validez jamais les secrets dans le contrôle de version. Reprise : déplacez les informations d'identification vers les connexions/variables, faites tourner tous les secrets exposés et nettoyez l'historique git si nécessaire. ### Piège 4 : ignorer la confusion de fuseau horaire et de planification Pourquoi cela arrive : Airflow utilise UTC par défaut pour la planification, mais l'heure de la machine locale peut différer. Les utilisateurs définissent des planifications en s'attendant à l'heure locale. Comment l'éviter : spécifiez toujours le fuseau horaire dans start_date et schedule du DAG, par exemple, schedule='0 9 *', timezone='America/New_York' . Reprise : ajustez start_date et la planification en conséquence ; effacez et réexécutez les tâches affectées. ### Piège 5 : ne pas surveiller le déclencheur pour les opérateurs différables Pourquoi cela arrive : les opérateurs différables reposent sur un processus de déclencheur séparé. S'il n'est pas démarré, les tâches restent dans un état différé. Comment l'éviter : démarrez le déclencheur avec le planificateur et le serveur web : airflow triggerer . Dans Docker Compose, assurez-vous que le service airflow-triggerer est en cours d'exécution. Reprise : vérifiez airflow jobs check --job-type TriggererJob --hostname $(hostname) et démarrez le déclencheur si nécessaire. ## Conclusion Un laboratoire local Airflow n'est utile que dans la mesure de la discipline que vous y apportez. En versionnant chaque recommandation, en observant avant d'intervenir et en vérifiant les résultats avec des commandes concrètes, vous pouvez expérimenter en toute sécurité et développer une mémoire musculaire opérationnelle. La liste de contrôle et les pièges de ce guide vous donnent un point de départ pour un processus reproductible qui peut évoluer vers la production. Comme prochaine étape, choisissez une vérification à faible risque dans la liste de contrôle, comme exécuter airflow db check , enregistrez la sortie et comparez-la au résultat attendu. Ensuite, écrivez un DAG simple qui utilise un BashOperator et testez-le avec airflow tasks test . Examinez le point de terminaison de santé dans Airflow 3 et documentez toute différence pour votre équipe. Un flux de travail technique fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la reprise avant qu'un incident ne force la décision.