Configuration - Dc-Maestro

Cette page présente le paramétrage des images du module Dc-Maestro, l’orchestrateur de pipelines de la solution Datachain.

Les images sont paramétrables via les fichiers *.env de docker ou des variables d’environnement.

Contrairement aux images Console et Marketplace, les images Dc-Maestro ne supportent actuellement pas les variables suffixées par _FILE : la procédure décrite dans A propos des variables d’environnements ne s’applique pas ici. Les valeurs sensibles (mots de passe, secrets Keycloak) sont à fournir en clair dans les variables d’environnement.

Vue d’ensemble

Dc-Maestro est livré sous la forme de plusieurs images. Une même image peut porter plusieurs services, qui se distinguent par leur commande de démarrage.

Les images s’exécutent sans privilèges root et sont compatibles avec OpenShift : voir Exécution sans privilèges.

Service	Image	Ports	Rôle
backend	maestro/maestro-backend	8080	API REST de Maestro
synchronizer	maestro/maestro-backend	Aucun	Synchronisation des pipelines avec Airflow
websockets	maestro/maestro-backend	Aucun	Diffusion des événements d’exécution en temps réel
db-migration	maestro/maestro-migrate	Aucun	Migration de la base de données Maestro (une seule exécution)
front-ui	maestro/maestro-ui	8080	Interface web
airflow-webserver, airflow-scheduler, airflow-worker, airflow-migration	maestro/maestro-airflow	8080 (airflow-webserver uniquement)	Moteur d’exécution Airflow (exécuteur Celery)
maestro-upflower	maestro/maestro-upflower	8000	Liaison Maestro / Airflow : dépôt des DAG générés par Maestro
socket-proxy	maestro/docker-proxy	2375	Accès filtré à l’API Docker, pour le lancement des tâches

Service

Image

Ports

Rôle

backend

maestro/maestro-backend

8080

API REST de Maestro

synchronizer

maestro/maestro-backend

Aucun

Synchronisation des pipelines avec Airflow

websockets

maestro/maestro-backend

Aucun

Diffusion des événements d’exécution en temps réel

db-migration

maestro/maestro-migrate

Aucun

Migration de la base de données Maestro (une seule exécution)

front-ui

maestro/maestro-ui

8080

Interface web

airflow-webserver, airflow-scheduler, airflow-worker, airflow-migration

maestro/maestro-airflow

8080 (airflow-webserver uniquement)

Moteur d’exécution Airflow (exécuteur Celery)

maestro-upflower

maestro/maestro-upflower

8000

Liaison Maestro / Airflow : dépôt des DAG générés par Maestro

socket-proxy

maestro/docker-proxy

2375

Accès filtré à l’API Docker, pour le lancement des tâches

Deux images supplémentaires ne sont pas des services : ce sont les images dans lesquelles s’exécutent les tâches des pipelines (maestro/maestro-python3.12-airflow-dc) et les notebooks DCCode (maestro/maestro-notebook).

Dc-Maestro utilise par ailleurs :

une base PostgreSQL pour Maestro (dc_maestro) et une pour Airflow (airflow) ;
un serveur Valkey (compatible Redis) : cache et files d’événements pour Maestro, broker Celery pour Airflow.

Dans une installation intégrée à la suite Datachain, ces bases sont portées par l’image dc/pg (valeurs dc_maestro et airflow de DATABASE_MODE) et le Valkey de Datachain : voir Gestion des données. Airflow utilise alors la base Valkey numéro 1, la base 0 étant réservée aux notifications de Datachain.

Module Backend - Image maestro/maestro-backend

Cette image porte l’API de Maestro, ainsi que les deux processus d’arrière-plan (synchronisation Airflow et événements WebSocket). En déploiement, trois services distincts utilisent la même image avec une commande différente.

Description de l’image

Description

Porte l’API REST de Dc-Maestro : gestion des instances Datachain, des pipelines, des planifications et des droits. Génère les DAG Airflow, synchronise leur état et diffuse les événements d’exécution.

Taille

~580Mo

Briques techniques

Python 3.12 / FastAPI / Uvicorn / SQLAlchemy (migrations Alembic)

Utilisateur

dc (uid 38330, groupe principal root (gid 0), répertoire personnel /home/maestro). L’image accepte aussi un uid quelconque imposé au démarrage (OpenShift) : cet uid appartient au groupe root (gid 0). Le répertoire monté sur /log doit être accessible en écriture à l’uid 38330 ou au groupe 0.

Commandes

Commande Utilité

python run.py webserver

API seule, sans WebSocket ni synchronisation Airflow. Utilisée pour le service backend.

python run.py synchronizer

Boucle de synchronisation avec Airflow. Exécute au démarrage la migration des DAG existants si MIGRATE_ON_UPDATE vaut 1. Utilisée pour le service synchronizer.

python run.py websockets

Boucle de diffusion des événements d’exécution. Utilisée pour le service websockets.

python run.py standalone

Les trois composants dans un même conteneur. Commande par défaut de l’image, adaptée à un déploiement simple.

Volumes

Chemin Utilité Obligatoire

/log

Répertoire du fichier de logs, lorsque LOG_FILENAME pointe dessus (valeur utilisée dans les déploiements fournis : /log/maestro_logs.log)

Non, mais il est conseillé

Logs

Les logs applicatifs sont écrits sur la sortie standard du conteneur et dans un fichier à rotation (LOG_FILENAME).

Log Utilité

maestro_logs.log

Logs applicatifs de l’API, de la synchronisation et des événements. Rotation par taille (LOG_MAXBYTES), nombre de fichiers conservés défini par LOG_BACKUPCOUNT.

Urls

Port Url Utilité

8080

Port d’écoute de l’API (variable PORT). Sert aussi de contrôle de santé de l’image (curl http://localhost:8080/). Dans les déploiements fournis, l’accès externe passe par le préfixe /api du nom de domaine de Maestro, retiré par le reverse proxy avant d’atteindre le conteneur.

Variables d’environnement

Les variables sont lues dans les variables d’environnement du conteneur ; à défaut, dans le fichier désigné par ENV_FILE (par défaut .env dans le répertoire de l’application). Une valeur d’environnement l’emporte toujours sur celle du fichier. Les booléens acceptent 0/1 ou true/false.

Les variables sans valeur par défaut sont obligatoires.

Base de données Maestro

Variable Défaut Description

Variable	Défaut	Description
PG_HOST	(aucun)	Hôte du serveur PostgreSQL
PG_PORT	5432	Port du serveur PostgreSQL
PG_DB	(aucun)	Nom de la base de données (`dc_maestro` pour une installation avec `dc/pg`)
PG_USER	(aucun)	Utilisateur PostgreSQL
PG_PWD	(aucun)	Mot de passe de l’utilisateur PostgreSQL
DB_URL	(construit)	URL SQLAlchemy complète (`postgresql+asyncpg://…`). Si elle est absente, elle est construite à partir des variables `PG_*` ci-dessus.
EXTRA_ENGINE_PARAMS	(aucun)	Paramètres du pool de connexions SQLAlchemy, au format JSON. Exemple : `{"pool_size":20,"max_overflow":5}`
CONNECT_ARGS	(aucun)	Arguments de connexion du pilote, au format JSON
ECHO_SQL	0	`1` : journalise les requêtes SQL

PG_HOST

(aucun)

Hôte du serveur PostgreSQL

PG_PORT

5432

Port du serveur PostgreSQL

PG_DB

(aucun)

Nom de la base de données (dc_maestro pour une installation avec dc/pg)

PG_USER

(aucun)

Utilisateur PostgreSQL

PG_PWD

(aucun)

Mot de passe de l’utilisateur PostgreSQL

DB_URL

(construit)

URL SQLAlchemy complète (postgresql+asyncpg://…). Si elle est absente, elle est construite à partir des variables PG_* ci-dessus.

EXTRA_ENGINE_PARAMS

(aucun)

Paramètres du pool de connexions SQLAlchemy, au format JSON. Exemple : {"pool_size":20,"max_overflow":5}

CONNECT_ARGS

(aucun)

Arguments de connexion du pilote, au format JSON

ECHO_SQL

1 : journalise les requêtes SQL

Valkey

Variable Défaut Description

Variable	Défaut	Description
VALKEY_HOST	(aucun)	Hôte du serveur Valkey. Les anciens noms `REDIS_HOST`, `REDIS_PORT` et `REDIS_PWD` sont acceptés à défaut.
VALKEY_PORT	6379	Port du serveur Valkey
VALKEY_PWD	(aucun)	Mot de passe Valkey, s’il est protégé
VALKEY_LOCK_TIMEOUT_S	60	Durée de vie (en secondes) des verrous posés par les différentes instances de Maestro

VALKEY_HOST

(aucun)

Hôte du serveur Valkey. Les anciens noms REDIS_HOST, REDIS_PORT et REDIS_PWD sont acceptés à défaut.

VALKEY_PORT

6379

Port du serveur Valkey

VALKEY_PWD

(aucun)

Mot de passe Valkey, s’il est protégé

VALKEY_LOCK_TIMEOUT_S

Durée de vie (en secondes) des verrous posés par les différentes instances de Maestro

Keycloak

Variable Défaut Description

Variable	Défaut	Description
DC_KEYCLOAK_HOST	(aucun)	URL du serveur Keycloak
DC_KEYCLOAK_REALM	(aucun)	Realm Keycloak (`dc-realm` dans les installations standard)
DC_KEYCLOAK_CLIENT_ID	(aucun)	Client Keycloak de l’interface Maestro (`maestro`)
DC_KEYCLOAK_CLIENT_SECRET	(aucun)	Secret de ce client. Obligatoire pour le démarrage ; laisser vide si le client est public.
DC_KEYCLOAK_CLIENT_BACKEND	(aucun)	Client Keycloak représentant l’API (`maestro_backend`)
DC_KEYCLOAK_CLIENT_AIRFLOW_ID	(aucun)	Client Keycloak utilisé par Airflow (`maestro_airflow`)
DC_KEYCLOAK_CLIENT_AIRFLOW_SECRET	(aucun)	Secret du client Airflow
DC_KEYCLOAK_ADMIN	(aucun)	Compte administrateur Keycloak utilisé par Maestro
DC_KEYCLOAK_ADMIN_PWD	(aucun)	Mot de passe de ce compte
DC_KEYCLOAK_ADMIN_REALM	master	Realm dans lequel le compte administrateur est défini
DC_MAESTRO_ADMIN_PWD	(aucun)	Mot de passe de l’utilisateur système `maestro-sys`, défini dans Keycloak (onglet Credentials) avec le rôle `maestro_admin` du client `maestro_backend`. Maestro l’utilise pour ses opérations internes, notamment la migration des DAG.
DC_KEYCLOAK_GROUPS_LABEL	user-groups	Nom de l’attribut Keycloak qui porte les groupes de l’utilisateur

DC_KEYCLOAK_HOST

(aucun)

URL du serveur Keycloak

DC_KEYCLOAK_REALM

(aucun)

Realm Keycloak (dc-realm dans les installations standard)

DC_KEYCLOAK_CLIENT_ID

(aucun)

Client Keycloak de l’interface Maestro (maestro)

DC_KEYCLOAK_CLIENT_SECRET

(aucun)

Secret de ce client. Obligatoire pour le démarrage ; laisser vide si le client est public.

DC_KEYCLOAK_CLIENT_BACKEND

(aucun)

Client Keycloak représentant l’API (maestro_backend)

DC_KEYCLOAK_CLIENT_AIRFLOW_ID

(aucun)

Client Keycloak utilisé par Airflow (maestro_airflow)

DC_KEYCLOAK_CLIENT_AIRFLOW_SECRET

(aucun)

Secret du client Airflow

DC_KEYCLOAK_ADMIN

(aucun)

Compte administrateur Keycloak utilisé par Maestro

DC_KEYCLOAK_ADMIN_PWD

(aucun)

Mot de passe de ce compte

DC_KEYCLOAK_ADMIN_REALM

master

Realm dans lequel le compte administrateur est défini

DC_MAESTRO_ADMIN_PWD

(aucun)

Mot de passe de l’utilisateur système maestro-sys, défini dans Keycloak (onglet Credentials) avec le rôle maestro_admin du client maestro_backend. Maestro l’utilise pour ses opérations internes, notamment la migration des DAG.

DC_KEYCLOAK_GROUPS_LABEL

user-groups

Nom de l’attribut Keycloak qui porte les groupes de l’utilisateur

Identification de l’instance

Variable	Défaut	Description
PLATEFORM_ID	default	Identifiant de la plateforme
MODULE_INSTANCE_ID	dcm-1	Identifiant de l’instance du module, utile lorsque plusieurs backends coexistent

Variable

Défaut

Description

PLATEFORM_ID

default

Identifiant de la plateforme

MODULE_INSTANCE_ID

dcm-1

Identifiant de l’instance du module, utile lorsque plusieurs backends coexistent

Intégration Airflow

Variable Défaut Description

Variable	Défaut	Description
AIRFLOW_API_URL	(aucun)	URL de l’API REST d’Airflow. Exemple : `http://airflow-api:8080/api/v1/`
AIRFLOW_UPFLOWER_URL	(aucun)	URL de l’Upflower. Exemple : `http://maestro-upflower:8000/`
AIRFLOW_USER	(aucun)	Utilisateur Airflow utilisé par Maestro (`maestro`)
AIRFLOW_PASSWORD	(aucun)	Mot de passe de cet utilisateur
AIRFLOW_DB_URI	(aucun)	Accès direct à la base Airflow, au format `utilisateur:motdepasse@hôte/airflow`. Optionnel : accélère la synchronisation.
AIRFLOW_ONLY_API	1	`1` : la synchronisation n’utilise que l’API Airflow. `0` : utilise aussi la connexion directe `AIRFLOW_DB_URI`.
AIRFLOW_SYNC_DELAY_MIN	5	Fréquence de la synchronisation avec Airflow, en minutes
STATUS_STREAM_DELAY_SEC	10	Fréquence de diffusion des événements d’exécution, en secondes
MIGRATE_ON_UPDATE	1	`1` : à chaque démarrage du synchronizer, migre les DAG existants vers le format de la version installée. `0` : désactivé (à réserver aux services autres que le synchronizer).

AIRFLOW_API_URL

(aucun)

URL de l’API REST d’Airflow. Exemple : http://airflow-api:8080/api/v1/

AIRFLOW_UPFLOWER_URL

(aucun)

URL de l’Upflower. Exemple : http://maestro-upflower:8000/

AIRFLOW_USER

(aucun)

Utilisateur Airflow utilisé par Maestro (maestro)

AIRFLOW_PASSWORD

(aucun)

Mot de passe de cet utilisateur

AIRFLOW_DB_URI

(aucun)

Accès direct à la base Airflow, au format utilisateur:motdepasse@hôte/airflow. Optionnel : accélère la synchronisation.

AIRFLOW_ONLY_API

1 : la synchronisation n’utilise que l’API Airflow. 0 : utilise aussi la connexion directe AIRFLOW_DB_URI.

AIRFLOW_SYNC_DELAY_MIN

Fréquence de la synchronisation avec Airflow, en minutes

STATUS_STREAM_DELAY_SEC

Fréquence de diffusion des événements d’exécution, en secondes

MIGRATE_ON_UPDATE

1 : à chaque démarrage du synchronizer, migre les DAG existants vers le format de la version installée. 0 : désactivé (à réserver aux services autres que le synchronizer).

Exécution des tâches

Ces variables définissent comment les tâches des pipelines sont lancées par Airflow.

Variable Défaut Description

Variable	Défaut	Description
DC_AFJOB_IMAGE	(aucun)	Image dans laquelle s’exécutent les tâches Datachain (`maestro/maestro-python3.12-airflow-dc:<version>`). Obligatoire en pratique : Maestro ne démarre pas sans elle.
DEPLOY_MODE	SWARM	Mode de déploiement : `SWARM` ou `K8S`
DC_AF_OPERATOR	DockerOperator	Opérateur Airflow utilisé par défaut
DOCKER_URI	tcp://socket-proxy:2375	Adresse de l’API Docker utilisée par les tâches (en pratique le service `socket-proxy`)
DOCKER_NETWORK	(aucun)	Réseau Docker auquel rattacher le conteneur de chaque tâche
DOCKER_NETWORKS	(aucun)	Pour les tâches DCCode : liste de réseaux séparés par des `;`. Les conteneurs des tâches doivent rejoindre le réseau du backend pour joindre `MAESTRO_PRIVATE_API_URL`.
DOCKER_SWARM_PLACEMENT	(aucun)	Contraintes de placement Swarm des conteneurs de tâches
DOCKER_FORCE_PULL	false	`true` : tire l’image avant chaque tâche
ADOBIS_REGISTRY_CONN_ID	(aucun)	Identifiant de la connexion Airflow utilisée pour s’authentifier auprès du registre d’images lors du tirage de l’image d’une tâche Docker. La connexion est déclarée côté Airflow (variable `AIRFLOW_CONN_<IDENTIFIANT>`). Non défini : aucune authentification n’est tentée.
K8S_NAMESPACE	datachain	Kubernetes : namespace dans lequel lancer les tâches
K8S_REGISTRY_SECRETS	datachain-ovh-registry-credential	Kubernetes : secret utilisé pour tirer les images
K8S_AFFINITY	(aucun)	Kubernetes : règles d’affinité des pods de tâches
K8S_SECURITY_CONTEXT	`{"fsGroup": 1000, "runAsUser": 1000}`	Kubernetes : contexte de sécurité des pods DCCode
K8S_DCCODE_IMAGE	(aucun)	Kubernetes : image des tâches DCCode

DC_AFJOB_IMAGE

(aucun)

Image dans laquelle s’exécutent les tâches Datachain (maestro/maestro-python3.12-airflow-dc:<version>). Obligatoire en pratique : Maestro ne démarre pas sans elle.

DEPLOY_MODE

SWARM

Mode de déploiement : SWARM ou K8S

DC_AF_OPERATOR

DockerOperator

Opérateur Airflow utilisé par défaut

DOCKER_URI

tcp://socket-proxy:2375

Adresse de l’API Docker utilisée par les tâches (en pratique le service socket-proxy)

DOCKER_NETWORK

(aucun)

Réseau Docker auquel rattacher le conteneur de chaque tâche

DOCKER_NETWORKS

(aucun)

Pour les tâches DCCode : liste de réseaux séparés par des ;. Les conteneurs des tâches doivent rejoindre le réseau du backend pour joindre MAESTRO_PRIVATE_API_URL.

DOCKER_SWARM_PLACEMENT

(aucun)

Contraintes de placement Swarm des conteneurs de tâches

DOCKER_FORCE_PULL

false

true : tire l’image avant chaque tâche

ADOBIS_REGISTRY_CONN_ID

(aucun)

Identifiant de la connexion Airflow utilisée pour s’authentifier auprès du registre d’images lors du tirage de l’image d’une tâche Docker. La connexion est déclarée côté Airflow (variable AIRFLOW_CONN_<IDENTIFIANT>). Non défini : aucune authentification n’est tentée.

K8S_NAMESPACE

datachain

Kubernetes : namespace dans lequel lancer les tâches

K8S_REGISTRY_SECRETS

datachain-ovh-registry-credential

Kubernetes : secret utilisé pour tirer les images

K8S_AFFINITY

(aucun)

Kubernetes : règles d’affinité des pods de tâches

K8S_SECURITY_CONTEXT

{"fsGroup": 1000, "runAsUser": 1000}

Kubernetes : contexte de sécurité des pods DCCode

K8S_DCCODE_IMAGE

(aucun)

Kubernetes : image des tâches DCCode

DCCode

Variable Défaut Description

Variable	Défaut	Description
DCCODE_LINKER_URL	(aucun)	URL (privée) du service `dccode_linker`
DCCODE_PUBLIC_URL	localhost	URL publique de DCCode
DCCODE_RUN_IMAGE	(image de référence)	Image dans laquelle s’exécutent les notebooks DCCode (`maestro/maestro-notebook:<version>`). Il est recommandé de la renseigner explicitement : la valeur par défaut référence une version de développement.

DCCODE_LINKER_URL

(aucun)

URL (privée) du service dccode_linker

DCCODE_PUBLIC_URL

localhost

URL publique de DCCode

DCCODE_RUN_IMAGE

(image de référence)

Image dans laquelle s’exécutent les notebooks DCCode (maestro/maestro-notebook:<version>). Il est recommandé de la renseigner explicitement : la valeur par défaut référence une version de développement.

Envoi d’e-mails (SMTP)

Variable Défaut Description

Variable	Défaut	Description
SMTP_SERVER	(aucun)	Serveur SMTP
SMTP_PORT	(aucun)	Port du serveur SMTP (25, 465 ou 587)
SMTP_SENDER	maestro-noreply@adobisgroup.fr	Adresse de l’expéditeur
DC_MAESTRO_ADMIN_EMAIL	(aucun)	Adresse électronique de l’administrateur de l’instance : elle est ajoutée aux destinataires des e-mails de notification des pipelines. Doit être une adresse valide, sinon le démarrage échoue.
SMTP_USER	(aucun)	Compte SMTP. Sans `SMTP_USER` ni `SMTP_PASSWORD`, aucune authentification n’est faite (relais interne, port 25 par exemple).
SMTP_PASSWORD	(aucun)	Mot de passe du compte SMTP
SMTP_STARTTLS	true	STARTTLS après la connexion (ports 25 et 587)
SMTP_SSL	false	SSL implicite dès la connexion (port 465). Prioritaire sur `SMTP_STARTTLS`.
SMTP_TIMEOUT	30	Délai, en secondes, de la connexion et de chaque échange SMTP
TEMPLATE_PATH	app/core/templates/	Répertoire des modèles d’e-mails

SMTP_SERVER

(aucun)

Serveur SMTP

SMTP_PORT

(aucun)

Port du serveur SMTP (25, 465 ou 587)

SMTP_SENDER

maestro-noreply@adobisgroup.fr

Adresse de l’expéditeur

DC_MAESTRO_ADMIN_EMAIL

(aucun)

Adresse électronique de l’administrateur de l’instance : elle est ajoutée aux destinataires des e-mails de notification des pipelines. Doit être une adresse valide, sinon le démarrage échoue.

SMTP_USER

(aucun)

Compte SMTP. Sans SMTP_USER ni SMTP_PASSWORD, aucune authentification n’est faite (relais interne, port 25 par exemple).

SMTP_PASSWORD

(aucun)

Mot de passe du compte SMTP

SMTP_STARTTLS

true

STARTTLS après la connexion (ports 25 et 587)

SMTP_SSL

false

SSL implicite dès la connexion (port 465). Prioritaire sur SMTP_STARTTLS.

SMTP_TIMEOUT

Délai, en secondes, de la connexion et de chaque échange SMTP

TEMPLATE_PATH

app/core/templates/

Répertoire des modèles d’e-mails

Adresses de Maestro

Variable Défaut Description

Variable	Défaut	Description
MAESTRO_PUBLIC_URL	(aucun)	Adresse où les utilisateurs ouvrent Maestro (l’interface web) : utilisée pour les liens des e-mails. À défaut sont lues les anciennes `MAESTRO_FRONT_URL`, puis `MAESTRO_HOST_URL`. Sans aucune des trois, les e-mails n’ont pas de lien.
MAESTRO_PRIVATE_API_URL	(aucun)	Adresse de l’API de Maestro, telle que les conteneurs des tâches la voient (`DCM_HOST_URL`). En Swarm : le nom du service et non d’un conteneur, par exemple `http://maestro-backend`. Sans elle, les tâches de déclenchement de pipeline échouent (`Environment variable DCM_HOST_URL is missing`).
DC_MAESTRO_API_PREFIX	(vide)	Préfixe d’URL (par exemple `/api`) sous lequel un reverse proxy publie l’API, lorsqu’il le retire avant de transmettre la requête au conteneur. Il ne change pas les adresses servies par le conteneur : il sert uniquement à ce que la documentation interactive de l’API (`/docs`) construise des adresses correctes derrière ce proxy. Facultatif : inutile pour les déploiements standard. Doit commencer par `/`.
USE_INSTANCE_PRIVATE_URL	(non défini)	Si la variable est définie (quelle que soit sa valeur, y compris `0`), Maestro joint les instances Datachain par leur adresse privée (réseau interne) plutôt que publique. Pour désactiver, ne pas définir la variable.

MAESTRO_PUBLIC_URL

(aucun)

Adresse où les utilisateurs ouvrent Maestro (l’interface web) : utilisée pour les liens des e-mails. À défaut sont lues les anciennes MAESTRO_FRONT_URL, puis MAESTRO_HOST_URL. Sans aucune des trois, les e-mails n’ont pas de lien.

MAESTRO_PRIVATE_API_URL

(aucun)

Adresse de l’API de Maestro, telle que les conteneurs des tâches la voient (DCM_HOST_URL). En Swarm : le nom du service et non d’un conteneur, par exemple http://maestro-backend. Sans elle, les tâches de déclenchement de pipeline échouent (Environment variable DCM_HOST_URL is missing).

DC_MAESTRO_API_PREFIX

(vide)

Préfixe d’URL (par exemple /api) sous lequel un reverse proxy publie l’API, lorsqu’il le retire avant de transmettre la requête au conteneur. Il ne change pas les adresses servies par le conteneur : il sert uniquement à ce que la documentation interactive de l’API (/docs) construise des adresses correctes derrière ce proxy. Facultatif : inutile pour les déploiements standard. Doit commencer par /.

USE_INSTANCE_PRIVATE_URL

(non défini)

Si la variable est définie (quelle que soit sa valeur, y compris 0), Maestro joint les instances Datachain par leur adresse privée (réseau interne) plutôt que publique. Pour désactiver, ne pas définir la variable.

Purge de l’historique

La purge de l’historique des exécutions est désactivée par défaut : rien n’est supprimé tant que HISTORY_PURGE_ENABLED ne vaut pas true.

Variable Défaut Description

Variable	Défaut	Description
HISTORY_PURGE_ENABLED	false	Active la purge
HISTORY_PURGE_DRY_RUN	false	`true` : la purge journalise seulement ce qu’elle supprimerait
HISTORY_KEEP_RUNS	500	Nombre maximal d’exécutions conservées par pipeline (les plus récentes)
HISTORY_RETENTION_DAYS	548	Âge maximal d’une exécution, en jours (548 jours = 18 mois)
HISTORY_RULE	cap	`cap` : une exécution est purgée dès qu’elle dépasse le nombre maximal OU l’âge maximal. `protect` : seulement si elle dépasse les deux.
HISTORY_PURGE_DELETED_PIPELINES	true	Purge aussi l’historique des pipelines qui n’existent plus
HISTORY_SYNC_KEEP_DAYS	30	Durée de conservation, en jours, des lignes de synchronisation (la dernière synchronisation réussie est toujours conservée)
HISTORY_PURGE_HOUR	3	La purge s’exécute une fois par jour, à partir de cette heure (0-23, heure du serveur)
HISTORY_PURGE_BATCH	500	Nombre d’exécutions supprimées par transaction
HISTORY_PURGE_MAX_SECONDS	600	Durée maximale d’une purge, en secondes (le reste est traité le lendemain)

HISTORY_PURGE_ENABLED

false

Active la purge

HISTORY_PURGE_DRY_RUN

false

true : la purge journalise seulement ce qu’elle supprimerait

HISTORY_KEEP_RUNS

500

Nombre maximal d’exécutions conservées par pipeline (les plus récentes)

HISTORY_RETENTION_DAYS

548

Âge maximal d’une exécution, en jours (548 jours = 18 mois)

HISTORY_RULE

cap

cap : une exécution est purgée dès qu’elle dépasse le nombre maximal OU l’âge maximal. protect : seulement si elle dépasse les deux.

HISTORY_PURGE_DELETED_PIPELINES

true

Purge aussi l’historique des pipelines qui n’existent plus

HISTORY_SYNC_KEEP_DAYS

Durée de conservation, en jours, des lignes de synchronisation (la dernière synchronisation réussie est toujours conservée)

HISTORY_PURGE_HOUR

La purge s’exécute une fois par jour, à partir de cette heure (0-23, heure du serveur)

HISTORY_PURGE_BATCH

500

Nombre d’exécutions supprimées par transaction

HISTORY_PURGE_MAX_SECONDS

600

Durée maximale d’une purge, en secondes (le reste est traité le lendemain)

Les valeurs HISTORY_KEEP_RUNS, HISTORY_RETENTION_DAYS et HISTORY_RULE ont les mêmes valeurs par défaut que le DAG de maintenance Airflow airflow_db_cleanup : il est recommandé de les garder identiques des deux côtés.

Logs et exécution

Variable Défaut Description

Variable	Défaut	Description
LOG_FILENAME	/opt/adobis/logs/maestro.log	Chemin du fichier de logs. Les déploiements fournis utilisent `/log/maestro_logs.log`.
LOG_MAXBYTES	10000000	Taille maximale d’un fichier de logs avant rotation, en octets (10 Mo par défaut)
LOG_BACKUPCOUNT	3	Nombre de fichiers de logs archivés conservés
DEBUG	0	Active les logs de débogage
HOST	0.0.0.0 (image)	Adresse d’écoute de l’API
PORT	8080 (image)	Port d’écoute de l’API
UVICORN_WORKERS	8 (image)	Nombre de processus Uvicorn de l’API. Seul le service backend l’utilise.
TTL_CACHE_MIN	5	Durée de vie, en minutes, du cache interne
ENV_FILE	.env	Fichier de variables lu en complément de l’environnement
DEV	0	Mode développement (rechargement automatique du code, un seul processus). Ne pas utiliser en production.

LOG_FILENAME

/opt/adobis/logs/maestro.log

Chemin du fichier de logs. Les déploiements fournis utilisent /log/maestro_logs.log.

LOG_MAXBYTES

10000000

Taille maximale d’un fichier de logs avant rotation, en octets (10 Mo par défaut)

LOG_BACKUPCOUNT

Nombre de fichiers de logs archivés conservés

DEBUG

Active les logs de débogage

HOST

0.0.0.0 (image)

Adresse d’écoute de l’API

PORT

8080 (image)

Port d’écoute de l’API

UVICORN_WORKERS

8 (image)

Nombre de processus Uvicorn de l’API. Seul le service backend l’utilise.

TTL_CACHE_MIN

Durée de vie, en minutes, du cache interne

ENV_FILE

.env

Fichier de variables lu en complément de l’environnement

DEV

Mode développement (rechargement automatique du code, un seul processus). Ne pas utiliser en production.

Fichier de configuration

L’image embarque un fichier .env par défaut, que les variables d’environnement du conteneur surchargent. Exemple de fichier backend.env pour un déploiement Docker Swarm (les valeurs entre chevrons sont à remplacer) :

# Base de données Maestro
PG_HOST=<hôte postgresql>
PG_PORT=5432
PG_DB=dc_maestro
PG_USER=<utilisateur>
PG_PWD=<mot de passe>

# Valkey
VALKEY_HOST=<hôte valkey>

# Keycloak
DC_KEYCLOAK_HOST=<url publique de keycloak>
DC_KEYCLOAK_REALM=dc-realm
DC_KEYCLOAK_CLIENT_ID=maestro
DC_KEYCLOAK_CLIENT_SECRET=<secret du client maestro>
DC_KEYCLOAK_ADMIN=<administrateur keycloak>
DC_KEYCLOAK_ADMIN_PWD=<mot de passe>
DC_KEYCLOAK_ADMIN_REALM=master
DC_KEYCLOAK_CLIENT_AIRFLOW_ID=maestro_airflow
DC_KEYCLOAK_CLIENT_AIRFLOW_SECRET=<secret du client maestro_airflow>
DC_KEYCLOAK_CLIENT_BACKEND=maestro_backend
DC_MAESTRO_ADMIN_PWD=<mot de passe de maestro-sys>

# Airflow
AIRFLOW_UPFLOWER_URL=http://maestro-upflower:8000/
AIRFLOW_API_URL=http://airflow-api:8080/api/v1/
AIRFLOW_USER=maestro
AIRFLOW_PASSWORD=<mot de passe de l'utilisateur airflow maestro>
AIRFLOW_ONLY_API=1
DOCKER_URI=tcp://socket-proxy:2375
DC_AFJOB_IMAGE=<registre>/maestro/maestro-python3.12-airflow-dc:<version>
DEPLOY_MODE=SWARM

# Adresses de Maestro
MAESTRO_PUBLIC_URL=https://<nom de domaine de maestro>
MAESTRO_PRIVATE_API_URL=http://maestro-backend

# SMTP
SMTP_SERVER=<serveur smtp>
SMTP_PORT=587
SMTP_SENDER=<expéditeur>
SMTP_USER=<compte smtp>
SMTP_PASSWORD=<mot de passe>

# Logs
LOG_FILENAME=/log/maestro_logs.log
LOG_MAXBYTES=104800
LOG_BACKUPCOUNT=3

EXTRA_ENGINE_PARAMS={"pool_size":20,"max_overflow":5}
STATUS_STREAM_DELAY_SEC=10
AIRFLOW_SYNC_DELAY_MIN=5

Chacune des variables suivantes n’est lue que par un seul service. Pour les ajuster, les définir au niveau de ce service dans le fichier de déploiement (docker-compose) plutôt que dans backend.env, partagé par tous les services :

Variable	Service	Défaut	Rôle
UVICORN_WORKERS	backend	8 (image)	Nombre de processus Uvicorn de l’API
MIGRATE_ON_UPDATE	synchronizer	1	Migration des DAG existants à chaque démarrage
AIRFLOW_SYNC_DELAY_MIN	synchronizer	5	Fréquence de la synchronisation avec Airflow, en minutes
STATUS_STREAM_DELAY_SEC	websockets	10	Fréquence de diffusion des événements d’exécution, en secondes

Variable

Service

Défaut

Rôle

UVICORN_WORKERS

backend

8 (image)

Nombre de processus Uvicorn de l’API

MIGRATE_ON_UPDATE

synchronizer

Migration des DAG existants à chaque démarrage

AIRFLOW_SYNC_DELAY_MIN

synchronizer

Fréquence de la synchronisation avec Airflow, en minutes

STATUS_STREAM_DELAY_SEC

websockets

Fréquence de diffusion des événements d’exécution, en secondes

À titre d’exemple, les déploiements Docker Swarm fournis réduisent la fréquence de synchronisation à 2 minutes et celle des événements à 5 secondes, et peuvent limiter l’API à 3 processus.

Module Migration - Image maestro/maestro-migrate

Cette image applique les migrations de la base de données de Maestro (Alembic). Elle est exécutée une fois à chaque installation ou mise à jour, avant le démarrage du backend, puis s’arrête.

Description de l’image

Description

Migre le schéma de la base de données Maestro vers la version de l’image (alembic upgrade head), après une sauvegarde optionnelle de la base.

Taille

~540Mo

Briques techniques

Python 3.12 / Alembic / client PostgreSQL (pg_dump)

Utilisateur

dc (uid 38330, groupe principal root (gid 0), répertoire personnel /home/maestro). L’image accepte aussi un uid quelconque imposé au démarrage (OpenShift) : cet uid appartient au groupe root (gid 0). Les répertoires montés sur /data/pg_dump et /log doivent être accessibles en écriture à l’uid 38330 ou au groupe 0 ; un volume nommé vide hérite des droits corrects de l’image au premier démarrage.

Volumes

Chemin Utilité Obligatoire

/data/pg_dump

Répertoire dans lequel est écrit la sauvegarde de la base avant migration (dump_maestro_<date>.tar, au format tar de pg_dump)

Seulement si DUMP_DB vaut true

/log

Répertoire de logs, si LOG_FILENAME pointe dessus

Non

Urls

Aucune : le conteneur s’exécute puis s’arrête. Le service ne doit pas être redémarré automatiquement (politique de redémarrage none).

Variables d’environnement

Variable Défaut Description

Variable	Défaut	Description
PG_HOST	(aucun)	Hôte du serveur PostgreSQL
PG_PORT	5432	Port du serveur PostgreSQL
PG_DB	(aucun)	Nom de la base de données (`dc_maestro`)
PG_USER	(aucun)	Utilisateur PostgreSQL. Doit pouvoir modifier le schéma.
PG_PWD	(aucun)	Mot de passe de l’utilisateur PostgreSQL
DUMP_DB	(désactivé)	La valeur `true` (en minuscules, toute autre valeur est ignorée) déclenche une sauvegarde de la base avant la migration. Le conteneur attend que PostgreSQL réponde avant de la lancer.
RESET_DB	(désactivé)	La valeur `true` supprime toutes les données de Maestro (`alembic downgrade base`) après confirmation interactive. Inutilisable en service Swarm (aucune saisie possible) : réservé aux environnements de développement.

PG_HOST

(aucun)

Hôte du serveur PostgreSQL

PG_PORT

5432

Port du serveur PostgreSQL

PG_DB

(aucun)

Nom de la base de données (dc_maestro)

PG_USER

(aucun)

Utilisateur PostgreSQL. Doit pouvoir modifier le schéma.

PG_PWD

(aucun)

Mot de passe de l’utilisateur PostgreSQL

DUMP_DB

(désactivé)

La valeur true (en minuscules, toute autre valeur est ignorée) déclenche une sauvegarde de la base avant la migration. Le conteneur attend que PostgreSQL réponde avant de la lancer.

RESET_DB

(désactivé)

La valeur true supprime toutes les données de Maestro (alembic downgrade base) après confirmation interactive. Inutilisable en service Swarm (aucune saisie possible) : réservé aux environnements de développement.

Le service doit accéder à la même base que le backend. Les variables PG_* sont les mêmes que celles du backend.

Fichier de configuration

PG_HOST=<hôte postgresql>
PG_PORT=5432
PG_DB=dc_maestro
PG_USER=<utilisateur>
PG_PWD=<mot de passe>
DUMP_DB=true

Module Interface - Image maestro/maestro-ui

Cette image sert l’interface web de Maestro (application Angular). Sa configuration est injectée au démarrage du conteneur dans les fichiers de l’application : elle ne nécessite pas de reconstruction de l’image.

Description de l’image

Description

Interface web de Dc-Maestro : conception, planification et suivi des pipelines.

Taille

~85Mo

Briques techniques

Application Angular servie par Nginx (alpine)

Utilisateur

nginx (uid 101, groupe principal root (gid 0)). L’image accepte aussi un uid quelconque imposé au démarrage (OpenShift) : cet uid appartient au groupe root (gid 0).

Urls

Port Url Utilité

8080

Port d’écoute de l’interface. L’interface appelle directement l’API et les WebSocket de Maestro (MAESTRO_API_URL, MAESTRO_WS_URL) : ces adresses doivent être joignables depuis le navigateur.

Variables d’environnement

Variable Défaut Description

Variable	Défaut	Description
MAESTRO_API_URL	(aucun)	URL publique de l’API de Maestro, vue du navigateur. Exemple : `https://<nom de domaine de maestro>/api`
MAESTRO_WS_URL	(aucun)	URL publique des WebSocket de Maestro. Exemple : `wss://<nom de domaine de maestro>/api`
MAESTRO_KEYCLOAK_AUTH_URL	(aucun)	URL d’authentification Keycloak, vue du navigateur (se termine par `/auth`)
MAESTRO_KEYCLOAK_REALM	(aucun)	Realm Keycloak (`dc-realm`)
MAESTRO_KEYCLOAK_CLIENT_ID	(aucun)	Client Keycloak de l’interface (`maestro`)
DOCUMENTATION_BASE_URL	`https://docs.adobisdc.fr/fr/datachain-maestro/current/` (image)	URL de la documentation, utilisée par les liens d’aide de l’interface
SUPPORT_BASE_URL	`https://adobisgroup.atlassian.net/servicedesk/customer/portal/10` (image)	URL du support, utilisée par les liens d’aide de l’interface
IS_EXPOSV2_ACTIVE	(aucun)	`true` : active l’exposition v2 des pipelines
IS_DCCODE_ACTIVE	(aucun)	`true` : active l’intégration DCCode (prérequis : DCCode déployé)
AIRFLOW_TIME_ZONE	(aucun)	Fuseau horaire d’Airflow, utilisé pour l’affichage des planifications

MAESTRO_API_URL

(aucun)

URL publique de l’API de Maestro, vue du navigateur. Exemple : https://<nom de domaine de maestro>/api

MAESTRO_WS_URL

(aucun)

URL publique des WebSocket de Maestro. Exemple : wss://<nom de domaine de maestro>/api

MAESTRO_KEYCLOAK_AUTH_URL

(aucun)

URL d’authentification Keycloak, vue du navigateur (se termine par /auth)

MAESTRO_KEYCLOAK_REALM

(aucun)

Realm Keycloak (dc-realm)

MAESTRO_KEYCLOAK_CLIENT_ID

(aucun)

Client Keycloak de l’interface (maestro)

DOCUMENTATION_BASE_URL

https://docs.adobisdc.fr/fr/datachain-maestro/current/ (image)

URL de la documentation, utilisée par les liens d’aide de l’interface

SUPPORT_BASE_URL

https://adobisgroup.atlassian.net/servicedesk/customer/portal/10 (image)

URL du support, utilisée par les liens d’aide de l’interface

IS_EXPOSV2_ACTIVE

(aucun)

true : active l’exposition v2 des pipelines

IS_DCCODE_ACTIVE

(aucun)

true : active l’intégration DCCode (prérequis : DCCode déployé)

AIRFLOW_TIME_ZONE

(aucun)

Fuseau horaire d’Airflow, utilisé pour l’affichage des planifications

Fichier de configuration

MAESTRO_API_URL=https://<nom de domaine de maestro>/api
MAESTRO_WS_URL=wss://<nom de domaine de maestro>/api
MAESTRO_KEYCLOAK_AUTH_URL=https://<url publique de keycloak>/auth
MAESTRO_KEYCLOAK_REALM=dc-realm
MAESTRO_KEYCLOAK_CLIENT_ID=maestro
DOCUMENTATION_BASE_URL=https://docs.adobisdc.fr/fr/datachain-maestro/current/
SUPPORT_BASE_URL=<url du support>
IS_EXPOSV2_ACTIVE=true
IS_DCCODE_ACTIVE=false
AIRFLOW_TIME_ZONE=Europe/Paris

Module Airflow - Image maestro/maestro-airflow

Image Apache Airflow 2.11 (Python 3.12) enrichie des extensions de Maestro (greffons, gabarits d’e-mails, client Datachain). La même image porte quatre services, qui se distinguent par leur commande.

Description de l’image

Description

Exécute les pipelines générés par Maestro sous forme de DAG Airflow, avec l’exécuteur Celery.

Taille

~2,8Go

Briques techniques

Apache Airflow 2.11 / Python 3.12 / Celery

Utilisateur

airflow (uid 50000, gid 0) par défaut dans l’image. Les déploiements fournis imposent 38330:0 (uid 38330, groupe root) : les répertoires montés sur /opt/airflow/dags et /opt/airflow/logs doivent être accessibles en écriture à cet uid, ou au groupe 0.

Commandes

Commande Utilité

webserver

Interface web et API REST d’Airflow (service airflow-webserver). L’API est utilisée par Maestro ; l’interface n’est exposée à l’extérieur que si nécessaire.

scheduler

Planificateur des DAG (service airflow-scheduler)

celery worker

Exécute les tâches (service airflow-worker). Il lance les conteneurs des tâches via le service socket-proxy.

airflow db upgrade puis réinitialisation du mot de passe de l’utilisateur maestro

Migration de la base Airflow et création de l’utilisateur de Maestro (service airflow-migration, exécution unique)

Volumes

Chemin Utilité Obligatoire

/opt/airflow/dags

DAG Airflow. Ce répertoire est partagé avec l’Upflower, qui y dépose les DAG générés par Maestro (sous-répertoire maestro).

Oui

/opt/airflow/logs

Logs d’exécution des tâches

Oui, pour conserver les logs

Urls

Port Url Utilité

8080

Interface web et API d’Airflow (service airflow-webserver uniquement). L’API est utilisée par Maestro sur /api/v1/.

Variables d’environnement

La configuration d’Airflow s’effectue par les variables standard AIRFLOW__<SECTION>__<CLÉ>, décrites dans la documentation d’Apache Airflow. Les variables ci-dessous sont celles fixées dans les déploiements fournis, et partagées par les quatre services via un fichier airflow_common.env.

Variable Valeur du déploiement Description

Variable	Valeur du déploiement	Description
AIRFLOW__CORE__EXECUTOR	CeleryExecutor	Exécuteur des tâches
AIRFLOW__DATABASE__SQL_ALCHEMY_CONN	`postgresql+psycopg2://<utilisateur>:<mot de passe>@<hôte>/airflow`	Base de métadonnées d’Airflow
AIRFLOW__CELERY__RESULT_BACKEND	`db+postgresql://<utilisateur>:<mot de passe>@<hôte>/airflow`	Résultats des tâches Celery (même base)
AIRFLOW__CELERY__BROKER_URL	`redis://<hôte valkey>:6379/1`	Broker Celery (Valkey). Utiliser une base différente de celles déjà utilisées par ailleurs.
AIRFLOW__CORE__FERNET_KEY	(à définir)	Clé de chiffrement des connexions et variables Airflow
AIRFLOW__CORE__DAGS_ARE_PAUSED_AT_CREATION	true	Les DAG sont créés en pause
AIRFLOW__CORE__LOAD_EXAMPLES	false	Ne pas charger les DAG d’exemple
AIRFLOW__CORE__MIN_SERIALIZED_DAG_UPDATE_INTERVAL	5	Intervalle minimal de mise à jour des DAG sérialisés, en secondes
AIRFLOW__CORE__MAX_ACTIVE_RUNS_PER_DAG	1	Nombre maximal d’exécutions simultanées d’un même DAG
AIRFLOW__CORE__MAX_ACTIVE_TASKS_PER_DAG	5	Nombre maximal de tâches simultanées d’un même DAG
AIRFLOW__CORE__PARALLELISM	15	Nombre maximal de tâches simultanées sur l’ensemble d’Airflow
AIRFLOW__API__AUTH_BACKENDS	`airflow.api.auth.backend.basic_auth,airflow.api.auth.backend.session`	Méthodes d’authentification de l’API. L’authentification de base est nécessaire à Maestro.
AIRFLOW__WEBSERVER__BASE_URL	`http://airflow-api`	Adresse de base du serveur web
AIRFLOW__WEBSERVER__PAGE_SIZE	20	Nombre d’éléments par page
AIRFLOW__WEBSERVER__WEB_SERVER_WORKER_TIMEOUT	300	Délai d’expiration des processus du serveur web, en secondes
AIRFLOW__LOGGING__LOGGING_LEVEL	INFO	Niveau de logs
AIRFLOW__LOGGING__EXTRA_LOGGER_NAMES	maestro	Loggers supplémentaires pris en compte
AIRFLOW__SMTP__SMTP_HOST	(serveur smtp)	Serveur SMTP pour les e-mails d’Airflow
AIRFLOW__SMTP__SMTP_PORT	587	Port SMTP
AIRFLOW__SMTP__SMTP_STARTTLS	True	STARTTLS
AIRFLOW__SMTP__SMTP_USER	(compte smtp)	Compte SMTP
AIRFLOW__SMTP__SMTP_PASSWORD	(mot de passe)	Mot de passe SMTP
AIRFLOW__SMTP__SMTP_MAIL_FROM	(expéditeur)	Adresse de l’expéditeur
ADOBIS_REGISTRY_CONN_ID, AIRFLOW_CONN_ADOBIS_REGISTRY	(vides si DCCode inactif)	Connexion Airflow au registre d’images, utilisée pour tirer l’image des tâches Docker et, avec DCCode, celle des notebooks (`ADOBIS_REGISTRY_CONN_ID` : identifiant de la connexion, à renseigner aussi dans le backend ; `AIRFLOW_CONN_ADOBIS_REGISTRY` : sa définition). À renseigner quand le registre exige une authentification, ou quand `IS_DCCODE_ACTIVE` vaut `true` côté interface.

AIRFLOW__CORE__EXECUTOR

CeleryExecutor

Exécuteur des tâches

AIRFLOW__DATABASE__SQL_ALCHEMY_CONN

postgresql+psycopg2://<utilisateur>:<mot de passe>@<hôte>/airflow

Base de métadonnées d’Airflow

AIRFLOW__CELERY__RESULT_BACKEND

db+postgresql://<utilisateur>:<mot de passe>@<hôte>/airflow

Résultats des tâches Celery (même base)

AIRFLOW__CELERY__BROKER_URL

redis://<hôte valkey>:6379/1

Broker Celery (Valkey). Utiliser une base différente de celles déjà utilisées par ailleurs.

AIRFLOW__CORE__FERNET_KEY

(à définir)

Clé de chiffrement des connexions et variables Airflow

AIRFLOW__CORE__DAGS_ARE_PAUSED_AT_CREATION

true

Les DAG sont créés en pause

AIRFLOW__CORE__LOAD_EXAMPLES

false

Ne pas charger les DAG d’exemple

AIRFLOW__CORE__MIN_SERIALIZED_DAG_UPDATE_INTERVAL

Intervalle minimal de mise à jour des DAG sérialisés, en secondes

AIRFLOW__CORE__MAX_ACTIVE_RUNS_PER_DAG

Nombre maximal d’exécutions simultanées d’un même DAG

AIRFLOW__CORE__MAX_ACTIVE_TASKS_PER_DAG

Nombre maximal de tâches simultanées d’un même DAG

AIRFLOW__CORE__PARALLELISM

Nombre maximal de tâches simultanées sur l’ensemble d’Airflow

AIRFLOW__API__AUTH_BACKENDS

airflow.api.auth.backend.basic_auth,airflow.api.auth.backend.session

Méthodes d’authentification de l’API. L’authentification de base est nécessaire à Maestro.

AIRFLOW__WEBSERVER__BASE_URL

http://airflow-api

Adresse de base du serveur web

AIRFLOW__WEBSERVER__PAGE_SIZE

Nombre d’éléments par page

AIRFLOW__WEBSERVER__WEB_SERVER_WORKER_TIMEOUT

300

Délai d’expiration des processus du serveur web, en secondes

AIRFLOW__LOGGING__LOGGING_LEVEL

INFO

Niveau de logs

AIRFLOW__LOGGING__EXTRA_LOGGER_NAMES

maestro

Loggers supplémentaires pris en compte

AIRFLOW__SMTP__SMTP_HOST

(serveur smtp)

Serveur SMTP pour les e-mails d’Airflow

AIRFLOW__SMTP__SMTP_PORT

587

Port SMTP

AIRFLOW__SMTP__SMTP_STARTTLS

True

STARTTLS

AIRFLOW__SMTP__SMTP_USER

(compte smtp)

Compte SMTP

AIRFLOW__SMTP__SMTP_PASSWORD

(mot de passe)

Mot de passe SMTP

AIRFLOW__SMTP__SMTP_MAIL_FROM

(expéditeur)

Adresse de l’expéditeur

ADOBIS_REGISTRY_CONN_ID, AIRFLOW_CONN_ADOBIS_REGISTRY

(vides si DCCode inactif)

Connexion Airflow au registre d’images, utilisée pour tirer l’image des tâches Docker et, avec DCCode, celle des notebooks (ADOBIS_REGISTRY_CONN_ID : identifiant de la connexion, à renseigner aussi dans le backend ; AIRFLOW_CONN_ADOBIS_REGISTRY : sa définition). À renseigner quand le registre exige une authentification, ou quand IS_DCCODE_ACTIVE vaut true côté interface.

Les variables suivantes sont fixées dans l’image et peuvent être surchargées : AIRFLOW__EMAIL__EMAIL_BACKEND (custom_utils.email_handler.send_email_with_id), AIRFLOW__EMAIL__HTML_CONTENT_TEMPLATE (/opt/airflow/mail_template.j2.html) et AIRFLOW__EMAIL__SUBJECT_TEMPLATE (/opt/airflow/mail_subject.j2.html).

Variables spécifiques au service de migration (airflow-migration) :

Variable Valeur Description

Variable	Valeur	Description
_AIRFLOW_DB_MIGRATE	true	Migre la base Airflow au démarrage
_AIRFLOW_WWW_USER_CREATE	true	Crée l’utilisateur Airflow de Maestro
_AIRFLOW_WWW_USER_USERNAME	maestro	Nom de l’utilisateur. Doit correspondre à `AIRFLOW_USER` du backend.
_AIRFLOW_WWW_USER_PASSWORD	(mot de passe)	Mot de passe de l’utilisateur. Doit correspondre à `AIRFLOW_PASSWORD` du backend. Le mot de passe est réinitialisé à chaque exécution de la migration.

_AIRFLOW_DB_MIGRATE

true

Migre la base Airflow au démarrage

_AIRFLOW_WWW_USER_CREATE

true

Crée l’utilisateur Airflow de Maestro

_AIRFLOW_WWW_USER_USERNAME

maestro

Nom de l’utilisateur. Doit correspondre à AIRFLOW_USER du backend.

_AIRFLOW_WWW_USER_PASSWORD

(mot de passe)

Mot de passe de l’utilisateur. Doit correspondre à AIRFLOW_PASSWORD du backend. Le mot de passe est réinitialisé à chaque exécution de la migration.

Fichier de configuration

AIRFLOW__CORE__EXECUTOR=CeleryExecutor
AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=postgresql+psycopg2://<utilisateur>:<mot de passe>@<hôte postgresql>/airflow
AIRFLOW__CELERY__RESULT_BACKEND=db+postgresql://<utilisateur>:<mot de passe>@<hôte postgresql>/airflow
AIRFLOW__CELERY__BROKER_URL=redis://<hôte valkey>:6379/1
AIRFLOW__CORE__FERNET_KEY=<clé fernet>
AIRFLOW__CORE__DAGS_ARE_PAUSED_AT_CREATION=true
AIRFLOW__CORE__LOAD_EXAMPLES=false
AIRFLOW__CORE__MAX_ACTIVE_RUNS_PER_DAG=1
AIRFLOW__CORE__MAX_ACTIVE_TASKS_PER_DAG=5
AIRFLOW__CORE__PARALLELISM=15
AIRFLOW__API__AUTH_BACKENDS=airflow.api.auth.backend.basic_auth,airflow.api.auth.backend.session
AIRFLOW__WEBSERVER__BASE_URL=http://airflow-api
AIRFLOW__LOGGING__EXTRA_LOGGER_NAMES=maestro
AIRFLOW__LOGGING__LOGGING_LEVEL=INFO
AIRFLOW__SMTP__SMTP_HOST=<serveur smtp>
AIRFLOW__SMTP__SMTP_PORT=587
AIRFLOW__SMTP__SMTP_STARTTLS=True
AIRFLOW__SMTP__SMTP_USER=<compte smtp>
AIRFLOW__SMTP__SMTP_PASSWORD=<mot de passe>
AIRFLOW__SMTP__SMTP_MAIL_FROM=<expéditeur>

Module Upflower - Image maestro/maestro-upflower

L’Upflower est le service de liaison entre Maestro et Airflow : il reçoit de Maestro les DAG générés et les dépose dans le répertoire des DAG d’Airflow. Il vérifie le jeton Keycloak des appels qu’il reçoit.

Description de l’image

Description

API de dépôt des DAG Airflow générés par Maestro. Livre aussi, au démarrage, les DAG de maintenance fournis avec l’image (sous-répertoire ops du répertoire des DAG).

Taille

~200Mo

Briques techniques

Python 3.12 / FastAPI / Uvicorn (3 processus)

Utilisateur

dc (uid 38330, groupe principal root (gid 0), répertoire personnel /home/maestro). L’image accepte aussi un uid quelconque imposé au démarrage (OpenShift) : cet uid appartient au groupe root (gid 0). Le répertoire monté sur /opt/airflow/dags doit être accessible en écriture à l’uid 38330 ou au groupe 0. Les fichiers de DAG déposés sont attribués à l’utilisateur de l’Upflower : voir AIRFLOW_UID et AIRFLOW_GID.

Volumes

Chemin

Utilité

Obligatoire

/opt/airflow/dags

Répertoire des DAG d’Airflow : doit être le même que celui monté dans les services Airflow

Oui

Urls

Port Url Utilité

8000

API de l’Upflower, appelée par le backend (AIRFLOW_UPFLOWER_URL). Sert aussi de contrôle de santé de l’image.

Variables d’environnement

Variable Défaut Description

Variable	Défaut	Description
DC_KEYCLOAK_HOST	localhost	URL du serveur Keycloak
DC_KEYCLOAK_REALM	dc-realm	Realm Keycloak
DC_KEYCLOAK_CLIENT_ID	maestro	Client Keycloak
DC_KEYCLOAK_CLIENT_SECRET	(aucun)	Secret du client Keycloak
DC_KEYCLOAK_AUDIENCE	maestro_backend	Audience attendue dans les jetons reçus
AIRFLOW_DAG_PATH	/opt/airflow/dags	Répertoire des DAG dans le conteneur
AIRFLOW_MAESTRO_FOLDER	maestro	Sous-répertoire des DAG générés par Maestro
AIRFLOW_OPS_FOLDER	ops	Sous-répertoire des DAG de maintenance livrés avec l’image
UPFLOWER_SEED_OPS_DAGS	1	`0` : ne livre pas les DAG de maintenance au démarrage
UPFLOWER_OPS_DAGS_DIR	/app/ops_dags	Répertoire, dans l’image, des DAG de maintenance livrés
AIRFLOW_UID	1000	Propriétaire des fichiers de DAG déposés. L’Upflower ne s’exécutant pas en `root`, il ne peut attribuer les fichiers qu’à son propre uid : positionner 38330 (uid de l’Upflower et des services Airflow fournis). Une autre valeur n’empêche pas le dépôt des DAG, mais les fichiers restent la propriété de l’uid 38330.
AIRFLOW_GID	0	Groupe des fichiers de DAG déposés : doit être un groupe de l’Upflower (`root`, gid 0, par défaut) et permettre la lecture par les services Airflow.
LOGLEVEL	INFO	Niveau de logs

DC_KEYCLOAK_HOST

localhost

URL du serveur Keycloak

DC_KEYCLOAK_REALM

dc-realm

Realm Keycloak

DC_KEYCLOAK_CLIENT_ID

maestro

Client Keycloak

DC_KEYCLOAK_CLIENT_SECRET

(aucun)

Secret du client Keycloak

DC_KEYCLOAK_AUDIENCE

maestro_backend

Audience attendue dans les jetons reçus

AIRFLOW_DAG_PATH

/opt/airflow/dags

Répertoire des DAG dans le conteneur

AIRFLOW_MAESTRO_FOLDER

maestro

Sous-répertoire des DAG générés par Maestro

AIRFLOW_OPS_FOLDER

ops

Sous-répertoire des DAG de maintenance livrés avec l’image

UPFLOWER_SEED_OPS_DAGS

0 : ne livre pas les DAG de maintenance au démarrage

UPFLOWER_OPS_DAGS_DIR

/app/ops_dags

Répertoire, dans l’image, des DAG de maintenance livrés

AIRFLOW_UID

1000

Propriétaire des fichiers de DAG déposés. L’Upflower ne s’exécutant pas en root, il ne peut attribuer les fichiers qu’à son propre uid : positionner 38330 (uid de l’Upflower et des services Airflow fournis). Une autre valeur n’empêche pas le dépôt des DAG, mais les fichiers restent la propriété de l’uid 38330.

AIRFLOW_GID

Groupe des fichiers de DAG déposés : doit être un groupe de l’Upflower (root, gid 0, par défaut) et permettre la lecture par les services Airflow.

LOGLEVEL

INFO

Niveau de logs

Les paramètres des DAG de maintenance (rétention de l’historique, par exemple) se règlent aussi par des variables d’environnement de l’Upflower : l’Upflower les écrit dans le fichier du DAG livré, ce qui évite de configurer les services Airflow. Voir DAG de maintenance Airflow (ops).

Fichier de configuration

DC_KEYCLOAK_HOST=<url publique de keycloak>
DC_KEYCLOAK_REALM=dc-realm
DC_KEYCLOAK_CLIENT_ID=maestro
DC_KEYCLOAK_CLIENT_SECRET=<secret du client maestro>
DC_KEYCLOAK_AUDIENCE=maestro_backend
AIRFLOW_DAG_PATH=/opt/airflow/dags
AIRFLOW_MAESTRO_FOLDER=maestro

DAG de maintenance Airflow (ops)

L’image maestro/maestro-upflower livre deux DAG de maintenance, qui nettoient les données techniques d’Airflow (Airflow 2.x). Ce ne sont pas des DAG Maestro : ils sont déposés dans le sous-répertoire ops du répertoire des DAG (variable AIRFLOW_OPS_FOLDER), et non dans maestro.

DAG Rôle

DAG	Rôle
`airflow_db_cleanup`	Nettoie la base de données d’Airflow : historique des exécutions (runs), tables techniques (jobs, sessions, résultats Celery, erreurs d’import) et journal d’audit. Peut aussi purger les métadonnées des DAG supprimés sans avoir été nettoyés.
`airflow_logs_cleanup`	Supprime les anciens fichiers de logs d’Airflow : logs des exécutions de chaque DAG, logs du scheduler, dossiers vides, et dossiers de logs des DAG supprimés.

airflow_db_cleanup

Nettoie la base de données d’Airflow : historique des exécutions (runs), tables techniques (jobs, sessions, résultats Celery, erreurs d’import) et journal d’audit. Peut aussi purger les métadonnées des DAG supprimés sans avoir été nettoyés.

airflow_logs_cleanup

Supprime les anciens fichiers de logs d’Airflow : logs des exécutions de chaque DAG, logs du scheduler, dossiers vides, et dossiers de logs des DAG supprimés.

Fonctionnement

Livraison : au démarrage, l’Upflower copie les fichiers livrés avec l’image (répertoire /app/ops_dags, variable UPFLOWER_OPS_DAGS_DIR) dans le répertoire ops. Un fichier n’est réécrit que si son contenu change : une mise à jour de l’image ou de la configuration est donc prise en compte au redémarrage de l’Upflower. Les modifications faites à la main dans le fichier livré sont écrasées.
Configuration : tous les paramètres de chaque DAG se règlent par des variables d’environnement de l'Upflower (OPS_DB_CLEANUP_<PARAMÈTRE> et OPS_LOGS_CLEANUP_<PARAMÈTRE>, en majuscules). L’Upflower écrit les valeurs dans le fichier du DAG au moment de la livraison : les services Airflow n’ont rien à configurer. Le type de la valeur est celui du paramètre (booléen : true/false, 1/0, yes/no, on/off ; entier ; texte). Une valeur invalide est ignorée (avertissement dans les logs de l’Upflower) et la valeur par défaut est conservée.
Désactivation : UPFLOWER_SEED_OPS_DAGS=0 empêche la livraison des DAG. Les fichiers doivent alors être fournis par un autre moyen, et leurs paramètres modifiés directement dans le bloc SETTINGS du fichier.
Prudence par défaut : chaque DAG est créé en pause et ne fait qu’une simulation (dry-run) : il indique dans ses logs ce qu’il supprimerait, sans rien supprimer.

Un DAG n’est mis en route (hors pause) qu’à sa création. Si le DAG existe déjà en pause, le réactiver une fois dans l’interface d’Airflow (ou avec airflow dags unpause), même après avoir positionné ENABLED à true.

Mettre en œuvre un DAG de maintenance

Positionner OPS_DB_CLEANUP_ENABLED=true (ou OPS_LOGS_CLEANUP_ENABLED=true) dans l’environnement de l’Upflower, ajuster les autres paramètres si besoin, puis redémarrer l’Upflower.
Laisser le DAG tourner en simulation et contrôler dans ses logs ce qui serait supprimé.
Faire une sauvegarde de la base de données Airflow (pg_dump) avant la première suppression réelle.
Activer les suppressions : OPS_DB_CLEANUP_APPLY=true (ou OPS_LOGS_CLEANUP_APPLY=true) dans l’environnement de l’Upflower, ou, sans redémarrage, lancer le DAG manuellement avec le paramètre apply à true, ou créer la variable Airflow db_cleanup_apply (respectivement logs_cleanup_apply) à true.

Sur une base volumineuse, réduire la rétention progressivement (par exemple OPS_DB_CLEANUP_KEEP_RUNS à 5000, puis 1000, puis 500).

Étendue (scope)

Le paramètre SCOPE des deux DAG définit les DAG concernés :

maestro (défaut) : uniquement les DAG dont le chemin de fichier contient SCOPE_MARKER (par défaut /maestro/maestro_, soit les DAG générés par Maestro). Les autres DAG (écrits à la main, DAG de maintenance eux-mêmes) ne sont jamais touchés ;
all : tous les DAG de l’instance Airflow, qu’ils viennent de Maestro ou non.

DAG airflow_db_cleanup

Le DAG ne supprime jamais de DAG : les tables dag et serialized_dag ne sont pas modifiées (sauf avec PURGE_ORPHANS, voir plus bas). Seul l’historique est nettoyé :

tables techniques (job, celery_taskmeta, celery_tasksetmeta, session, import_error) : lignes de plus de TECH_DAYS jours, quelle que soit l’étendue (ces tables sont globales) ;
exécutions (dag_run, avec leurs instances de tâches et leurs xcom) : selon RUNS_MODE ;
journal d’audit (log) : lignes de plus de LOG_DAYS jours. Une exécution en cours ou en attente n’est jamais supprimée.

Variable (préfixe OPS_DB_CLEANUP_) Défaut Description

Variable (préfixe `OPS_DB_CLEANUP_`)	Défaut	Description
ENABLED	false	`true` : le DAG est créé hors pause. Sans effet si le DAG existe déjà
APPLY	false	`true` : supprime réellement. `false` : simulation uniquement
SCHEDULE	`0 3 * * 0`	Planification (expression cron : sans guillemets dans un fichier d’environnement Docker), par défaut chaque dimanche à 03:00. `none` : DAG à lancer manuellement
SCOPE	maestro	Étendue : `maestro` ou `all`
SCOPE_MARKER	/maestro/maestro_	Étendue `maestro` : texte que doit contenir le chemin du fichier du DAG
TECH_DAYS	14	Tables techniques : ancienneté maximale, en jours
RUNS_MODE	keep_runs	Nettoyage des exécutions : `keep_runs` (limites ci-dessous) ou `skip` (les exécutions ne sont pas touchées)
KEEP_RUNS	500	Mode `keep_runs` : nombre maximal d’exécutions conservées par DAG (les plus récentes)
RUNS_DAYS	548	Mode `keep_runs` : ancienneté maximale des exécutions, en jours (548 jours, soit 18 mois)
RUNS_RULE	cap	`cap` : une exécution est supprimée dès qu’elle dépasse l’une des deux limites. `protect` : seulement si elle dépasse les deux (un DAG rarement exécuté conserve alors tout son historique)
LOG_DAYS	90	Journal d’audit (table `log`) : ancienneté maximale, en jours
PURGE_ORPHANS	false	`true` : purge aussi les métadonnées des DAG supprimés de façon incomplète (fichier disparu, mais lignes restées en base)
ORPHAN_MIN_AGE_DAYS	7	`PURGE_ORPHANS` : le DAG doit être inactif depuis au moins N jours
ORPHAN_MAX	200	`PURGE_ORPHANS` : nombre maximal de DAG purgés par exécution (la purge se fait par étapes)

ENABLED

false

true : le DAG est créé hors pause. Sans effet si le DAG existe déjà

APPLY

false

true : supprime réellement. false : simulation uniquement

SCHEDULE

0 3 * * 0

Planification (expression cron : sans guillemets dans un fichier d’environnement Docker), par défaut chaque dimanche à 03:00. none : DAG à lancer manuellement

SCOPE

maestro

Étendue : maestro ou all

SCOPE_MARKER

/maestro/maestro_

Étendue maestro : texte que doit contenir le chemin du fichier du DAG

TECH_DAYS

Tables techniques : ancienneté maximale, en jours

RUNS_MODE

keep_runs

Nettoyage des exécutions : keep_runs (limites ci-dessous) ou skip (les exécutions ne sont pas touchées)

KEEP_RUNS

500

Mode keep_runs : nombre maximal d’exécutions conservées par DAG (les plus récentes)

RUNS_DAYS

548

Mode keep_runs : ancienneté maximale des exécutions, en jours (548 jours, soit 18 mois)

RUNS_RULE

cap

cap : une exécution est supprimée dès qu’elle dépasse l’une des deux limites. protect : seulement si elle dépasse les deux (un DAG rarement exécuté conserve alors tout son historique)

LOG_DAYS

Journal d’audit (table log) : ancienneté maximale, en jours

PURGE_ORPHANS

false

true : purge aussi les métadonnées des DAG supprimés de façon incomplète (fichier disparu, mais lignes restées en base)

ORPHAN_MIN_AGE_DAYS

PURGE_ORPHANS : le DAG doit être inactif depuis au moins N jours

ORPHAN_MAX

200

PURGE_ORPHANS : nombre maximal de DAG purgés par exécution (la purge se fait par étapes)

Les valeurs KEEP_RUNS, RUNS_DAYS et RUNS_RULE sont les mêmes que celles de la purge de l’historique de Maestro (HISTORY_KEEP_RUNS, HISTORY_RETENTION_DAYS et HISTORY_RULE du backend) : garder les mêmes valeurs des deux côtés.

Un DAG n’est purgé (PURGE_ORPHANS) que s’il est inactif depuis plus de ORPHAN_MIN_AGE_DAYS jours, dans l’étendue choisie, et sans exécution en cours démarrée depuis moins de 3 jours. Les exécutions sont d’abord supprimées par lots, puis le DAG lui-même, comme le fait l’API REST d’Airflow (DELETE /dags/{dag_id}). Les lignes du journal d’audit sont conservées.

Les tâches utilisent la connexion à la base de données du worker Airflow : ce DAG fonctionne avec Airflow 2.x uniquement. Aucune table d’archive n’est conservée.

DAG airflow_logs_cleanup

Le DAG supprime, dans le répertoire de logs d’Airflow (base_log_folder) :

les dossiers de logs d’exécution (dag_id=<id>/run_id=<exécution>) de chaque DAG de l’étendue, selon RUNS_LOGS_KEEP, RUNS_LOGS_DAYS et RUNS_LOGS_RULE. L’ancienneté et le rang sont ceux des fichiers (dernière écriture) ; la base de données n’est pas utilisée. Un dossier modifié durant les RUNS_LOGS_GRACE_DAYS derniers jours n’est jamais supprimé ;
optionnellement, les dossiers de logs des DAG qui n’existent plus (DELETED_DAGS_LOGS) ;
les fichiers du dossier scheduler/ de plus de SCHEDULER_LOGS_DAYS jours ;
les dossiers vides, de plus d’un jour ;
en filet de sécurité, quelle que soit l’étendue, tout fichier de logs de plus de MAX_AGE_DAYS jours.

Variable (préfixe OPS_LOGS_CLEANUP_) Défaut Description

Variable (préfixe `OPS_LOGS_CLEANUP_`)	Défaut	Description
ENABLED	false	`true` : le DAG est créé hors pause. Sans effet si le DAG existe déjà
APPLY	false	`true` : supprime réellement. `false` : simulation uniquement
SCHEDULE	`0 2 * * *`	Planification (expression cron), par défaut chaque jour à 02:00. `none` : DAG à lancer manuellement
SCOPE	maestro	Étendue : `maestro` ou `all`
SCOPE_MARKER	/maestro/maestro_	Étendue `maestro` : texte que doit contenir le chemin du fichier du DAG
RUNS_LOGS_KEEP	100	Nombre maximal d’exécutions dont les logs sont conservés par DAG (les plus récentes)
RUNS_LOGS_DAYS	548	Ancienneté maximale des logs d’exécution, en jours (18 mois)
RUNS_LOGS_RULE	cap	`cap` : supprimé dès qu’une des deux limites est dépassée. `protect` : seulement si les deux le sont
RUNS_LOGS_GRACE_DAYS	1	Un dossier d’exécution modifié durant les N derniers jours n’est jamais supprimé
RUNS_LOGS_MAX	5000	Nombre maximal de dossiers d’exécution supprimés par exécution du DAG
DELETED_DAGS_LOGS	false	`true` : supprime aussi les dossiers de logs des DAG qui n’existent plus
DELETED_DAGS_MIN_AGE_DAYS	7	`DELETED_DAGS_LOGS` : le DAG doit être inactif, et rien n’avoir été écrit dans son dossier, depuis au moins N jours
DELETED_DAGS_MAX	500	`DELETED_DAGS_LOGS` : nombre maximal de dossiers de DAG supprimés par exécution
MAX_AGE_DAYS	730	Filet de sécurité : tout fichier de logs de plus de N jours est supprimé, pour tous les DAG, connus de la base ou non (730 jours, soit 2 ans ; `0` : désactivé)
SCHEDULER_LOGS_DAYS	7	Fichiers du dossier `scheduler/` : ancienneté maximale, en jours

ENABLED

false

true : le DAG est créé hors pause. Sans effet si le DAG existe déjà

APPLY

false

true : supprime réellement. false : simulation uniquement

SCHEDULE

0 2 * * *

Planification (expression cron), par défaut chaque jour à 02:00. none : DAG à lancer manuellement

SCOPE

maestro

Étendue : maestro ou all

SCOPE_MARKER

/maestro/maestro_

Étendue maestro : texte que doit contenir le chemin du fichier du DAG

RUNS_LOGS_KEEP

100

Nombre maximal d’exécutions dont les logs sont conservés par DAG (les plus récentes)

RUNS_LOGS_DAYS

548

Ancienneté maximale des logs d’exécution, en jours (18 mois)

RUNS_LOGS_RULE

cap

cap : supprimé dès qu’une des deux limites est dépassée. protect : seulement si les deux le sont

RUNS_LOGS_GRACE_DAYS

Un dossier d’exécution modifié durant les N derniers jours n’est jamais supprimé

RUNS_LOGS_MAX

5000

Nombre maximal de dossiers d’exécution supprimés par exécution du DAG

DELETED_DAGS_LOGS

false

true : supprime aussi les dossiers de logs des DAG qui n’existent plus

DELETED_DAGS_MIN_AGE_DAYS

DELETED_DAGS_LOGS : le DAG doit être inactif, et rien n’avoir été écrit dans son dossier, depuis au moins N jours

DELETED_DAGS_MAX

500

DELETED_DAGS_LOGS : nombre maximal de dossiers de DAG supprimés par exécution

MAX_AGE_DAYS

730

Filet de sécurité : tout fichier de logs de plus de N jours est supprimé, pour tous les DAG, connus de la base ou non (730 jours, soit 2 ans ; 0 : désactivé)

SCHEDULER_LOGS_DAYS

Fichiers du dossier scheduler/ : ancienneté maximale, en jours

La rétention des logs est indépendante de celle de l’historique des exécutions (base de données). Avec l’étendue maestro, la suppression des logs d’un DAG supprimé de la base ne peut plus être rattachée à Maestro : ces logs sont supprimés par MAX_AGE_DAYS, ou par DELETED_DAGS_LOGS avec l’étendue all. Pour éviter toute suppression par erreur, le DAG refuse de s’exécuter si la base ne connaît aucun des DAG présents dans le répertoire de logs (base erronée ou vide). Le répertoire de logs vu par le worker est celui de son hôte : il est partagé par les services Airflow d’un même hôte.

Si un DAG de nettoyage des logs écrit à la main existe déjà dans le répertoire des DAG, le retirer pour que les deux ne s’exécutent pas en même temps.

Exemple de configuration

Variables à ajouter au fichier d’environnement de l’Upflower, pour activer les deux DAG avec des suppressions réelles :

# Nettoyage de la base d'Airflow
OPS_DB_CLEANUP_ENABLED=true
OPS_DB_CLEANUP_APPLY=true
OPS_DB_CLEANUP_KEEP_RUNS=500
OPS_DB_CLEANUP_RUNS_DAYS=548

# Nettoyage des fichiers de logs
OPS_LOGS_CLEANUP_ENABLED=true
OPS_LOGS_CLEANUP_APPLY=true
OPS_LOGS_CLEANUP_SCHEDULE=0 2 * * *

Module Proxy Docker - Image maestro/docker-proxy

Cette image (HAProxy 2.6) expose l’API Docker du nœud avec des droits limités. Elle permet au worker Airflow de lancer les conteneurs des tâches sans accéder directement à la socket Docker.

Description de l’image

Description

Filtre les appels à l’API Docker : seules les familles d’appels autorisées par les variables ci-dessous sont transmises à la socket Docker.

Taille

~25Mo

Briques techniques

HAProxy 2.6 (alpine)

Utilisateur

haproxy (uid 99, gid 99) par défaut dans l’image. Les déploiements fournis exécutent le service en root (0:0) pour pouvoir lire la socket Docker.

Volumes

Chemin

Utilité

Obligatoire

/var/run/docker.sock

Socket Docker de l’hôte, montée en lecture seule

Oui

Urls

Port Url Utilité

2375

API Docker filtrée. Ne pas exposer en dehors du réseau interne : c’est l’adresse DOCKER_URI du backend (tcp://socket-proxy:2375).

Ce service donne la possibilité de créer des conteneurs sur le cluster. Il doit être attaché uniquement au réseau interne de Datachain, jamais publié, et placé sur un nœud manager.

Variables d’environnement

Chaque variable autorise (1) ou interdit (0) une famille d’appels de l’API Docker. Par défaut, l’image n’autorise que la lecture : EVENTS, PING et VERSION. Le déploiement fourni active les familles nécessaires au lancement de conteneurs.

Variable	Défaut de l’image	Déploiement fourni	Description
POST	0	1	Autorise les appels qui modifient l’état (sans lui, l’API est en lecture seule)
CONTAINERS	0	1	Gestion des conteneurs
IMAGES	0	1	Gestion des images
NETWORKS	0	1	Gestion des réseaux
SERVICES, TASKS, SWARM, NODES, CONFIGS	0	1	Gestion des services Swarm et de l’état du cluster
VOLUMES	0	1	Gestion des volumes
EXEC, BUILD, COMMIT, DISTRIBUTION, PLUGINS, SESSION, SYSTEM, INFO, AUTH	0	1	Autres familles d’appels de l’API Docker
SECRETS, GRPC	0	0	Inchangé : appels interdits
ALLOW_RESTARTS	0	0	Autorise l’arrêt, le redémarrage et la destruction des conteneurs, même quand `POST` vaut 0
PING, VERSION	1	1	Nécessaires à la négociation de version du client Docker
EVENTS	1	1	Flux d’événements Docker
SOCKET_PATH	/var/run/docker.sock	unix@/var/run/docker.sock	Chemin de la socket. Le préfixe `unix@` est nécessaire pour que HAProxy la traite comme une socket Unix.
LOG_LEVEL	info	info	Niveau de logs de HAProxy

Le groupe propriétaire de la socket Docker variant selon les machines, les déploiements fournis exécutent ce service en root (user: "0:0") plutôt que de supposer un groupe fixe.

Images d’exécution des pipelines

Image maestro/maestro-python3.12-airflow-dc

Image dans laquelle s’exécutent les tâches Datachain d’un pipeline (déclenchement d’une exposition, d’un export, etc.). Elle est désignée par la variable DC_AFJOB_IMAGE du backend.

Description	Exécute les scripts des tâches Maestro avec le client Python Datachain.
Taille	~215Mo
Briques techniques	Python 3.12 / client Python `datachain`
Utilisateur	`dc` (uid 38330, groupe principal `root` (gid 0), répertoire personnel `/home/maestro`). L’image accepte aussi un uid quelconque imposé au démarrage (OpenShift) : cet uid appartient au groupe `root` (gid 0).
Configuration	Aucune configuration à fournir : Maestro transmet à chaque conteneur de tâche les variables nécessaires (`DC_HOST`, `DC_PORT`, `DC_PROTOCOL`, `DC_TOKEN`, `DCM_HOST_URL`, etc.). Le conteneur doit pouvoir joindre l’instance Datachain et l’API de Maestro (`MAESTRO_PRIVATE_API_URL`).

Description

Exécute les scripts des tâches Maestro avec le client Python Datachain.

Taille

~215Mo

Briques techniques

Python 3.12 / client Python datachain

Utilisateur

Configuration

Aucune configuration à fournir : Maestro transmet à chaque conteneur de tâche les variables nécessaires (DC_HOST, DC_PORT, DC_PROTOCOL, DC_TOKEN, DCM_HOST_URL, etc.). Le conteneur doit pouvoir joindre l’instance Datachain et l’API de Maestro (MAESTRO_PRIVATE_API_URL).

Image maestro/maestro-notebook

Image dans laquelle s’exécutent les notebooks de l’intégration DCCode. Elle est désignée par la variable DCCODE_RUN_IMAGE du backend (et K8S_DCCODE_IMAGE pour Kubernetes).

Description	Prépare l’environnement Python du notebook (`uv sync`), puis l’exécute avec Papermill en lui passant ses paramètres.
Taille	~160Mo
Briques techniques	Python 3.12 / uv / Papermill
Utilisateur	`dc` (uid 38330, groupe principal `root` (gid 0), répertoire personnel `/home/maestro`). L’image accepte aussi un uid quelconque imposé au démarrage (OpenShift) : cet uid appartient au groupe `root` (gid 0).
Configuration	Aucune configuration à fournir : le répertoire de travail (`/home/maestro/dccodenb`), le notebook et ses paramètres sont préparés et montés par Maestro à chaque exécution.

Description

Prépare l’environnement Python du notebook (uv sync), puis l’exécute avec Papermill en lui passant ses paramètres.

Taille

~160Mo

Briques techniques

Python 3.12 / uv / Papermill

Utilisateur

Configuration

Aucune configuration à fournir : le répertoire de travail (/home/maestro/dccodenb), le notebook et ses paramètres sont préparés et montés par Maestro à chaque exécution.

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