URLs fonctionnelles — bookmarks stables au-dessus du Lego¶

AKKO publie chaque couche de la plateforme sous un FQDN fonctionnel qui décrit ce que la couche fait, pas quelle technologie la fait tourner aujourd'hui. Remplacer Spark par Dremio, Trino par Starburst, MinIO par Ceph : le bookmark reste le même. Le dashboard que ton équipe a construit en année 1 ouvre toujours le bon outil en année 5.

Mapping¶

Couche	FQDN fonctionnel	Implémentation actuelle	Alias legacy (résolution maintenue)
Notebooks et code	`lab.<domaine>`	JupyterHub + code-server	`jupyter.<domaine>`
Tableaux de bord et SQL Lab	`bi.<domaine>`	Apache Superset	`superset.<domaine>`
Orchestration de pipelines	`orchestrator.<domaine>`	Apache Airflow 3	`airflow.<domaine>`
SQL fédéré	`federation.<domaine>`	Trino	`trino.<domaine>`
Calcul distribué	`compute.<domaine>`	Apache Spark	`spark.<domaine>`
Expériences et registre ML	`experiments.<domaine>`	MLflow	`mlflow.<domaine>`
Passerelle IA	`llm.<domaine>`	LiteLLM	`litellm.<domaine>`
Fournisseur d'identité	`identity.<domaine>`	Keycloak	`keycloak.<domaine>`
Annuaire	`directory.<domaine>`	LLDAP	`lldap.<domaine>`
Stockage objet	`storage.<domaine>`	SeaweedFS S3	`seaweedfs.<domaine>`
Catalogue de données	`catalog.<domaine>`	OpenMetadata	`openmetadata.<domaine>`
Tableaux d'observabilité	`metrics.<domaine>`	Perses	`perses.<domaine>`
Recherche de logs	`logs.<domaine>`	VictoriaLogs	`loki.<domaine>`
Routage d'alertes	`alerts.<domaine>`	Alertmanager	`alertmanager.<domaine>`
Serveurs MCP	`mcp.<domaine>` / `mcp-catalog.<domaine>`	MCP Trino + OpenMetadata	`mcp-trino.<domaine>` / `mcp-openmetadata.<domaine>`
Registre conteneurs	`registry.<domaine>`	Harbor	`harbor.<domaine>`
Cockpit (UI opérateur)	`demo.<domaine>`	AKKO Cockpit	(aucun)
Documentation	`docs.<domaine>`	mkdocs Material	(aucun)
Apex / vitrine	`<domaine>`	Landing statique	(aucun)

Pourquoi c'est important¶

Souveraineté plutôt que rotation : chaque brique Lego peut être échangée sans casser les bookmarks utilisateur, les redirectUris OIDC, les paramètres IDE distants ou la configuration des notebooks. L'alias legacy survit un sprint supplémentaire pour faciliter la transition, puis est retiré.
Stabilité OIDC : le realm Keycloak inscrit pour chaque client (jupyterhub, superset, airflow, trino, mlflow, oauth2-proxy) les deux noms. Ajouter un nouveau FQDN fonctionnel se fait en une ligne dans helm/scripts/generate-domain-values.sh.
Stabilité des tests : la suite Playwright référence les noms fonctionnels, donc un swap d'implémentation n'oblige pas à réécrire les tests.

Comment ajouter un nouvel alias fonctionnel¶

Ajouter à helm/akko/templates/functional-aliases-ingresses.yaml.
Ajouter à helm/scripts/generate-domain-values.sh EXTRA_REDIRECTS pour que les clients OIDC apprennent le nouveau callback.
Ajouter à helm/akko/templates/oauth2-callback-ingresses.yaml la liste d'hosts pour qu'oauth2-proxy serve /oauth2/* sur le nouveau FQDN.
Si la couche est publique, ajouter l'annotation middleware oauth2-forward-auth.
bash helm/scripts/generate-domain-values.sh akko-ai.com pour régénérer values-domain.yaml et realm-domain.json.
helm upgrade akko helm/akko/ -n akko ... — le nouvel alias est en place en quelques secondes.

Vérification production¶

for h in lab bi orchestrator federation compute experiments metrics \
         llm directory storage identity alerts mcp mcp-catalog logs \
         registry; do
  curl -sILk -m 5 -o /dev/null -w "$h: HTTP %{http_code}\n" \
       "https://$h.akko-ai.com/"
done

Les seize FQDN fonctionnels doivent répondre 200, 302 ou 401. Un 404 signifie que l'Ingress alias fonctionnel manque. Un 502 signifie que la NetworkPolicy du chart backend bloque Traefik (voir le gotcha documenté — chaque chart avec Ingress public doit autoriser le contrôleur Traefik).

Référence¶

ADR-035 — Certificat TLS wildcard via cert-manager DNS-01.
ADR-035 update — Reverse proxy Caddy host-side sur Netcup (l'histoire spécifique de la terminaison TLS sur ce cluster).
PR #39 — Sprint 47 V2 refactor URL fonctionnel + nettoyage cockpit.