ADR-0003: Infra portal — one URL, replaceable panes
Date: 2026-07-17
Status: accepted · amended 2026-07-19: public hostnames carry the brand —
hub at pulse.dev.openmined.org, panes under *.pulse.dev.openmined.org
(e.g. status.pulse.dev.openmined.org; docs under /docs). §2's
boring-names rule now applies to repo paths, dirs, and resource names only,
not hostnames — the URL is brand surface, the paths are not.
Context
Platform knowledge is siloed: what runs where lives in Azure Portal + Argo CD +
this repo's docs, each behind different access and know-how. The team wants one
place — infra.dev.openmined.org — where anyone can see the services that are
running and their health, what exists in the Azure subscription at any point in
time, and all documentation (landing-zone architecture, workload architecture,
runbooks, conventions, history), with links to the tools themselves (Argo CD,
future Grafana/Keycloak). It must be able to grow with the platform and become
RBAC-gated when identity lands (ADR-0002 §5), and it must run on the platform
it describes.
Decision
1. A composite portal, not an IDP (yet)
Backstage is the end-state candidate but a product to own (Postgres, plugins, catalog sprawl) — wrong cost at the current service count. Instead: four thin panes behind one hub, each independently replaceable when it's outgrown:
| Pane | Tool now | Grows into | Migration cost |
|---|---|---|---|
| Hub / service directory | Homepage (k8s Ingress auto-discovery) | Backstage catalog | tiles → catalog YAML |
| Docs | MkDocs Material over this repo's docs/ |
Backstage TechDocs | none — same markdown |
| Status / health | Gatus (config-as-code checks) | kube-prometheus + Grafana | check YAML → probes |
| Cloud inventory | scheduled Azure Resource Graph snapshot → git | live in-cluster API (workload identity, Reader) | same query, fresher |
The hub auto-discovers cluster Ingresses, so every service that ships appears
on the board with zero curation. The inventory snapshot is committed to
docs/inventory/ — making the subscription's contents a git timeline:
"what ran last Tuesday" is git log.
2. Boring names in paths, brand late-binding
Stacks/dirs/hosts use plain names (portal, docs, status,
infra.dev.openmined.org). The platform brand (naming in progress) is a page
title + logo — one config string, swappable any time. Cool names in resource
paths age badly; brands in HTML don't.
3. Placement (per ADR-0001 decision tree)
- Homepage, Gatus, docs-site runtime →
kubernetes/apps/<name>/(workloads, Argo-delivered, enabled per cluster). - Docs-site image build (mkdocs → nginx Dockerfile) →
platform/docs-site/(we build it), pushed toacropenminedby CI. This is deliberately the first CI→ACR image path — a dry run of the 3d serviced-repo contract. - Inventory job →
.github/workflows/inventory.yml(thin trigger) +scripts/ci/azure-inventory.sh(logic), reusing the existing read-only OIDC identity. Output committed todocs/inventory/.
4. Exposure and access
pulse.dev.openmined.org(hub, docs under/docs; amended 2026-07-19, wasinfra.…) andstatus.pulse.dev.openmined.org(separate host + cert so status stays reachable when the portal itself is sick). DNS + TLS via the proven loop.- Open-internal for now. When Keycloak lands (3c): one oauth2-proxy in front, SSO + group RBAC for the whole portal at once. Public visibility of the status page becomes a deliberate choice then.
Consequences
- Zero new credential classes: image push needs one AcrPush federated credential for CI, and AcrPush joins the apply identity's ABAC whitelist — a trust-root change (break-glass) planned as part of Stage 2.
- The docs site rebuilds on merge; stale docs become CI-visible, not tribal.
- Betting on replaceable panes means accepting three small tools now instead of one big one; the exit criteria for each swap are written into the roadmap so "grows as needs grow" is a plan, not a hope.
- Everything runs on aks-dev ("dev data, prod service" — ADR-0002): the portal being down never blocks delivery, only visibility.