Guide du développeur data — la référence d'interface

Cette page est la référence des points d’accès de la plateforme pour le développeur data : la liste des services à joindre, leurs ports, et les conventions de secrets et de stockage. C’est un aide-mémoire à consulter, pas un parcours à suivre.

Pour faire, pas seulement vérifier : le mode d’emploi de chaque branchement (connexion PostgreSQL, émission de lineage, code-location Dagster, stockage…) est dans Se brancher sur la plateforme ; le parcours pas à pas en local est le tutoriel Monter le banc local. Pour ce que fait et pourquoi chaque brique, composants.

Frontière (ADR 0022 / 0023). Ce dépôt décrit l’infrastructure (générique). Le code métier vit dans le dépôt applicatif, pas ici. Les valeurs réelles (mots de passe, hostnames) viennent d’une config locale non versionnée.

Version machine-lisible — la source de vérité. Cette table (et les StorageClasses, namespaces, conventions de secrets) est aussi publiée comme contrat versionné sous contract/ — diff-able et consommable par un script (ADR 0043). En cas d’écart, le contrat fait foi ; cette page en est la version lisible.

Points d’accès (services intra-cluster)

Toutes les adresses sont des services Kubernetes intra-cluster (DNS *.svc.cluster.local) : votre code tourne dans un pod du cluster, dans un namespace autorisé par les NetworkPolicies.

Brique	Service (intra-cluster)	Port	Auth (Secret)
PostgreSQL (CNPG)	`pg-rw.postgres.svc.cluster.local` (primary)	5432	Secret du rôle (`pg-role-<rôle>`)
PostgreSQL (replica)	`pg-ro.postgres.svc.cluster.local` (lecture)	5432	idem
Marquez (lineage)	`marquez.marquez.svc.cluster.local`	5000	aucune (intra-cluster)
MLflow (modèles)	`mlflow.mlflow.svc.cluster.local`	5000	aucune (intra-cluster)
Registry d’images	`registry:80` (sur les nœuds)	80	aucune (HTTP interne, ADR 0011)
S3 datalake (RGW)	`rook-ceph-rgw-datalake.rook-ceph`	80	creds d’un `ObjectBucketClaim`
Gitea (forge GitOps)	`gitea-http.gitea.svc.cluster.local`	80	Secret `gitea-admin` (mot de passe)
Argo CD (GitOps)	`argocd-server.argocd.svc.cluster.local`	80	Secret `argocd-initial-admin-secret`

Exposition hors cluster (UI) via le Gateway Cilium + TLS interne (ADR 0020/0021) : p. ex. https://dagster.cluster.lan, https://marquez.cluster.lan (hostnames *.cluster.lan = placeholders génériques ; l’admin réseau pose les vrais).

⚠️ Résolution DNS : préférez le nom COURT, pas le FQDN. Depuis un pod, visez un service par <svc> (même namespace) ou <svc>.<ns> (autre namespace) — pas le FQDN complet <svc>.<ns>.svc.cluster.local. En prod, le resolv.conf des pods peut porter un search domain externe (DNS de l’organisation) avec ndots:5 : un FQDN complet (moins de 5 points) est traité comme relatif → le résolveur tente le suffixe externe avant le bon et timeoute, surtout côté gRPC/c-ares (code-location Dagster) et curl/glibc. Vécu sur dirqual (2026-06-22) : Dagster « gRPC UNAVAILABLE » sur FQDN, OK sur nom court (drift L58). Le banc Lima n’a pas ce search domain → le piège ne s’y voit pas. Le FQDN reste la référence canonique du contrat ; pour s’y connecter, raccourcir.

Bases logiques PostgreSQL

Un cluster HA unique pg (namespace postgres) porte quatre bases logiques, chacune avec son rôle propriétaire (ADR 0024) :

Base	Rôle (login)	Usage
`dagster`	`dagster`	event log de l’orchestrateur
`pgvector`	`pgvector`	recherche sémantique (extension SQL `vector`)
`marquez`	`marquez`	store de lineage (migrations Flyway)
`mlflow`	`mlflow`	backend store du suivi de modèles (ADR 0082)

Le mot de passe d’un rôle est dans le Secret pg-role-<rôle> (clé password, namespace postgres). Connexion : écrire (pg-rw) ou lire (pg-ro). La procédure (lire le Secret, exemple psycopg) est dans Se brancher → PostgreSQL.

StorageClasses disponibles

Le « catalogue » de types de stockage (StorageClass) — défaut = rook-ceph-block-replicated (RBD ×3, ADR 0001) :

StorageClass	Profil
`rook-ceph-block-replicated`	RBD ×3 — défaut, stateful critique
`rook-ceph-block-ec`	erasure coded — gros volumes tolérants
`rook-cephfs`	RWX (partagé multi-pods)
`rook-ceph-datalake`	objet S3 (via `ObjectBucketClaim`)

La procédure (PVC type, ObjectBucketClaim) est dans Se brancher → Stockage.

Variables OpenLineage

Le client OpenLineage standard lit ces variables pour émettre vers Marquez :

Variable	Valeur (intra-cluster)
`OPENLINEAGE_URL`	`http://marquez.marquez.svc.cluster.local:5000`
`OPENLINEAGE_ENDPOINT`	`api/v1/lineage`
`OPENLINEAGE_NAMESPACE`	le namespace logique de vos jobs (ex. `dagster`)

Variable MLflow

Pendant de OPENLINEAGE_URL pour le suivi de modèles : le client MLflow lit cette variable pour logger ses runs vers MLflow (serveur livré vide, peuplé par atlas) :

Variable	Valeur (intra-cluster)
`MLFLOW_TRACKING_URI`	`http://mlflow.mlflow.svc.cluster.local:5000`

⚠️ Pour que vos RUNS Dagster voient cette variable (pas seulement la code-location) : déclarez-la via un tag dagster-k8s/config (container_config.env) sur vos jobs — les env du pod de la code-location gRPC ne se propagent pas aux pods de run du K8sRunLauncher. Sinon le logging MLflow est un no-op silencieux (run SUCCESS mais rien de loggé). Détail : note dagster-webserver du contrat.

La procédure (logger un run, exemple Python) est dans Se brancher → Suivi de modèles.

Pour aller plus loin

Mode d’emploi de chaque branchement : Se brancher sur la plateforme.
Parcours en local, de zéro : Monter le banc local.
Présentation des briques : composants. Décisions : index ADR. Chaque brique a son README dans platform/<brique>/ et storage/ceph/.
Mettre la plateforme en place : bootstrap/dataops.yaml (ADR 0033).