Exploitation - Dc-Maestro

Cette page présente les opérations d’exploitation de la stack Dc-Maestro : démarrage et arrêt, logs, sauvegarde, purge de l’historique et DAG de maintenance. Le paramétrage des images est décrit dans Configuration - Dc-Maestro.

Services et ordre de démarrage

Dc-Maestro est composé de services permanents et de services à exécution unique (migrations). Les services s’appuient sur Keycloak, PostgreSQL (bases dc_maestro et airflow) et Valkey, qui doivent être démarrés au préalable (voir Exploitation - Généralités).

Service Type Remarques

Service	Type	Remarques
db-migration	Exécution unique	Migre la base Maestro vers la version de l’image, après une sauvegarde optionnelle. À exécuter avant le démarrage du backend. Ne doit pas être redémarré automatiquement.
airflow-migration	Exécution unique	Migre la base Airflow et crée l’utilisateur de Maestro dans Airflow. À exécuter avant le démarrage des services Airflow.
socket-proxy	Permanent	Accès filtré à l’API Docker : nécessaire pour que le worker Airflow lance les conteneurs des tâches.
airflow-webserver, airflow-scheduler, airflow-worker	Permanents	Moteur d’exécution des pipelines. Ils partagent avec l’Upflower le répertoire des DAG (`/opt/airflow/dags`).
maestro-upflower	Permanent	Dépose dans le répertoire des DAG les DAG générés par Maestro, et livre les DAG de maintenance au démarrage.
backend, synchronizer, websockets	Permanents	API de Maestro, synchronisation avec Airflow, diffusion des événements d’exécution.
front-ui	Permanent	Interface web de Maestro.

db-migration

Exécution unique

Migre la base Maestro vers la version de l’image, après une sauvegarde optionnelle. À exécuter avant le démarrage du backend. Ne doit pas être redémarré automatiquement.

airflow-migration

Exécution unique

Migre la base Airflow et crée l’utilisateur de Maestro dans Airflow. À exécuter avant le démarrage des services Airflow.

socket-proxy

Permanent

Accès filtré à l’API Docker : nécessaire pour que le worker Airflow lance les conteneurs des tâches.

airflow-webserver, airflow-scheduler, airflow-worker

Permanents

Moteur d’exécution des pipelines. Ils partagent avec l’Upflower le répertoire des DAG (/opt/airflow/dags).

maestro-upflower

Permanent

Dépose dans le répertoire des DAG les DAG générés par Maestro, et livre les DAG de maintenance au démarrage.

backend, synchronizer, websockets

Permanents

API de Maestro, synchronisation avec Airflow, diffusion des événements d’exécution.

front-ui

Permanent

Interface web de Maestro.

Ordre de démarrage conseillé : migrations (db-migration, airflow-migration), puis socket-proxy, les services Airflow et l’Upflower, puis le backend (et ses deux services associés) et l’interface. L’arrêt se fait dans l’ordre inverse.

Contrôle de l’état des services

Service Port Contrôle

Service	Port	Contrôle
backend	8080	`curl http://localhost:8080/` (utilisé aussi comme contrôle de santé de l’image)
front-ui	8080	Interface web
airflow-webserver	8080	Interface web et API d’Airflow (`/api/v1/`, utilisée par Maestro)
maestro-upflower	8000	`/` (contrôle de santé de l’image)
socket-proxy	2375	API Docker filtrée, utilisée par le worker Airflow

backend

8080

curl http://localhost:8080/ (utilisé aussi comme contrôle de santé de l’image)

front-ui

8080

Interface web

airflow-webserver

8080

Interface web et API d’Airflow (/api/v1/, utilisée par Maestro)

maestro-upflower

8000

/ (contrôle de santé de l’image)

socket-proxy

2375

API Docker filtrée, utilisée par le worker Airflow

Les services synchronizer et websockets n’écoutent sur aucun port : consulter leurs logs.

Logs

Service Emplacement

Service	Emplacement
backend, synchronizer, websockets	Sortie standard du conteneur, et fichier à rotation `LOG_FILENAME` (par exemple `/log/maestro_logs.log`). La rotation se règle avec `LOG_MAXBYTES` et `LOG_BACKUPCOUNT`. Monter un volume sur `/log` est conseillé.
db-migration	Sortie standard, et `/log` si `LOG_FILENAME` pointe dessus
Services Airflow	Sortie standard. Logs d’exécution des tâches sous `/opt/airflow/logs` (monter un volume pour les conserver)
maestro-upflower	Sortie standard (niveau réglé par `LOGLEVEL`)

backend, synchronizer, websockets

Sortie standard du conteneur, et fichier à rotation LOG_FILENAME (par exemple /log/maestro_logs.log). La rotation se règle avec LOG_MAXBYTES et LOG_BACKUPCOUNT. Monter un volume sur /log est conseillé.

db-migration

Sortie standard, et /log si LOG_FILENAME pointe dessus

Services Airflow

Sortie standard. Logs d’exécution des tâches sous /opt/airflow/logs (monter un volume pour les conserver)

maestro-upflower

Sortie standard (niveau réglé par LOGLEVEL)

Après chaque mise à jour, vérifier dans les logs de db-migration et airflow-migration que les migrations se sont bien déroulées.

Sauvegarde et restauration

Nous conseillons d’effectuer des sauvegardes à froid, avec au préalable arrêt des services concernés. Les éléments à sauvegarder sont :

les bases de données dc_maestro (pipelines, planifications, droits) et airflow (métadonnées et historique des exécutions) : voir Exploitation - Gestion des données ;
le répertoire des DAG Airflow (/opt/airflow/dags), qui contient les DAG générés par Maestro (sous-répertoire maestro). Ces DAG peuvent être régénérés par Maestro, mais leur sauvegarde permet une reprise plus rapide. Les DAG de maintenance (sous-répertoire ops) sont redéposés à chaque démarrage de l’Upflower ;
optionnellement, les logs d’exécution des tâches (/opt/airflow/logs).

Le service db-migration peut aussi sauvegarder la base Maestro avant la migration (variable DUMP_DB à true) : le fichier dump_maestro_<date>.tar est écrit dans le volume monté sur /data/pg_dump.

Purge de l’historique des exécutions

Maestro conserve l’historique des exécutions des pipelines. Pour limiter la taille de la base, une purge peut être activée sur le backend : elle est désactivée par défaut, rien n’est supprimé tant que HISTORY_PURGE_ENABLED ne vaut pas true. Les paramètres sont décrits dans Configuration - Dc-Maestro.

Procédure conseillée : activer d’abord HISTORY_PURGE_DRY_RUN pour contrôler dans les logs ce qui serait supprimé, puis désactiver le mode simulation. Garder les mêmes valeurs de rétention (HISTORY_KEEP_RUNS, HISTORY_RETENTION_DAYS, HISTORY_RULE) que celles du DAG de maintenance airflow_db_cleanup.

DAG de maintenance d’Airflow

L’Upflower livre deux DAG de maintenance, airflow_db_cleanup (base d’Airflow) et airflow_logs_cleanup (fichiers de logs d’Airflow). Leur paramétrage est décrit dans Configuration - DAG de maintenance Airflow (ops). Du point de vue de l’exploitation :

Les DAG sont créés en pause et en simulation : ils n’agissent qu’après activation.
Mise en service : activer le DAG (hors pause, une seule fois : dans l’interface d’Airflow ou avec airflow dags unpause), le laisser s’exécuter en simulation, contrôler dans les logs de ses tâches ce qui serait supprimé, faire une sauvegarde de la base Airflow, puis activer les suppressions.
Les suppressions s’activent par OPS_DB_CLEANUP_APPLY / OPS_LOGS_CLEANUP_APPLY (environnement de l’Upflower, redémarrage nécessaire), par le paramètre apply lors d’un lancement manuel du DAG, ou par la variable Airflow db_cleanup_apply / logs_cleanup_apply positionnée à true.
Un changement de paramètre dans l’environnement de l’Upflower est pris en compte au redémarrage de l’Upflower, qui réécrit le fichier du DAG.
Sur une base volumineuse, réduire la rétention progressivement (par exemple OPS_DB_CLEANUP_KEEP_RUNS à 5000, puis 1000, puis 500).

Mise à jour

Sauvegarder les bases dc_maestro et airflow, et le répertoire des DAG.
Arrêter la stack, puis la redémarrer avec la nouvelle version des images (voir Mise à jour d’une version).
Les migrations s’exécutent (db-migration, airflow-migration). Au démarrage du synchronizer, les DAG existants sont migrés vers le format de la nouvelle version (MIGRATE_ON_UPDATE).
L’Upflower redépose les DAG de maintenance fournis avec la nouvelle version.
Consulter les notes techniques de version pour les changements de configuration (ports, utilisateur des images, etc.).

Dernière mise à jour le 2 novembre 2026 à 15:16