Sauvegarde et restauration d'Apache Airflow : exemples pratiques pour une reprise fiable

Introduction

Sauvegarder Apache Airflow ne se résume pas à copier des fichiers. Une sauvegarde fiable permet de restaurer la base de métadonnées, les fichiers DAG, les journaux et la configuration afin que vos workflows puissent être relancés après un incident. Cet article fournit des commandes et des vérifications pratiques pour Airflow 2 et 3, pour vous permettre de sauvegarder et restaurer en toute confiance.

Nous nous concentrons sur les étapes essentielles pour les opérateurs : effectuer une sauvegarde cohérente de la base de métadonnées, préserver vos DAG et plugins, capturer la configuration et valider que la restauration fonctionne réellement. Nous couvrons également les modes de défaillance courants et comment les surmonter. L'objectif est de rendre votre routine de sauvegarde testable, reproductible et sûre.

Tout au long de cet article, nous utilisons des exemples concrets avec sorties de commandes et résultats attendus. Nous évitons les variables génériques et montrons des chemins réels, variables d'environnement et vérifications de validation.

Inventaire des versions et de l'environnement

Avant de sauvegarder quoi que ce soit, sachez exactement ce que vous exécutez. Les différentes versions d'Airflow modifient l'emplacement des données et la manière de valider une restauration.

Commencez par vérifier la version d'Airflow et la configuration :

airflow version

La sortie attendue ressemble à :

3.0.2

ou pour Airflow 2 :

2.10.4

Ensuite, inspectez la configuration actuelle sans exposer les secrets. La commande airflow config list affiche les paramètres effectifs mais peut inclure des chaînes de connexion. Pour une vue en lecture seule plus sûre, utilisez :

airflow config get-value core sql_alchemy_conn

Remplacez sql_alchemy_conn par la clé souhaitée. Cela n'affiche que la valeur, veillez donc à ne pas l'exposer dans les journaux. Par exemple, si votre base de métadonnées est PostgreSQL, vous pourriez voir :

postgresql+psycopg2://airflow:****@postgres:5432/airflow

Dans de nombreuses configurations par défaut, le mot de passe est masqué, mais vérifiez avant d'exécuter cette commande sur un terminal partagé.

Documentez les détails suivants dans votre inventaire :

• Version d'Airflow (2.x ou 3.x). Dans Airflow 3, l'architecture a introduit un serveur API et un processeur de DAG séparé. Cela modifie ce que vous devez sauvegarder.
• Type d'exécuteur (LocalExecutor, CeleryExecutor, KubernetesExecutor, etc.). Vérifiez avec airflow config get-value core executor.
• Type de base de métadonnées et détails de connexion. Sur Airflow 2, utilisez airflow db check ; sur Airflow 3, utilisez également airflow db check si pris en charge, ou inspectez la configuration.
• Méthode de déploiement : Docker, Kubernetes, métal nu ou service géré. Cela affecte l'emplacement des fichiers DAG et des journaux.
• Distribution des DAG : les DAG sont-ils dans un volume partagé, un dépôt Git ou un stockage objet ?

Vérifications de santé : pour Airflow 3, le serveur API expose /api/v2/monitor/health. Ne considérez pas un code HTTP 200 comme preuve que tous les composants sont sains. Inspectez plutôt le corps JSON :

curl -s http://airflow-api:8080/api/v2/monitor/health | jq .

La sortie attendue inclut des champs comme :

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

Si un composant indique unhealthy, enquêtez avant de sauvegarder, car vous pourriez capturer un état incohérent.

Pour les vérifications du planificateur, utilisez :

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

Sortie attendue :

Found one alive job.

Si la commande ne signale aucun job actif, le planificateur est arrêté et votre sauvegarde pourrait manquer l'état de planification.

Chemin de configuration sécurisé

Avant d'effectuer des modifications, capturez la configuration actuelle pour pouvoir revenir en arrière si nécessaire. Le fichier airflow.cfg ou les variables d'environnement définissent le comportement de base. Sauvegardez-les explicitement.

Exemple : si vous exécutez Airflow dans Docker avec un fichier de configuration monté sur /opt/airflow/airflow.cfg, copiez-le :

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

Vérifiez la copie :

ls -l /backup/airflow/

Vous devriez voir un fichier horodaté.

Pour Airflow 3, la configuration peut être gérée via l'API ou des variables d'environnement. Utilisez airflow config list pour vider la configuration effective et l'enregistrer dans un fichier, mais soyez prudent avec les secrets. Par exemple :

airflow config list > /backup/airflow/config-$(date +%Y%m%d).txt

Examinez le fichier et masquez les valeurs sensibles avant de le stocker dans un emplacement partagé.

Si vous devez modifier une valeur de configuration, faites-le de manière contrôlée. Par exemple, pour modifier l'intervalle d'interrogation du processeur de DAG sur Airflow 3, éditez airflow.cfg ou définissez une variable d'environnement, puis redémarrez uniquement le service de processeur de DAG. Vérifiez que la modification a pris effet :

airflow config get-value dag_processor processor_poll_interval

Sortie attendue :

30

Si vous voyez l'ancienne valeur, le service n'a pas pris en compte la modification. Vérifiez le redémarrage et le chargement de la configuration.

Lors de la mise à niveau d'Airflow, ne sautez jamais la sauvegarde de la base de métadonnées. Testez également des DAG représentatifs dans un environnement de préproduction avant de mettre à niveau la production. Pour Airflow 2.7+ et 3.x, le chemin de mise à niveau recommandé comprend :

1. Arrêtez le planificateur et les workers (pour Airflow 2) ou les composants correspondants.
2. Sauvegardez la base de métadonnées.
3. Consultez les notes de version et la compatibilité des fournisseurs.
4. Exécutez airflow db migrate.
5. Redémarrez les services et exécutez les vérifications de santé.

Ne remplacez pas une migration par un simple redémarrage. Les changements de schéma de base de données nécessitent l'étape de migration.

Sauvegarde et restauration de la base de métadonnées

La base de métadonnées contient toutes les exécutions de DAG, instances de tâches, variables, connexions et configuration. Sans elle, vous perdez l'historique d'exécution et l'état de planification. La sauvegarder est essentiel.

Exemple PostgreSQL

Supposons que votre Airflow utilise PostgreSQL. Vous pouvez utiliser pg_dump pendant que la base de données est en ligne, mais pour une sauvegarde cohérente, il est préférable soit d'arrêter le planificateur, soit d'utiliser pg_dump avec précaution et les options --no-owner et --clean.

Pour un instantané cohérent sans arrêter Airflow, vous pouvez utiliser pg_dump avec --serializable-deferrable si votre PostgreSQL le prend en charge :

pg_dump -h postgres -U airflow -d airflow --serializable-deferrable -Fc -f /backup/airflow/airflow-metadata-$(date +%Y%m%d).dump

Cela crée un dump au format personnalisé. Vérifiez que le fichier dump existe et n'est pas vide :

ls -lh /backup/airflow/airflow-metadata-*.dump

La taille attendue dépend de votre volume de données, mais elle ne doit pas être nulle.

Pour restaurer :

pg_restore -h postgres -U airflow -d airflow --clean --if-exists /backup/airflow/airflow-metadata-20250101.dump

Après la restauration, vérifiez que la base de données est accessible :

airflow db check

Sortie attendue :

Connection successful.

Vérifiez ensuite que le schéma de base de données correspond à la version d'Airflow :

airflow db migrate

Cette commande appliquera toute migration en attente, mais après une restauration, elle devrait indiquer qu'aucune migration n'est nécessaire si la sauvegarde provient de la même version. S'il y a des migrations en attente, exécutez-les et vérifiez.

Exemple MySQL

Pour MySQL, utilisez mysqldump :

mysqldump -h mysql -u airflow -p airflow > /backup/airflow/airflow-metadata-$(date +%Y%m%d).sql

Pour restaurer :

mysql -h mysql -u airflow -p airflow < /backup/airflow/airflow-metadata-20250101.sql

Testez toujours la restauration sur une instance séparée avant de vous y fier.

Sauvegarde des fichiers DAG et des plugins

Les fichiers DAG définissent vos workflows. Ce sont généralement des scripts Python stockés dans le dags_folder. Trouvez l'emplacement :

airflow config get-value core dags_folder

Exemple de sortie :

/opt/airflow/dags

Sauvegardez l'intégralité du dossier, y compris les sous-répertoires :

tar -czf /backup/airflow/dags-$(date +%Y%m%d).tar.gz -C /opt/airflow/dags .

Les plugins sont stockés dans le dossier des plugins :

airflow config get-value core plugins_folder

Sauvegardez-les de manière similaire :

tar -czf /backup/airflow/plugins-$(date +%Y%m%d).tar.gz -C /opt/airflow/plugins .

Si vous stockez les DAG dans Git, assurez-vous que le dépôt est poussé vers un distant. Une sauvegarde simple est un git bundle :

git bundle create /backup/airflow/dags-repo-$(date +%Y%m%d).bundle --all

Vous pouvez restaurer avec git clone à partir du bundle.

Journaux et autres fichiers

Les journaux Airflow sont essentiels pour le débogage, mais ils peuvent être volumineux. Définissez une politique de rétention. Sauvegardez les journaux uniquement si nécessaire pour l'audit ou la conformité. Ils sont souvent stockés dans AIRFLOW_HOME/logs ou à un emplacement distant comme S3 si configuré.

Exemple de sauvegarde des journaux locaux :

tar -czf /backup/airflow/logs-$(date +%Y%m%d).tar.gz -C /opt/airflow/logs .

Si les journaux sont envoyés vers S3, aucune sauvegarde locale n'est nécessaire, mais vous pouvez activer la versioning sur le compartiment.

Sauvegardez également votre airflow.cfg, le fichier de variables d'environnement et tout script personnalisé.

Vérification et diagnostics après restauration

Une sauvegarde n'est utile que si vous pouvez la restaurer. Testez régulièrement votre processus de restauration. Voici une liste de vérification :

1. Restaurez la base de métadonnées sur une instance de test.
2. Restaurez les DAG et les plugins.
3. Démarrez les services Airflow.
4. Exécutez les vérifications de santé.
5. Vérifiez l'analyse des DAG : airflow dags list doit afficher vos DAG.
6. Vérifiez que le planificateur répond : airflow jobs check --job-type SchedulerJob --hostname $(hostname)
7. Déclenchez une exécution de DAG simple et vérifiez qu'elle se termine.

Exemple : après restauration, exécutez :

airflow dags list

La sortie attendue inclut vos identifiants de DAG, par exemple :

dag_id              | filepath            | owner   | paused
====================+=====================+=========+=======
example_dag_basic   | example_dag_basic.py| airflow | False

Si des DAG manquent, vérifiez le chemin du dossier DAG et les permissions.

Utilisez airflow tasks test pour un test manuel rapide sans planificateur :

airflow tasks test example_dag_basic print_date 2025-01-01

Cela exécute la tâche localement et affiche les journaux. En cas d'échec, le DAG ou les dépendances ne sont pas restaurés correctement.

Modes de défaillance et récupération

Plusieurs problèmes peuvent survenir lors de la sauvegarde et de la restauration. Voici les défaillances courantes et comment les gérer.

Défaillance : sauvegarde incohérente de la base de métadonnées

Si vous effectuez une sauvegarde pendant que le planificateur écrit activement, vous pourriez obtenir un dump incohérent. Cela peut entraîner des instances de tâches manquantes ou un état corrompu.

Récupération : utilisez toujours une méthode de sauvegarde cohérente. Pour PostgreSQL, utilisez pg_dump avec --serializable-deferrable, ou arrêtez temporairement le planificateur. Pour MySQL, utilisez mysqldump --single-transaction si vous utilisez InnoDB. Si vous disposez déjà d'une sauvegarde incohérente, vous devrez peut-être la refaire après avoir assuré la cohérence.

Défaillance : fichiers DAG manquants après restauration

Si les DAG ne sont pas présents après la restauration, le planificateur ne planifiera aucune exécution. Vérifiez le chemin dags_folder et les permissions.

Exemple d'erreur dans les journaux du planificateur :

FileNotFoundError: [Errno 2] No such file or directory: '/opt/airflow/dags/my_dag.py'

Récupération : assurez-vous que la sauvegarde des DAG a été extraite au bon emplacement et que l'utilisateur Airflow dispose des autorisations de lecture. Vérifiez avec ls -l et airflow dags list.

Défaillance : incompatibilité de schéma de base de données

Si la sauvegarde de la base de métadonnées provient d'une version antérieure, vous devrez peut-être exécuter airflow db migrate. Si la sauvegarde provient d'une version plus récente, elle peut ne pas être compatible.

Récupération : vérifiez la version d'Airflow et la version de la base de données. Exécutez airflow db migrate si nécessaire, mais ne rétrogradez pas. En cas d'incompatibilité, vous devrez peut-être utiliser une version intermédiaire ou reconstruire la base de données à partir des définitions de DAG.

Défaillance : la restauration réussit mais le planificateur ne démarre pas

Parfois, le planificateur échoue parce que la base de métadonnées est accessible mais qu'une configuration est incorrecte.

Vérifiez les journaux du planificateur pour détecter les erreurs. Problème courant : mauvaise chaîne de connexion à la base de données. Vérifiez avec airflow db check. Si la connexion échoue, corrigez la chaîne de connexion dans airflow.cfg ou la variable d'environnement et redémarrez.

Défaillance : secrets ou connexions manquants après restauration

Les connexions et variables sont stockées dans la base de métadonnées, elles devraient donc être restaurées avec celle-ci. Mais si vous avez recréé la base de données à partir de zéro, les connexions et variables peuvent être perdues.

Récupération : exportez régulièrement les connexions et variables à l'aide de airflow connections export et airflow variables export. Par exemple :

airflow connections export /backup/airflow/connections.json
airflow variables export /backup/airflow/variables.json

Vous pourrez ensuite les importer après une configuration de base de données fraîche :

airflow connections import /backup/airflow/connections.json
airflow variables import /backup/airflow/variables.json

Liste de contrôle des opérations pour la sauvegarde et la restauration

Voici une liste de contrôle concrète à suivre. Attribuez un responsable à chaque élément et définissez une fréquence de révision.

Les scripts de sauvegarde doivent être stockés dans un contrôle de version et révisés. Des alertes doivent être configurées en cas d'échec de sauvegarde.

Exemple de script de sauvegarde pour la base de métadonnées PostgreSQL, les DAG et les journaux :

#!/bin/bash
set -euo pipefail
BACKUP_DIR=/backup/airflow
DATE=$(date +%Y%m%d)
mkdir -p $BACKUP_DIR
pg_dump -h postgres -U airflow -d airflow --serializable-deferrable -Fc -f $BACKUP_DIR/airflow-metadata-$DATE.dump
tar -czf $BACKUP_DIR/dags-$DATE.tar.gz -C /opt/airflow/dags .
tar -czf $BACKUP_DIR/logs-$DATE.tar.gz -C /opt/airflow/logs .
# Optionnellement, pousser vers un stockage distant
# aws s3 cp $BACKUP_DIR s3://my-airflow-backups/$DATE --recursive

Exécutez ce script quotidiennement via cron ou un planificateur.

Erreurs courantes à éviter

1. Ne pas tester les restaurations : de nombreuses équipes sauvegardent mais ne testent jamais la restauration. Erreur : en cas de sinistre, la sauvegarde est inutilisable. Évitez-la en planifiant des tests de restauration mensuels dans un environnement de préproduction.

1. Sauvegarder sans cohérence : effectuer un simple pg_dump pendant qu'Airflow écrit peut conduire à des instantanés incohérents. Utilisez des options cohérentes ou mettez le planificateur en pause.

1. Ignorer la configuration et les secrets : la base de métadonnées ne suffit pas si vous avez des fichiers airflow.cfg ou des variables d'environnement personnalisés. Sauvegardez-les et chiffrez les secrets.

1. Oublier les dépendances des DAG : les DAG peuvent importer des modules personnalisés ou des plugins. S'ils ne sont pas sauvegardés, les DAG échouent après la restauration. Sauvegardez tout le dossier des plugins et toute bibliothèque personnalisée.

1. Ne pas versionner les sauvegardes : conservez plusieurs versions de sauvegarde pour permettre une récupération à un point dans le temps. Utilisez une politique de rétention, par exemple, gardez les sauvegardes quotidiennes pendant 30 jours et les mensuelles pendant 12 mois.

1. Supposer qu'Airflow 3 et 2 sont identiques : Airflow 3 a considérablement modifié l'architecture. Ne copiez pas aveuglément les procédures de sauvegarde d'Airflow 2. Vérifiez la santé des composants via l'API pour Airflow 3.

1. Laisser les secrets en texte clair : les chaînes de connexion dans les dumps de configuration peuvent exposer des mots de passe. Masquez ou chiffrez les sauvegardes.

Conclusion

Sauvegarder et restaurer Apache Airflow nécessite une attention particulière à la base de métadonnées, aux fichiers DAG, à la configuration et aux secrets. En suivant les commandes et vérifications pratiques de cet article, vous pouvez vous assurer que votre instance Airflow peut être récupérée rapidement et de manière fiable.

Commencez par un inventaire complet de votre configuration Airflow, implémentez le script de sauvegarde, puis pratiquez une restauration. Validez chaque étape avec des vérifications de santé et la liste des DAG. Attribuez clairement les responsabilités et révisez régulièrement le processus.

Votre sauvegarde ne vaut que par votre dernier test de restauration réussi. Faites de ce test une partie intégrante de vos opérations.