For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/docs/decisions/0058-distributed-services-composition.md.

0058 — Complete distributed services composition

Status: Proposed; implementation and evidence are recorded in DD-0058. Date: 24 October 2026. Stacked on ADR-0051 and ADR-0056.

Decision

A complete distributed site is one closed Argo CD composition rooted at gitops/distributed-services-root-app.yaml. It installs exactly nine child Applications: argocd, pharos-platform-routes, pharos-infra, gitlab, waldur, llm, pharos, pharos-site-runtime and themelio-compat. An extra, missing or development-owned Application fails before delivery. The Site Runtime is installed but remains paused until its production owners are connected.

The retained themelio-compat service is mandatory and active until every route has been migrated to the new Themelio service under an explicit handover. The composition must not treat the new Themelio as complete while any retained route still depends on the compatibility service. Its public origin, OIDC binding, provider tokens and image digests are part of the same exact-commit delivery.

Development AAI, browser aliases, Mailpit and Waldur seed data do not belong to a complete site. External AAI is supplied privately on the administration machine. Its file must be mode 0600, bind all three registered clients and contain public issuer metadata and trust material. The plan records only its canonical fingerprint. Delivery rejects changed or missing identity input before a cluster write, then applies consumer Secrets from stdin so credentials do not enter Git, Argo values, command arguments, public state or evidence.

Every service origin is an explicit HTTPS authority on port 443 with no path, credentials, query or fragment. Route values carry the exact catalogue checksum, active profiles and Ceph certificate hash to the route chart. Images built in the cluster are pinned by digest. Delivery waits for the complete child set at the reviewed commit, including successful provider hooks, before recording success. The Pharos browser and Site API use distinct public hosts. The Site API exposes only its native command and SSH-access prefixes, authenticates requests with scoped bearer grants and requires no browser OIDC redirect registration. The gateway verifies the HTTPS backend against the internal Site API trust.

The disposable icaruscloudlab environment remains foundation-only until it has approved public origins and external identity. A site with an existing foundation must use the reviewed writer-fencing cutover; enabling the composition does not authorise replacing existing application writers.

Consequences

GitLab, Waldur, routes and retained Themelio share one activation boundary. A failed identity, provider-token or child-health gate leaves the previous ready delivery authoritative. Route migration can remove themelio-compat only through a later decision that names the final migrated route set and removes its provider exceptions. A new distributed environment must supply public bindings in committed policy and private AAI material on its selected administration machine.

Page source

Source snapshot · Revision f928834c8.