docs: bring the specification in line with the accepted implementation

The operator ruled the implementation repo's main (50c8719) the latest
and accepted state. Sync the spec to it.

Accepted changes are reflected: one bare-metal environment, TrueNAS bulk
storage, R2 off-cluster backup, CloudNativePG, single-node VPN gateway
with Cilium fail-closed, inbound WireGuard, per-app auth sidecars,
Renovate, the CI gate as approver, and the pm-agent. New ADR-0017..0025;
ADR-0016 corrected and accepted; R-* IDs unchanged, eight amended.

Where the implementation has simply not met a requirement, the
requirement stands and the shortfall is recorded in docs/16-known-gaps.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
jakman85andClaude Opus 5.5 committed 2026-11-08 22:46:00 -06:00
1 parent 1ddc14b918
commit 250fb54154
43 files changed
+1672 -575

No files matched your search

+22 -16
View File
@@ -18,15 +18,18 @@ app to build from scratch:
Homepage widgets: Plex, Sonarr, Radarr, qBittorrent, PiHole, Gitea, etc.). This is the primary
R-C2-01 surface.
- **Grafana** — embedded platform + per-service dashboards (R-OBS-03) for health at a glance.
- **Headlamp** (or a comparable Kubernetes web UI) — a controlled Kubernetes console for viewing
workloads/VMs and performing scoped operational actions (restart, scale, inspect) — the R-C2-02
"controlled operational actions where safe" surface.
- **Headlamp** — a controlled Kubernetes console for viewing workloads/VMs and performing scoped
operational actions (restart, scale, inspect) — the R-C2-02 "controlled operational actions where
safe" surface. Each user acts under their own IdP identity and group-bound RBAC, never a shared
console identity.
- **Flux status** — GitOps reconciliation state (via Headlamp's Flux view, the Flux UI, or a
Homepage widget) so the operator sees drift/errors.
- **Hubble UI** (optional) — network flow visualization for isolation troubleshooting.
- **Hubble UI** (optional) — network flow visualization for isolation troubleshooting; deployed
with no route, so it is not reachable from outside the cluster.
Each sub-UI is itself an onboarded, TLS-protected, access-controlled service; the root aggregates and
links them. ADR-worthy only if a custom portal is later preferred over Homepage.
Each sub-UI is itself a platform-managed or onboarded, TLS-protected, access-controlled service; the
root aggregates and links them. Status of this composition is tracked in
[known gaps](16-known-gaps.md).
## Data the C2 surfaces (R-C2-02)
@@ -47,12 +50,16 @@ kubeconfig in a browser:
## Access control
- The C2 root and its sub-UIs are `internal` exposure by default (LAN-only) unless the operator
explicitly makes a component `public`.
- C2 sub-UIs are `internal` exposure by default (LAN/VPN-only) unless the operator explicitly makes
a component `public`. The apex and Grafana are `public` as registered platform routes; Headlamp is
LAN/VPN-only because it holds a path to the Kubernetes API on the user's behalf.
- Prometheus, Alertmanager and Hubble UI have **no route** and are not exposed; operators reach
their data through Grafana. Any future exposure of them MUST be gated.
- Authentication is via **Keycloak SSO** ([15](15-identity-and-access.md), [ADR-0014](../decisions/adr-0014-idp-keycloak.md)):
Headlamp/Grafana use **native OIDC**; UIs without OIDC (Homepage, Prometheus, Alertmanager, Hubble)
sit behind the **oauth2-proxy forward-auth** at the Gateway. Access to the C2 and sensitive
surfaces requires an authenticated user **in an authorized group** with **MFA** (R-IDP-06).
Headlamp/Grafana use **native OIDC**; a UI without OIDC, such as Homepage, requires a per-app
**oauth2-proxy forward-auth gate** ([ADR-0022](../decisions/adr-0022-forward-auth-per-app-oauth2-proxy-sidecars.md)).
Access to the C2 and sensitive surfaces requires an authenticated user **in an authorized group**
with **MFA** (R-IDP-06).
- Trusted TLS on the root and all sub-UIs ([08](08-tls-and-certificates.md)).
## Acceptance gates
@@ -62,8 +69,7 @@ kubeconfig in a browser:
- Safe operational actions work and are access-controlled + audited; destructive actions confirm.
## Resolved
- Auth mechanism — **Keycloak SSO** (native OIDC + oauth2-proxy forward-auth), [15](15-identity-and-access.md) /
[ADR-0014](../decisions/adr-0014-idp-keycloak.md).
## Open questions
- Custom portal vs. Homepage-as-root long term (ADR if we diverge from Homepage).
- Auth mechanism — **Keycloak SSO** (native OIDC + per-app oauth2-proxy forward-auth gates),
[15](15-identity-and-access.md) / [ADR-0014](../decisions/adr-0014-idp-keycloak.md) /
[ADR-0022](../decisions/adr-0022-forward-auth-per-app-oauth2-proxy-sidecars.md).
- Root UI — **Homepage** at the apex. A custom portal would need an ADR.