Apache Airflow 3 : orchestrer ses workflows (DAGs, assets, Kubernetes)

Apache Airflow orchestre des workflows décrits en Python sous forme de DAGs (graphes acycliques dirigés) : des tâches enchaînées selon leurs dépendances, planifiées et surveillées. C'est l'outil de référence pour l'ETL, les pipelines de données et l'automatisation d'ops. Ce guide couvre Airflow 3 (version 3.2 en 2026), qui est une refonte majeure de la v2, pas une simple montée de version.

Vous allez installer Airflow 3 en local, écrire un DAG avec le nouveau Task SDK, planifier par assets, puis déployer sur Kubernetes avec le chart Helm officiel. Public visé : intermédiaire à avancé, à l'aise avec Python, Docker et un peu Kubernetes. Tous les exemples sont testés.

Vous venez d'Airflow 2 ?

Airflow 3 déplace du code et des composants. Les points qui cassent le plus souvent : schedule_interval devient schedule, execution_date disparaît au profit de logical_date, les imports d'authoring passent par airflow.sdk, et BashOperator/PythonOperator migrent dans le provider apache-airflow-providers-standard. La section « Ce qui change avec Airflow 3 » détaille la migration.

Ce que vous allez apprendre

• Comprendre l'architecture d'Airflow 3 et ce qui change depuis la v2.
• Installer Airflow 3 en local et écrire un DAG avec le Task SDK.
• Planifier par assets (scheduling orienté données).
• Déployer Airflow 3 sur Kubernetes avec Helm.

Les concepts d'Airflow

Avant le code, le vocabulaire. Ces notions sont stables entre les versions ; seule leur mise en oeuvre évolue.

• DAG : un workflow, décrit en Python, qui définit des tâches et leurs dépendances. Il ne contient pas la logique métier lourde, il l'orchestre.
• Task (tâche) : une unité de travail. En Airflow 3, on l'écrit surtout avec le décorateur @task (TaskFlow) plutôt qu'avec des operators explicites.
• Operator : un modèle de tâche prêt à l'emploi (exécuter du Bash, du Python, une requête SQL, lancer un pod Kubernetes).
• Scheduler : le composant qui décide quand lancer chaque tâche selon la planification et les dépendances.
• Executor : la stratégie d'exécution des tâches. LocalExecutor (un seul noeud), CeleryExecutor (workers distribués), KubernetesExecutor (un pod par tâche).

Ce qui change avec Airflow 3

Airflow 3 passe à une architecture orientée service. C'est le coeur de la refonte, et ça impacte le déploiement comme le code.

Domaine	Airflow 2	Airflow 3
Interface web	airflow webserver (Flask)	airflow api-server (FastAPI) qui sert l'API et une UI React
Parsing des DAGs	dans le scheduler	dag-processor séparé et obligatoire
Exécution des tâches	couplée au scheduler	Task Execution API + Task SDK : la tâche est isolée, sans accès direct à la base de métadonnées
Authoring	from airflow import DAG	from airflow.sdk import dag, task
Planification	schedule_interval	schedule
Date de run	execution_date	logical_date (et run_id)
Données	Datasets	Assets (scheduling data-aware, @asset)
Operators de base	intégrés	déplacés dans apache-airflow-providers-standard
Exécuteurs	dont SequentialExecutor	SequentialExecutor supprimé (utiliser LocalExecutor)

Glissez pour voir

Deux nouveautés structurantes accompagnent cette architecture : le versioning de DAG (chaque run reste attaché à la version du DAG au moment où il a démarré, même si le fichier change) et les DAG bundles (plusieurs sources de DAGs, dont des dépôts Git versionnés, au lieu du dossier unique de la v2).

Installer Airflow 3 en local

Le plus simple pour découvrir : la commande standalone, qui initialise la base, crée un compte admin et démarre tous les composants (api-server, scheduler, dag-processor, triggerer). Réservée au développement.

Docker (standalone)

mkdir -p dags
docker run -d --name airflow -p 8080:8080 \
  -v "$PWD/dags:/opt/airflow/dags" \
  apache/airflow:3.2.0 standalone

Le mot de passe admin s'affiche dans les logs, et l'API confirme la version :

docker logs airflow 2>&1 | grep "Password for user"
# Simple auth manager | Password for user 'admin': zZNbk2Ch9WdqeF6A

curl -s http://localhost:8080/api/v2/version
# {"version":"3.2.0", ...}

L'authentification par défaut est SimpleAuthManager et l'API vit sous /api/v2/ (l'ancien /api/v1 de la v2 est remplacé).

pip (avec constraints)

Airflow s'installe toujours avec un fichier de contraintes pour figer les versions des dépendances, sinon l'installation casse.

pip install "apache-airflow==3.2.0" \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt"

airflow standalone

Le dag-processor est un composant à part

En production, on ne lance plus un webserver monolithique. On démarre séparément airflow api-server, airflow scheduler, airflow dag-processor et airflow triggerer. standalone fait tout ça d'un coup pour le développement.

Écrire un premier DAG

Un DAG Airflow 3 s'écrit avec le Task SDK (airflow.sdk). Le style TaskFlow (@task) rend le code lisible : les valeurs de retour circulent entre tâches, sans manipuler d'XCom à la main.

Créez dags/etl_demo.py :

from datetime import datetime
from airflow.sdk import dag, task   # Airflow 3 : namespace airflow.sdk

@dag(schedule="@daily", start_date=datetime(2026, 1, 1), catchup=False, tags=["demo"])
def etl_demo():
    @task
    def extract() -> dict:
        return {"lignes": 3}

    @task
    def transform(data: dict) -> int:
        return data["lignes"] * 10

    @task
    def load(total: int) -> None:
        print(f"charge {total} enregistrements")

    load(transform(extract()))

etl_demo()

Notez schedule (et non schedule_interval) et catchup=False, désormais la valeur par défaut recommandée. Un nouveau DAG arrive en pause : on le réactive, puis on le déclenche.

docker exec airflow airflow dags unpause etl_demo
docker exec airflow airflow dags trigger etl_demo

La liste des runs confirme le succès, et les états des tâches montrent l'enchaînement :

docker exec airflow airflow dags list-runs etl_demo
# etl_demo | manual__2026-07-04T16:42:44... | success | ...

docker exec airflow airflow tasks states-for-dag-run etl_demo <run_id>
# extract   | success
# transform | success
# load      | success

execution_date a disparu

Sur les runs manuels ci-dessus, le champ logical_date est vide : en Airflow 3, un déclenchement manuel n'est plus rattaché à un intervalle de données. execution_date et les variables dérivées (prev_ds, next_ds, tomorrow_ds...) sont supprimées. Utilisez logical_date ou run_id dans vos templates.

Planifier par assets (data-aware)

Plutôt que de planifier un DAG toutes les heures « au cas où », Airflow 3 permet de le déclencher quand une donnée est produite. Les assets (ex-datasets) modélisent ces données par un URI, et un DAG peut être planifié sur un asset.

Un DAG producteur qui émet un asset :

from airflow.sdk import asset

@asset(uri="s3://asset-bucket/example.csv", schedule="@daily")
def ventes_du_jour():
    """Écrit les données ; l'asset est mis à jour à la fin."""
    ...

Un DAG consommateur planifié sur cet asset, déclenché automatiquement dès qu'il est mis à jour :

from airflow.sdk import DAG, Asset, task

ventes = Asset("s3://asset-bucket/example.csv")

with DAG(dag_id="rapport_ventes", schedule=ventes):
    @task
    def generer_rapport():
        ...

    generer_rapport()

Ce modèle remplace les planifications horaires fragiles par un chaînage piloté par les données, plus juste et moins coûteux.

Déployer Airflow 3 sur Kubernetes avec Helm

En production, Airflow se déploie sur Kubernetes avec le chart Helm officiel. Le chart apache-airflow/airflow en version 1.22 embarque Airflow 3.2.

1. Ajouter le dépôt Helm et vérifier la version applicative.

   helm repo add apache-airflow https://airflow.apache.org
   helm repo update
   helm search repo apache-airflow/airflow
   # CHART VERSION 1.22.0   APP VERSION 3.2.2

2. Installer le chart dans un namespace dédié. On choisit LocalExecutor pour un lab léger (pas de Redis ni de workers Celery).

   helm install airflow apache-airflow/airflow \
     --namespace airflow --create-namespace \
     --set executor=LocalExecutor

3. Vérifier les pods : l'architecture v3 apparaît clairement.

   kubectl get pods -n airflow
   # airflow-api-server-...      1/1 Running
   # airflow-dag-processor-...   2/2 Running
   # airflow-scheduler-0         2/2 Running
   # airflow-triggerer-0         2/2 Running
   # airflow-postgresql-0        1/1 Running

   Il n'y a pas de webserver : c'est l'api-server, et le dag-processor est un composant à part entière, conformément à Airflow 3.

4. Confirmer la version via l'API, en redirigeant le service.

   kubectl port-forward svc/airflow-api-server 8080:8080 -n airflow &
   curl -s http://localhost:8080/api/v2/version
   # {"version":"3.2.2", ...}

Quel executor sur Kubernetes ?

Pour de la production, préférez KubernetesExecutor (un pod isolé par tâche, scaling naturel) ou CeleryExecutor (workers persistants). LocalExecutor reste réservé aux petites instances et aux labs. Le choix se fait via --set executor=... et les valeurs du chart.

Pour charger vos DAGs dans le cluster, la voie recommandée en v3 est le git-sync via un DAG bundle Git : le dépôt de DAGs est synchronisé et versionné, au lieu de construire une image à chaque changement.

La CLI Airflow 3

Quelques commandes du quotidien, certaines nouvelles en v3.

airflow version                       # 3.2.0
airflow api-server                    # remplace 'airflow webserver'
airflow dag-processor                 # parsing des DAGs (composant séparé)
airflow dags list                     # lister les DAGs
airflow dags trigger <dag_id>         # déclencher un run
airflow dags reserialize              # forcer la (re)lecture des DAGs
airflow config update --fix           # migrer la config vers les clés v3
airflow db migrate                    # appliquer les migrations de schéma

Migrer de la version 2 vers la 3

La migration est outillée, ne la faites pas à la main.

1. Partez d'Airflow 2.7+, sauvegardez la base de métadonnées, puis nettoyez et resérialisez.

   airflow db clean
   airflow dags reserialize

2. Contrôlez vos DAGs avec Ruff, qui détecte et corrige les ruptures d'API (règle AIR301).

   ruff check dags/ --select AIR301 --show-fixes
   ruff check dags/ --select AIR301 --fix --unsafe-fixes   # réécrit les imports vers airflow.sdk

3. Installez le provider standard pour retrouver BashOperator et PythonOperator.

   pip install apache-airflow-providers-standard

4. Migrez le schéma puis adaptez les scripts de démarrage : airflow webserver devient airflow api-server, et il faut ajouter airflow dag-processor.

   airflow db migrate

Bonnes pratiques

• Un DAG orchestre, il ne calcule pas : déportez la logique lourde dans des tâches idempotentes, pas dans le fichier DAG.
• Écrivez avec le Task SDK (@task) : code plus lisible, passage de données sans XCom manuel, tâches isolées.
• Préférez les assets au planning horaire quand une tâche dépend d'une donnée produite ailleurs.
• Versionnez vos DAGs par Git via un bundle plutôt que de rebuild une image à chaque modification.
• Sur Kubernetes, isolez par namespace, choisissez l'executor selon la charge, et gérez les secrets hors des DAGs.

À retenir

• Airflow 3 est une refonte : api-server (FastAPI) à la place du webserver, dag-processor séparé, Task SDK qui isole les tâches.
• Le code d'authoring passe par airflow.sdk ; schedule remplace schedule_interval ; logical_date remplace execution_date.
• Les assets (ex-datasets) permettent un scheduling data-aware avec le décorateur @asset.
• Les operators de base vivent désormais dans apache-airflow-providers-standard.
• Le chart Helm officiel (1.22) déploie Airflow 3.2 avec l'architecture complète sur Kubernetes.
• La migration 2 vers 3 s'appuie sur Ruff (AIR301) et airflow db migrate, pas sur des retouches manuelles.

Prochaines étapes

Déployer avec Helm

Orchestrer avec Kubernetes

Conteneuriser avec Docker

Programmer en Python

×

📖 Voir la documentation →