Functional URLs — Lego-stable bookmarks

AKKO publishes each layer of the platform under a functional FQDN that names what the layer does, not which technology powers it today. Swap Spark for Dremio, Trino for Starburst, MinIO for Ceph — the bookmark stays the same. The dashboard your team built in Year 1 keeps opening the right tool in Year 5.

Mapping

Layer	Functional FQDN	Current implementation	Legacy alias (still resolves)
Notebooks & Code	lab.<domain>	JupyterHub + code-server	jupyter.<domain>
Dashboards & SQL Lab	bi.<domain>	Apache Superset	superset.<domain>
Pipeline orchestration	orchestrator.<domain>	Apache Airflow 3	airflow.<domain>
Federated SQL	federation.<domain>	Trino	trino.<domain>
Distributed compute	compute.<domain>	Apache Spark	spark.<domain>
ML experiments & registry	experiments.<domain>	MLflow	mlflow.<domain>
AI gateway	llm.<domain>	LiteLLM	litellm.<domain>
Identity provider	identity.<domain>	Keycloak	keycloak.<domain>
Directory service	directory.<domain>	LLDAP	lldap.<domain>
Object storage	storage.<domain>	SeaweedFS S3	seaweedfs.<domain>
Data catalog	catalog.<domain>	OpenMetadata	openmetadata.<domain>
Observability dashboards	metrics.<domain>	Perses	perses.<domain>
Log search	logs.<domain>	VictoriaLogs	loki.<domain>
Alert routing	alerts.<domain>	Alertmanager	alertmanager.<domain>
MCP servers	mcp.<domain> / mcp-catalog.<domain>	MCP Trino + OpenMetadata	mcp-trino.<domain> / mcp-openmetadata.<domain>
Container registry	registry.<domain>	Harbor	harbor.<domain>
Cockpit (operator UI)	demo.<domain>	AKKO Cockpit	(none)
Documentation	docs.<domain>	mkdocs Material	(none)
Apex / marketing	<domain>	Static landing	(none)

Why this matters

1. Sovereignty over churn: every Lego layer can be swapped without breaking user bookmarks, OIDC redirect URIs, IDE remote settings, or notebook config. The legacy alias lives one extra sprint to ease the transition, then is retired.
2. OIDC stability: the Keycloak realm redirectUris for each client (jupyterhub, superset, airflow, trino, mlflow, oauth2-proxy) all carry both names. Adding a new functional FQDN is a one-line append in helm/scripts/generate-domain-values.sh.
3. Test stability: Playwright persona tests reference functional names, so an implementation swap doesn't churn the suite.

How to add a new functional alias

1. Append to helm/akko/templates/functional-aliases-ingresses.yaml.
2. Append to helm/scripts/generate-domain-values.sh EXTRA_REDIRECTS so OIDC clients learn the new callback URL.
3. Append to helm/akko/templates/oauth2-callback-ingresses.yaml host list so oauth2-proxy serves /oauth2/* on the new FQDN.
4. If the layer is publicly visible, add the oauth2-forward-auth middleware annotation.
5. bash helm/scripts/generate-domain-values.sh akko-ai.com to regenerate values-domain.yaml + realm-domain.json.
6. helm upgrade akko helm/akko/ -n akko ... — the new alias is live in seconds.

Production verification

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

All sixteen functional FQDNs must answer 200, 302, or 401. A 404 means the functional alias Ingress is missing. A 502 means the NetworkPolicy on the backend chart blocks Traefik (see the documented gotcha — every chart with a public Ingress must whitelist the Traefik controller).

Reference

• ADR-035 — TLS wildcard cert via cert-manager DNS-01.
• ADR-035 update — Caddy host-side reverse proxy on Netcup (this cluster's specific TLS termination story).
• PR #39 — Sprint 47 V2 functional URL refactor + cockpit cleanup.