jakman85andClaude Opus 4.8
fb153f0bb5
New identity subsystem, and resolves the C2 auth open question: - docs/15-identity-and-access.md + ADR-0014: Keycloak as central IdP; native OIDC where supported (Gitea, Nextcloud, Grafana, Kasm, Semaphore, Headlamp) and oauth2-proxy forward-auth for bare UIs (PiHole, *arr, qBittorrent, Homepage, Prometheus, Alertmanager, Hubble). Group-based authz + MFA; declarative realm/clients (GitOps); PostgreSQL on Longhorn, DR-critical + break-glass; hardened public exposure. Plex/Seerr use Plex auth; Minecraft N/A. - Requirements R-IDP-01..06; ServiceDefinition gains an block. - Onboarded early (with Gitea) so services adopt SSO as they come up. - Threaded through: docs 00,01,07,10,12,13; roadmap phases+workstreams; task board (T-6.1c/T-6.1d); glossary; ADR index; README. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
3.7 KiB
3.7 KiB
12 — Command & Control (C2) Center UI
Serves: R-C2-01/02, surfaces R-OBS-, R-GITOPS-.
Purpose
The root home.keithjackson.dev is the operator's front door: a single UI that shows what's running
in the cluster, links to every service, and surfaces platform health and safe operational actions
(R-C2-01/02).
Composition (assemble, don't reinvent)
The C2 center is a curated composition of best-in-class UIs behind the root domain, not a bespoke app to build from scratch:
- Homepage (gethomepage.dev) — the landing dashboard at the root: a live catalog of services with links, status pings, and per-service widgets (many of the catalog services have native 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.
- 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.
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.
Data the C2 surfaces (R-C2-02)
- Service catalog: every running service, its URL, its health, its egress class, its exposure.
- Platform health: node status, Longhorn capacity/health, Flux reconciliation, cert expiry, backup status, VPN tunnel state — sourced from the observability stack (10).
- Alerts: current firing alerts (mirrors what email delivers).
Actions (safe, audited)
Operational actions exposed through the C2 must be scoped and audited, never a raw cluster-admin kubeconfig in a browser:
- Restart/scale a workload, start/stop a KubeVirt VM, trigger a Flux reconcile, acknowledge an alert.
- Destructive actions (delete, offboard) require explicit confirmation and are logged.
- Onboarding itself remains a git PR (GitOps), not a C2 button — the C2 may link to the catalog/PR flow but does not bypass GitOps (05).
Access control
- The C2 root and its sub-UIs are
internalexposure by default (LAN-only) unless the operator explicitly makes a componentpublic. - Authentication is via Keycloak SSO (15, ADR-0014): 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).
- Trusted TLS on the root and all sub-UIs (08).
Acceptance gates
https://home.keithjackson.devserves the C2 landing UI over trusted TLS.- Every running service appears with a working link and live status.
- Platform health (nodes, storage, Flux, certs, backups, VPN) is visible without leaving the C2.
- Safe operational actions work and are access-controlled + audited; destructive actions confirm.
Resolved
Open questions
- Custom portal vs. Homepage-as-root long term (ADR if we diverge from Homepage).