Environnement Local Astro

Cette compétence t'aide à gérer ton environnement Airflow local avec Astro CLI.

Deux modes : Docker (par défaut, utilise les conteneurs) et Standalone (sans Docker, utilise un venv local — nécessite Airflow 3 + uv).

Pour configurer un nouveau projet, consulte la compétence setting-up-astro-project. Quand Airflow est en cours d'exécution, utilise les outils MCP des compétences authoring-dags et testing-dags.

Démarrer / Arrêter / Redémarrer (Docker)

# Démarrer Airflow local (webserver à http://localhost:8080)
astro dev start

# Arrêter les conteneurs (préserve les données)
astro dev stop

# Tuer et supprimer les volumes (démarrage propre)
astro dev kill

# Redémarrer tous les conteneurs
astro dev restart

# Redémarrer un composant spécifique
astro dev restart --scheduler
astro dev restart --webserver

Identifiants par défaut : admin / admin

Redémarrer après modification : requirements.txt, packages.txt, Dockerfile

Mode Standalone ? Voir la section suivante.

Mode Standalone

Développement local sans Docker. Exécute Airflow directement sur ta machine dans un .venv/ géré par uv.

Prérequis : Airflow 3 (runtime 3.x), uv dans le PATH. Non supporté sur Windows.

Démarrer

# Une seule fois : définir standalone comme mode par défaut
astro config set dev.mode standalone

# Ou utiliser le drapeau par invocation
astro dev start --standalone

Drapeau	Description
`--foreground` / `-f`	Diffuser la sortie en avant-plan
`--port` / `-p`	Remplacer le port du webserver (défaut : 8080)
`--no-proxy`	Désactiver le reverse proxy

Arrêter / Tuer / Redémarrer

# Arrêter (préserve .venv)
astro dev stop

# Tuer (supprime .venv et .astro/standalone/ — démarrage propre)
astro dev kill

# Redémarrer (préserve .venv pour redémarrage rapide, utilise -k pour tuer d'abord)
astro dev restart

Si tu as utilisé --standalone au démarrage au lieu de définir la config, passe --standalone sur chaque commande ultérieure aussi (stop, kill, restart, bash, run, logs, etc.).

Emplacements d'état : venv dans .venv/, base de données et logs dans .astro/standalone/, DAGs depuis dags/.

Reverse Proxy

Exécute plusieurs projets Airflow localement sans conflits de ports. Fonctionne en modes Docker et standalone.

Chaque projet obtient un nom d'hôte comme <project-name>.localhost:6563. Visite http://localhost:6563 pour voir tous les projets actifs.

# Vérifier le statut du proxy et les routes actives
astro dev proxy status

# Forcer l'arrêt du proxy (redémarre automatiquement au prochain astro dev start)
astro dev proxy stop

Config	Commande
Changer le port du proxy	`astro config set proxy.port <port>`
Désactiver au démarrage	`astro dev start --no-proxy`

Port proxy par défaut : 6563

Vérifier le Statut

astro dev ps

Afficher les Logs

# Tous les logs
astro dev logs

# Composant spécifique
astro dev logs --scheduler
astro dev logs --webserver

# Suivre en temps réel
astro dev logs -f

Standalone : astro dev logs fonctionne de la même façon mais affiche un log unifié (pas de filtrage par composant).

Exécuter des Commandes Airflow CLI

# Ouvrir un shell avec l'environnement Airflow
astro dev bash

# Exécuter des commandes Airflow CLI
astro dev run airflow info
astro dev run airflow dags list

Standalone : Les mêmes commandes fonctionnent — bash ouvre un shell activé par venv, run exécute dans le venv.

Interroger l'API Airflow

Utilise astro api airflow pour interroger une instance Airflow locale en cours d'exécution. Préfère les opération IDs aux chemins URL.

Défauts : localhost:8080, admin/admin (détection automatique). Remplace avec --api-url, --username, --password.

Découverte

# Lister tous les endpoints
astro api airflow ls

# Filtrer par mot-clé
astro api airflow ls dags
astro api airflow ls task

# Afficher les paramètres et le schéma d'une opération
astro api airflow describe get_dag

Drapeaux Clés

Drapeau	Objectif
`-p key=value`	Paramètres de chemin
`-F key=value`	Champs corps/requête (conversion auto booléens/nombres)
`-q` / `--jq`	Filtre jq sur la réponse
`--paginate`	Récupérer toutes les pages
`-X` / `--method`	Remplacer la méthode HTTP
`--generate`	Afficher la commande curl au lieu d'exécuter

DAGs

# Lister tous les DAGs
astro api airflow get_dags

# Filtrer par motif (SQL LIKE — utilise les caractères % comme jokers)
astro api airflow get_dags -F dag_id_pattern=%etl%

# Obtenir un DAG spécifique
astro api airflow get_dag -p dag_id=my_dag

# Obtenir les détails complets (calendrier, paramètres, etc.)
astro api airflow get_dag_details -p dag_id=my_dag

# Pause / reprendre
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=true
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=false

# Afficher le code source du DAG
astro api airflow get_dag_source -p dag_id=my_dag

# Vérifier les erreurs d'import
astro api airflow get_import_errors

DAG Runs

# Lister les runs d'un DAG
astro api airflow get_dag_runs -p dag_id=my_dag

# Déclencher un run
astro api airflow trigger_dag_run -p dag_id=my_dag

# Déclencher avec config
astro api airflow trigger_dag_run -p dag_id=my_dag -F conf[key]=value

# Obtenir un run spécifique
astro api airflow get_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07

# Effacer (réexécuter) un DAG run
astro api airflow clear_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -F dry_run=false

Task Instances

# Lister les instances de tâche pour un run
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=manual__2026-04-07

# Utiliser ~ comme joker (tous les DAGs ou tous les runs)
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~

# Obtenir une instance de tâche spécifique
astro api airflow get_task_instance -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -p task_id=extract

# Effacer/recommencer les tâches échouées
astro api airflow post_clear_task_instances -p dag_id=my_dag \
  -F dag_run_id=manual__2026-04-07 -F only_failed=true -F dry_run=false

# Obtenir les logs de tâche
astro api airflow get_log -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 \
  -p task_id=extract -p try_number=1

Config & Connexions

astro api airflow get_connections
astro api airflow get_variables
astro api airflow get_config

Filtrage avec jq

# Lister uniquement les IDs de DAG
astro api airflow get_dags -q '.dags[].dag_id'

# Obtenir les IDs de tâches échouées d'un run
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~ \
  -q '[.task_instances[] | select(.state=="failed") | .task_id]'

Dépannage

Problème	Solution
Port 8080 en utilisation	Arrête d'autres conteneurs ou édite `.astro/config.yaml`
Le conteneur ne démarre pas	`astro dev kill` puis `astro dev start`
Installation de package échouée	Vérifie la syntaxe de `requirements.txt`
DAG n'apparaît pas	Exécute `astro dev parse` pour vérifier les erreurs d'import
Espace disque insuffisant	`docker system prune`
Standalone ne démarre pas	Assure-toi que `uv` est dans le PATH et que le runtime est 3.x
Conflit de port du proxy	`astro config set proxy.port <port>`
`.venv` corrompu	`astro dev kill` puis `astro dev start --standalone`

Réinitialiser l'Environnement

Quand les choses sont cassées :

astro dev kill
astro dev start

Mettre à Jour Airflow

Tester la compatibilité d'abord

astro dev upgrade-test

Changer la version

Édite Dockerfile :

FROM quay.io/astronomer/astro-runtime:13.0.0

Redémarre :
```
astro dev kill && astro dev start
```

Compétences Connexes

setting-up-astro-project : Initialiser les projets et configurer les dépendances
authoring-dags : Écrire des DAGs (utilise les outils MCP, nécessite Airflow en cours d'exécution)
testing-dags : Tester les DAGs (utilise les outils MCP, nécessite Airflow en cours d'exécution)
deploying-airflow : Déployer les DAGs en production (Astro, Docker Compose, Kubernetes)

managing-astro-local-env