Skip to content

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 to acropenmined by 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 to docs/inventory/.

4. Exposure and access

  • pulse.dev.openmined.org (hub, docs under /docs; amended 2026-07-19, was infra.…) and status.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.