## Introduction Apache Airflow repose sur plusieurs connexions réseau : le webserver et l'API, la base de données de métadonnées, les brokers de messages optionnels (pour CeleryExecutor) et parfois des récepteurs de métriques. Quand Airflow semble lent ou inaccessible, la cause racine est souvent le DNS, les ports, les adresses de liaison, le routage ou les pare-feux. Ce guide vous donne des commandes pratiques et sûres pour isoler rapidement les problèmes, explique les résultats attendus pour que vous puissiez raisonner sur les sorties, et fournit une procédure de retour arrière si un changement n'aide pas. Le chemin le plus rapide vers la clarté est de tester d'abord une tranche étroite et mesurable, de vérifier les résultats localement, puis seulement d'élargir la portée. Des points de terminaison nommés et clairs pour les services Airflow minimisent les allers-retours et rendent les diagnostics reproductibles d'un environnement à l'autre. ## Inventaire des versions et de l'environnement Avant de changer quoi que ce soit, capturez ce qui tourne réellement. Cela évite de poursuivre le mauvais problème et vous donne une cible de retour arrière connue comme bonne. Prérequis : - Accès shell aux hôtes Airflow où tournent le webserver, le scheduler, les workers, la base de données ou le broker. - Capacité à lancer les outils réseau de base : ss ou netstat , lsof , curl , nc (netcat), dig ou nslookup , traceroute . - Accès en lecture aux fichiers de configuration Airflow (typiquement $AIRFLOW_HOME/airflow.cfg ) et aux logs. Enregistrez ce qui suit sur chaque hôte pertinent : - Version Airflow et exécuteur airflow version airflow config get-value core executor - Python et OS python --version uname -a - Inventaire des processus ps -ef | grep -E 'airflow|celery' | grep -v grep - Points de terminaison et ports des composants (noms d'exemple construits) - Webserver : http://airflow-web.example.internal:8080 - Scheduler : processus local ; pas de port entrant - Base de données de métadonnées (ex. Postgres) : airflow-db.example.internal:5432 - Broker (ex. Redis ou RabbitMQ pour Celery) : redis.example.internal:6379 ou rabbitmq.example.internal:5672 - Métriques (StatsD optionnel) : statsd.example.internal:8125/udp - Valeurs de configuration clés airflow config get-value webserver web_server_host airflow config get-value webserver web_server_port airflow config get-value webserver base_url airflow config get-value core sql_alchemy_conn airflow config get-value celery broker_url airflow config get-value celery result_backend Tableau : points de terminaison et ports réseau Airflow courants (défauts affichés ; ajustez à votre environnement).
ComposantPort par défautProtocole
Webserver (UI/API)8080TCP
Flower (optionnel)5555TCP
Postgres métadonnées5432TCP
MySQL métadonnées3306TCP
Broker Redis6379TCP
Broker RabbitMQ (AMQP)5672TCP
RabbitMQ mgmt (optionnel)15672TCP
StatsD (optionnel)8125UDP
Résultat attendu : vous avez une note d'une page avec versions, noms d'hôtes et ports. C'est votre source de vérité pendant le diagnostic. ## Chemin de configuration sécurisé Les changements réseau peuvent casser l'accès. Utilisez une approche réversible : - Sauvegardez les fichiers de config : cp $AIRFLOW_HOME/airflow.cfg $AIRFLOW_HOME/airflow.cfg.bak.$(date +%Y%m%d%H%M%S) - Changez une chose à la fois ; testez ; puis continuez. - Préférez les tests temporaires ( curl , nc ) aux changements de config permanents jusqu'à ce que vous ayez validé l'hypothèse. - Utilisez une fenêtre de maintenance si vous devez redémarrer des services. Changements ciblés, à faible risque, à envisager : - Adresse de liaison et port du webserver - Si l'UI n'est accessible que depuis localhost : mettez l'hôte à 0.0.0.0 pour un accès distant dans un réseau de confiance, ou à une IP d'interface spécifique (ex. 10.10.20.15 ). - Exemple : dans airflow.cfg sous [webserver] : [webserver] web_server_host = 0.0.0.0 web_server_port = 8080 base_url = http://airflow-web.example.internal:8080 - DNS base de données et broker - Remplacez temporairement un nom d'hôte qui échoue par une IP directe pour confirmer DNS vs accessibilité. - Si l'IP fonctionne, corrigez le DNS plutôt que de laisser l'IP en dur. - Ouvertures pare-feu - Ouvrez seulement les ports nécessaires, vers les sources qui en ont besoin. Testez avec une règle temporaire avant de la rendre permanente. Plan de retour arrière : - Restaurez airflow.cfg depuis la sauvegarde et redémarrez seulement le(s) service(s) affecté(s). - Annulez les changements de pare-feu en utilisant la liste de règles sauvegardée et rechargez. ## Vérification et diagnostics Lancez des tests simples, progressivement plus profonds. Arrêtez-vous quand vous trouvez un saut qui échoue. - Le webserver tourne-t-il et écoute-t-il ? # Affiche les sockets d'écoute pour les ports Airflow courants sudo ss -tulpn | grep -E ':(8080|5432|5672|6379)' # Ou sudo lsof -i -P -n | grep -E ':(8080|5432|5672|6379)' Attendu : une ligne montrant python (airflow webserver) lié à 0.0.0.0:8080 ou une IP spécifique:8080. S'il est lié à 127.0.0.1:8080 , les clients distants ne l'atteindront pas. C'est la mauvaise configuration par défaut la plus fréquente dans les installations fraîches. - Vérification HTTP santé depuis l'hôte lui-même curl -sS -I http://127.0.0.1:8080/ | head -n 1 curl -sS http://127.0.0.1:8080/health || true Attendu : - La première commande retourne HTTP/1.1 200 OK ou 302 Found (redirection login). Cela prouve que le socket et le HTTP sont OK. - /health peut retourner du JSON si activé. S'il 404 mais que la page racine retourne 200/302, le webserver est quand même assez sain pour servir l'UI. - Vérification HTTP distante depuis un hôte client curl -sS -I http://airflow-web.example.internal:8080/ | head -n 1 Si cela échoue mais que le test local réussit, investiguez DNS, routage ou pare-feux. - Vérifications de résolution DNS getent hosts airflow-web.example.internal dig +short airflow-web.example.internal nslookup airflow-web.example.internal Attendu : IPs cohérentes sur tous les hôtes. Si la résolution diffère selon l'hôte ou est absente, corrigez le DNS d'abord. - Vérification du chemin de routage # Traceroute basé TCP vers le port web sudo traceroute -T -p 8080 airflow-web.example.internal Attendu : une liste de sauts stable se terminant à l'IP du webserver. Des timeouts vers la fin indiquent souvent des pare-feux d'hôte. - Accessibilité du port sans HTTP # Depuis un hôte client nc -vz airflow-web.example.internal 8080 # Pour DB et broker (exemple) nc -vz airflow-db.example.internal 5432 nc -vz redis.example.internal 6379 nc -vz rabbitmq.example.internal 5672 Attendu : messages succeeded pour les ports accessibles. Connection refused signifie que l'hôte est joignable mais aucun processus n'écoute. Timeout signifie un pare-feu ou un trou noir de routage. - Connectivité base de données depuis l'hôte Airflow # Exemple Postgres psql "$(airflow config get-value core sql_alchemy_conn)" -c 'select 1;' # Exemple MySQL mysql --execute='select 1;' "$(airflow config get-value core sql_alchemy_conn)" Attendu : retourne une seule ligne avec 1 . Si l'authentification échoue ici mais que les tests réseau passent, corrigez les identifiants ou les réglages SSL. - Connectivité broker depuis l'hôte worker (CeleryExecutor) # Exemple Redis redis-cli -h redis.example.internal -p 6379 PING # Exemple RabbitMQ (poignée de main TCP simple ; utilisez le port AMQPS 5671 pour TLS) openssl s_client -connect rabbitmq.example.internal:5672 -quiet < /dev/null || true Attendu : Redis PONG ; pour RabbitMQ vous confirmez seulement la poignée de main TCP sauf si TLS/AMQPS est configuré. - Vérifications pare-feu d'hôte (lancez seulement ce qui s'applique) # UFW sudo ufw status verbose # firewalld sudo firewall-cmd --list-all # iptables (hérité) sudo iptables -S | sed -n '1,200p' Attendu : voyez si 8080, 5432, 5672, 6379 sont autorisés depuis les bonnes sources. - Logs Airflow pour corroboration # Remplacez par votre AIRFLOW_HOME si nécessaire ls -1 $AIRFLOW_HOME/logs/ grep -iE 'connection|error|timeout|refused|dns' -R $AIRFLOW_HOME/logs/ | sed -n '1,100p' Attendu : les erreurs réseau mentionneront timeout, refused, name or address not known, ou échecs SSL. Utilisez les horodatages des logs pour les aligner avec vos tests. Tableau : référence diagnostics rapides.
ObjectifCommande exempleSignal attendu
Voir les écouteursss -tulpnProcessus et adresses de liaison
HTTP localcurl -I http://127.0.0.1:8080/En-têtes 200/302
HTTP distantcurl -I http://airflow-web.example.internal:8080/En-têtes 200/302
Résolution DNSgetent hosts airflow-web.example.internalAdresse IP
Test portnc -vz airflow-db.example.internal 5432succeeded/refused/timeout
Routagetraceroute -T -p 8080 airflow-web.example.internalchemin de sauts vers cible
Pare-feuufw status verboserègles autorisées/refusées
## Modes de défaillance et récupération Utilisez cette carte pour passer du symptôme à la cause probable et au correctif. Tableau : échecs réseau Airflow courants et premières étapes de correctif (exemples construits).
SymptômeCause probablePremière étape de correctif
UI fonctionne localement, pas à distanceWebserver lié à 127.0.0.1Mettez web_server_host à 0.0.0.0 ou IP d'interface ; redémarrez webserver
curl timeout depuis clientPare-feu hôte ou ACL réseauAutorisez temporairement le port depuis l'IP client ; vérifiez avec nc -vz ; puis pérennisez la règle proprement
Connexion refusée sur 8080Pas de processus ou mauvais portConfirmez ss -tulpn ; corrigez port ou démarrez webserver
DNS résout différemment par hôteSplit-horizon ou cache obsolèteCorrigez enregistrements DNS ; videz cache nscd/systemd-resolved ; évitez IPs en dur long terme
Scheduler n'atteint pas DBMauvais hôte/port sql_alchemy_conn ou pare-feuTestez avec psql/mysql depuis hôte scheduler ; corrigez config et autorisez port
Workers bloqués, tâches non réclaméesBroker inaccessiblenc -vz vers broker ; corrigez broker_url DNS/port ou ouvrez pare-feu
UI lente ou 504 intermittentsProxy ou load balancer timeouts inactifsAugmentez timeouts amont ou activez keepalive ; vérifiez avec curl -v
Erreurs handshake SSLMauvais certificats ou désaccord TLSTestez avec openssl s_client ; mettez à jour bundle CA ou alignez versions TLS
Patterns de récupération : - Correction adresse de liaison - Changez [webserver] web_server_host à 0.0.0.0 (ou l'IP d'interface spécifique sur un réseau de confiance, ex. 10.10.20.15 ). - Redémarrez seulement le webserver. - Revérifiez curl local et distant. - Retour arrière : restaurez le airflow.cfg précédent si la nouvelle liaison élargit l'exposition inattendue. - Correction conflit de port - Identifiez le processus en conflit : sudo ss -tulpn | grep :8080 sudo lsof -iTCP:8080 -sTCP:LISTEN -n -P - Option A : arrêtez l'autre processus si non nécessaire. Option B : changez Airflow vers un port libre (ex. 8081) et mettez à jour base_url . - Vérifiez avec curl ; mettez à jour les règles pare-feu pour correspondre au nouveau port. - Retour arrière : revenez au port et redémarrez si les clients sont codés en dur sur l'ancien port. - Remédiation DNS - Prouvez le chemin avec une IP directe une fois : curl -I http://10.10.20.30:8080/ - Si l'IP fonctionne, corrigez le DNS : mettez à jour enregistrements A/CNAME ou domaines de recherche. Évitez de laisser des IPs brutes dans airflow.cfg . - Videz les caches si nécessaire : sudo resolvectl flush-caches || sudo systemd-resolve --flush-caches || true - Retour arrière : aucun nécessaire ; retirez les surcharges IP temporaires. - Ouverture pare-feu (exemple UFW) # Autorisation temporaire depuis un client spécifique sudo ufw allow from 192.0.2.10 to any port 8080 proto tcp sudo ufw status numbered - Testez avec nc et curl . Si bon, rendez la règle persistante dans votre système de gestion de changements. - Retour arrière : sudo ufw delete - Accessibilité base de données - Depuis l'hôte Airflow, testez le port DB et la connexion ; corrigez réseau et identifiants. - Exemple Postgres d'un test de connexion minimal : PGURI="$(airflow config get-value core sql_alchemy_conn)" psql "$PGURI" -c 'select 1;' - Si SSL est requis, confirmez le chemin CA et sslmode dans la chaîne de connexion. - Récupération broker (CeleryExecutor) - Redis : redis-cli -h redis.example.internal -p 6379 PING - RabbitMQ : nc -vz rabbitmq.example.internal 5672 - Corrigez broker_url DNS, identifiants, ou ouvrez le port. Redémarrez les workers après avoir confirmé l'accessibilité. - Réglage proxy ou load balancer - Reproduisez un timeout avec curl -v pour voir le délai et si un en-tête proxy est présent. - Augmentez le timeout inactif et le keepalive entre le proxy et le webserver Airflow. - Vérifiez en lançant plusieurs curl rapides ; la latence doit se stabiliser. - Désaccords SSL/TLS - Inspectez avec openssl : openssl s_client -connect airflow-web.example.internal:8443 -servername airflow-web.example.internal -showcerts < /dev/null - Mettez à jour les certificats et alignez les versions de protocole selon votre politique de sécurité. ## Liste de contrôle opérationnelle Utilisez cette liste courte, reproductible, pour les installations et les incidents. Pré-vol - Capturez version Airflow, exécuteur, et points de terminaison des composants. - Documentez noms d'hôtes et ports attendus pour web, DB, broker, métriques. - Sauvegardez airflow.cfg et toute règle de pare-feu que vous prévoyez de toucher. Vérification rapide quotidienne ou hebdomadaire - ss -tulpn montre le webserver en écoute sur l'hôte:port prévu. - curl -I vers l'UI depuis localhost et un client distant retourne 200/302. - getent hosts pour tous les noms d'hôtes Airflow retourne les IPs attendues. - Pour CeleryExecutor : nc -vz vers broker et DB réussissent depuis les workers. Gestion des changements - Changez une variable à la fois (liaison, port, DNS, pare-feu). - Testez localement, puis à distance ; enregistrez sorties de commandes et horodatages. - Si sans succès, retour arrière immédiat avec configs et règles sauvées. Réponse aux incidents - Confirmez processus et écouteur ( ss , lsof ). - Distinguez refus vs timeout ( nc ) : refus => pas d'écouteur ; timeout => filtre/routage. - Validez cohérence DNS entre hôtes ( getent , dig ). - Tracez la route seulement si DNS et curl local sont bons. - Vérifiez les logs pour erreurs de connexion alignées avec vos tests. Revue post-incident - Remplacez tout hack IP temporaire par du DNS propre. - Serrez les règles pare-feu au moindre privilège tout en gardant les chemins qui marchent ouverts. - Mettez à jour cette liste avec commandes concrètes et sorties observées. ## Conclusion Les problèmes réseau Airflow se réduisent généralement à quelques questions : un processus écoute-t-il où vous l'attendez, les clients peuvent-ils le résoudre et l'atteindre, et les équipements intermédiaires permettent-ils le flux ? En commençant par un petit test vérifiable, en confirmant DNS et adresses de liaison, et en utilisant des vérifications d'accessibilité ciblées, vous pouvez isoler les échecs rapidement. Gardez des sauvegardes pour airflow.cfg et les règles de pare-feu, changez une variable à la fois, et faites un retour arrière rapide si une étape n'aide pas. Adoptez le tableau de diagnostics et la liste de contrôle comme base de votre équipe pour que la validation routine et la récupération deviennent de la mémoire musculaire.