Mise à niveau et migration d'Apache Airflow : guide pratique de mise en œuvre

Introduction

Les mises à niveau et les migrations d’Apache Airflow sont des opérations critiques qui exigent une planification minutieuse, une exécution précise et une vérification approfondie. Que vous passiez d’Airflow 2 à Airflow 3, que vous appliquiez une mise à jour mineure ou que vous migriez vers une nouvelle infrastructure, le processus requiert une approche systématique pour éviter les interruptions de service, les pertes de données ou les DAG défaillants.

Ce guide s’adresse aux développeurs, ingénieurs DevOps et équipes techniques de startups chargées de maintenir des environnements Airflow. Il fournit des instructions pratiques et concrètes pour chaque phase : évaluation de votre configuration actuelle, préparation de la mise à niveau, exécution de la migration, vérification du succès et restauration si nécessaire. Nous mettons l’accent sur des commandes réelles, des sorties attendues et des stratégies de récupération, pour vous permettre d’opérer en toute confiance.

Tout au long de cet article, nous insistons sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d’impact, protéger les données sensibles et toujours définir des étapes de récupération avant d’en avoir besoin. À la fin, vous disposerez d’un processus clair et reproductible pour les mises à niveau et les migrations d’Apache Airflow, étayé par des exemples concrets.

Inventaire des versions et de l’environnement

Avant toute mise à niveau, vous devez comprendre en détail votre environnement Airflow actuel. Commencez par documenter la version, la topologie de déploiement et les composants clés. Cet inventaire sert de base à la planification et à la restauration.

Étape 1 : Vérifier la version d’Airflow et ses composants

Exécutez la commande suivante pour déterminer la version d’Airflow installée :

airflow version

Exemple de sortie attendue :

2.9.3

Si vous utilisez Airflow 3, la sortie commencera par 3.x.x. Notez la version majeure, car Airflow 3 introduit des changements architecturaux importants, comme un serveur API et un processeur de DAG séparés.

Identifiez ensuite l’exécuteur (executor), la base de données de métadonnées et la méthode de déploiement. Vérifiez votre fichier airflow.cfg ou vos variables d’environnement :

airflow config get-value core executor
airflow config get-value database sql_alchemy_conn

Sorties attendues :

CeleryExecutor
postgresql+psycopg2://airflow:airflow@localhost/airflow

Les exécuteurs courants incluent SequentialExecutor, LocalExecutor, CeleryExecutor et KubernetesExecutor. La base de métadonnées peut être PostgreSQL, MySQL ou SQLite. Les méthodes de déploiement incluent souvent Docker, Kubernetes ou une installation sur serveur bare metal.

Listez également les fournisseurs (providers) installés :

airflow providers list

Cette commande affiche les paquets de fournisseurs et leurs versions, ce qui est crucial pour les vérifications de compatibilité.

Étape 2 : Contrôles de santé (lecture seule)

Avant toute modification, effectuez des contrôles de santé en lecture seule pour vous assurer que le système est stable. Dans Airflow 2, utilisez :

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

Sortie attendue (si sain) :

Found one alive job.

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

airflow db check

Sortie attendue :

Connection successful.

Dans Airflow 3, l’endpoint de santé fournit un état détaillé des composants. Accédez à l’API :

curl -s http://<hôte-airflow>/api/v2/monitor/health

Exemple de réponse :

{
  "metadatabase": {"status": "healthy"},
  "scheduler": {"status": "healthy"},
  "triggerer": {"status": "healthy"},
  "dag_processor": {"status": "healthy"}
}

Ne vous fiez pas uniquement au code de statut 200 ; inspectez l’état de chaque composant.

Étape 3 : Documenter les DAG et les dépendances

Inventoriez vos DAG et notez ceux qui sont critiques pour les tests après la mise à niveau :

airflow dags list

Enregistrez également l’emplacement des fichiers de DAG et les plugins ou hooks personnalisés, car ils peuvent nécessiter des mises à jour.

Chemin de configuration sécurisé

Lors d’une mise à niveau, les modifications de configuration doivent être gérées avec soin pour éviter de casser les workflows existants. Cette section présente une approche sûre pour valider et appliquer les mises à jour de configuration.

1. Examiner les notes de version et la compatibilité

Avant la mise à niveau, lisez les notes de version de la version cible. Portez attention aux éléments suivants :

• Fonctionnalités dépréciées
• Changements incompatibles
• Compatibilité des fournisseurs

Par exemple, le passage d’Airflow 2.9 à 2.10 peut déprécier certains opérateurs. Si vous utilisez des fournisseurs comme apache-airflow-providers-amazon, assurez-vous qu’ils prennent en charge la nouvelle version. Vérifiez la compatibilité des fournisseurs avec :

pip check

Ou consultez la documentation du fournisseur.

2. Sauvegarder la configuration et la base de métadonnées

Sauvegardez toujours votre fichier airflow.cfg et tous les paramètres spécifiques à l’environnement :

cp $AIRFLOW_HOME/airflow.cfg $AIRFLOW_HOME/airflow.cfg.backup-$(date +%Y%m%d)

Pour la base de métadonnées, utilisez l’outil de sauvegarde de votre SGBD. Pour PostgreSQL :

pg_dump -U airflow airflow > airflow_db_backup_$(date +%Y%m%d).sql

Pour MySQL :

mysqldump -u airflow -p airflow > airflow_db_backup_$(date +%Y%m%d).sql

3. Tester les changements dans un environnement de préproduction

Si possible, reproduisez votre environnement de production et testez la mise à niveau là-bas d’abord. Exécutez vos DAG les plus critiques en préproduction et vérifiez qu’ils se terminent correctement.

4. Appliquer les changements de configuration de manière incrémentale

Après la mise à niveau de la version d’Airflow, vous devrez peut-être ajuster des configurations. Par exemple, dans Airflow 3, la séparation du serveur API et du processeur de DAG nécessite de nouveaux paramètres. Au lieu d’apporter plusieurs modifications à la fois, changez un paramètre à la fois et vérifiez son effet.

Par exemple, si vous devez passer à l’exécuteur KubernetesExecutor, modifiez-le dans airflow.cfg et redémarrez le planificateur, puis consultez les journaux pour détecter des erreurs.

airflow config set core executor KubernetesExecutor

Notez cependant que changer d’exécuteur peut nécessiter une configuration d’infrastructure supplémentaire.

5. Utiliser airflow db migrate

Après l’installation d’une nouvelle version, exécutez la commande de migration de la base de données. Cette étape est obligatoire pour les mises à niveau mineures et majeures.

airflow db migrate

Sortie attendue (tronquée) :

INFO  [alembic.runtime.migration] Running upgrade 2.9.3 -> 2.10.0, add column to task_instance

Ne sautez pas cette étape ; un redémarrage sans migration peut entraîner des incohérences de schéma et des erreurs.

Vérification et diagnostics

Après une mise à niveau, une vérification approfondie est essentielle pour s’assurer que tous les composants fonctionnent correctement. Utilisez les méthodes suivantes pour diagnostiquer d’éventuels problèmes.

1. Vérifier la version d’Airflow et les composants

Exécutez à nouveau airflow version pour confirmer la nouvelle version.

Vérifiez que tous les processus attendus sont en cours d’exécution. Dans Airflow 2, vous pouvez utiliser :

ps aux | grep airflow

Dans Airflow 3, utilisez l’endpoint de santé comme décrit précédemment :

curl -s http://<hôte-airflow>/api/v2/monitor/health

2. Vérifier la santé du planificateur et de la base de données

Réexécutez les commandes de contrôle de santé :

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

Si le planificateur n’est pas sain, inspectez ses journaux. Emplacement typique des journaux : $AIRFLOW_HOME/logs/scheduler/latest/.

3. Valider l’analyse des DAG

Assurez-vous que tous les DAG sont analysés sans erreur :

airflow dags list-import-errors

Sortie attendue si aucune erreur :

No data found

Ou, pour chaque DAG :

airflow dags list

Vérifiez que les DAG apparaissent avec les bonnes planifications.

4. Exécuter un DAG de test

Déclenchez un DAG de test simple ou utilisez airflow tasks test pour exécuter une seule tâche :

airflow tasks test example_bash_operator runme_0 2024-01-01

Cette commande exécute la tâche localement sans affecter le planificateur. Elle aide à vérifier l’exécution des tâches et les dépendances.

Pour un test plus complet, déclenchez une exécution de DAG via l’interface utilisateur ou la CLI :

airflow dags trigger -e 2024-01-01 example_bash_operator

Puis surveillez son état :

airflow dags list-runs -d example_bash_operator

5. Surveiller les journaux et les métriques

Après avoir déclenché les tests, examinez les journaux pour détecter des erreurs :

tail -f $AIRFLOW_HOME/logs/dag_id=example_bash_operator/run_id=manual__2024-01-01T00:00:00/task_id=runme_0/attempt=1.log

Si vous utilisez un système de surveillance comme Prometheus, vérifiez les métriques d’Airflow pour détecter des anomalies.

Modes de défaillance et récupération

Malgré une planification soignée, les mises à niveau peuvent échouer. Cette section couvre les scénarios de défaillance courants et la manière de s’en remettre.

1. Échec de la migration de la base de données

Si airflow db migrate échoue, le message d’erreur indique généralement la cause. Les problèmes courants incluent des extensions manquantes, des problèmes de permissions ou des versions de base de données incompatibles.

Étapes de récupération :

• Restaurez la base de données à partir de la sauvegarde.
• Corrigez le problème sous-jacent (par exemple, installez l’extension PostgreSQL requise).
• Relancez la migration.

Exemple de restauration pour PostgreSQL :

psql -U airflow airflow < airflow_db_backup_YYYYMMDD.sql

2. Le planificateur ne démarre pas après la mise à niveau

Si le planificateur plante après la mise à niveau, consultez les journaux pour la trace d’erreur. Causes courantes :

• Fournisseurs incompatibles
• Erreurs de configuration
• Dépendances manquantes

Dépannage :

airflow scheduler

Exécutez au premier plan pour voir directement les erreurs. Si un fournisseur est incompatible, rétrogradez-le ou mettez-le à niveau :

pip install apache-airflow-providers-amazon==<version-compatible>

Si l’erreur vient de la configuration, annulez le paramètre spécifique que vous avez modifié.

3. Erreurs d’importation de DAG

Après la mise à niveau, certains DAG peuvent ne pas être analysés en raison d’opérateurs dépréciés. Utilisez airflow dags list-import-errors pour identifier les DAG problématiques. Mettez ensuite à jour le code du DAG pour utiliser de nouveaux opérateurs ou ajustez les instructions d’importation.

4. Dégradation des performances

Parfois, les mises à niveau introduisent des régressions de performances. Surveillez le battement de cœur du planificateur, le débit des tâches et la charge de la base de données. Si les performances sont inacceptables, envisagez de revenir à la version précédente, mais seulement après avoir vérifié que le schéma de base de données est compatible. La restauration nécessite généralement la restauration de la sauvegarde de la base de données, car les changements de migration sont souvent irréversibles.

Plan de restauration

Un plan de restauration solide comprend :

• La restauration de la version précédente d’Airflow (par exemple, pip install apache-airflow==2.9.3)
• La restauration de la sauvegarde de la base de données
• La restauration des fichiers de configuration
• Le redémarrage des services

Exemple de commandes de restauration :

pip install apache-airflow==2.9.3
psql -U airflow airflow < airflow_db_backup_YYYYMMDD.sql
cp $AIRFLOW_HOME/airflow.cfg.backup-YYYYMMDD $AIRFLOW_HOME/airflow.cfg
airflow db upgrade  # assure que le schéma correspond à la version
airflow scheduler -D
airflow webserver -D

Testez toujours la procédure de restauration en préproduction avant d’en avoir besoin en production.

Liste de contrôle opérationnelle

Utilisez cette liste avant, pendant et après une mise à niveau d’Airflow pour ne rien oublier.

Avant la mise à niveau

• [ ] Documenter la version actuelle d’Airflow, l’exécuteur, la base de données, les fournisseurs et la méthode de déploiement.
• [ ] Examiner les notes de version et la compatibilité pour la version cible.
• [ ] Sauvegarder airflow.cfg et toutes les configurations personnalisées.
• [ ] Sauvegarder la base de métadonnées.
• [ ] Identifier les DAG critiques pour les tests.
• [ ] Mettre en place un environnement de préproduction (si possible) et y tester la mise à niveau.
• [ ] Informer les parties prenantes et planifier une fenêtre de maintenance.

Pendant la mise à niveau

• [ ] Installer la nouvelle version d’Airflow (par exemple, pip install apache-airflow==X.Y.Z).
• [ ] Mettre à jour les paquets de fournisseurs si nécessaire.
• [ ] Exécuter airflow db migrate et capturer la sortie.
• [ ] Redémarrer les services (planificateur, serveur web, workers).
• [ ] Vérifier les endpoints de santé et les journaux.

Vérification après la mise à niveau

• [ ] Exécuter airflow version pour confirmer la nouvelle version.
• [ ] Exécuter airflow db check et airflow jobs check.
• [ ] Vérifier l’analyse des DAG (aucune erreur d’importation).
• [ ] Déclencher des DAG de test et surveiller leur achèvement.
• [ ] Vérifier les journaux pour des erreurs ou des avertissements.
• [ ] Surveiller les métriques de performance pendant une période (par exemple, 24 à 48 heures).
• [ ] Mettre à jour la documentation avec la nouvelle version et tout changement de configuration.

Préparation à la restauration

• [ ] Garder les sauvegardes facilement accessibles.
• [ ] Documenter les commandes exactes de restauration.
• [ ] S’assurer que les membres de l’équipe savent comment exécuter la restauration.
• [ ] Tester la restauration en préproduction.

Conclusion

Les mises à niveau et les migrations d’Apache Airflow exigent une attention méticuleuse aux détails, mais avec une approche structurée, vous pouvez minimiser les risques et assurer une transition en douceur. Ce guide a couvert les étapes essentielles : inventorier votre environnement, préparer un chemin de configuration sécurisé, vérifier la mise à niveau, gérer les défaillances et suivre une liste de contrôle complète.

N’oubliez pas que chaque environnement Airflow est unique ; adaptez donc ces pratiques à votre configuration spécifique. Donnez toujours la priorité à l’observabilité, aux changements incrémentaux et à la planification de la récupération. Ainsi, vous maintiendrez une plateforme Airflow fiable qui pourra évoluer avec vos workflows de données.

Comme prochaine étape, choisissez une vérification à faible risque de ce guide, comme l’exécution de airflow jobs check, et intégrez-la à votre routine de maintenance régulière. Ensuite, le moment venu pour votre prochaine mise à niveau, vous serez bien préparé pour l’exécuter avec confiance et récupérer rapidement si nécessaire.