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]>
5.7 KiB
5.7 KiB
Roadmap — Workstreams
A workstream is a durable area of ownership. Each maps to an agent role
(../agents/roles.md), owns a set of specs, exposes interfaces other
workstreams depend on, and delivers against requirement IDs. Interfaces are contracts — change them
only via ../agents/coordination-protocol.md.
| ID | Workstream | Owns (specs) | Serves | Depends on |
|---|---|---|---|---|
| WS-INFRA | Infra & cluster bring-up | 02 | R-PLAT-01, R-ENV-* | — |
| WS-GITOPS | GitOps, CI, catalog renderer | 05, 13 | R-GITOPS-*, R-UPD-02 | WS-INFRA |
| WS-NET | Networking, isolation, egress, ingress | 03, 09 | R-NET-, R-DNS- | WS-INFRA |
| WS-STORAGE | Storage, state, backup/DR | 04 | R-STATE-* | WS-INFRA |
| WS-SEC | Secrets, TLS, RBAC, identity/SSO, auditability | 07, 08, 15 | R-SEC-, R-TLS-, R-IDP-* | WS-INFRA, WS-NET |
| WS-OBS | Observability & alerting | 10 | R-OBS-* | WS-INFRA, WS-STORAGE |
| WS-UPDATE | Automated updates | 11 | R-UPD-* | WS-GITOPS, WS-OBS |
| WS-VM | KubeVirt IaaS | 06 | R-PLAT-03 | WS-NET, WS-STORAGE |
| WS-APPS | Service onboarding (13 services) | 13 | app requirements | WS-GITOPS, WS-NET, WS-STORAGE, WS-SEC, WS-OBS |
| WS-C2 | Command & Control UI | 12 | R-C2-* | WS-OBS, WS-APPS, WS-SEC |
| WS-TEST | Conformance testing (cross-cutting) | 14 | R-TEST-* | WS-INFRA, WS-GITOPS |
Key interfaces (contracts between workstreams)
- ServiceDefinition schema (WS-GITOPS owns) — the operator surface every app/VM is expressed in. WS-APPS, WS-VM consume it; WS-NET/STORAGE/SEC/OBS render pieces of it. The most important contract in the system.
- Network baseline & policy rendering (WS-NET) — default-deny + how
dependenciesandegresscompile to CiliumNetworkPolicies/egress routing. Consumed by WS-APPS/WS-VM. - StorageClasses (WS-STORAGE) —
longhorn(replicated) andbulk(media). Consumed by everyone with state. - Issuer + Gateway TLS (WS-SEC + WS-NET) — wildcard cert + Gateway listeners that HTTPRoutes attach to.
- Observability contract (WS-OBS) — how a service declares metrics/SLIs/alerts and gets dashboards. Consumed by WS-APPS/WS-VM.
- Update policy contract (WS-UPDATE) — ImagePolicy/Renovate conventions a ServiceDefinition's
updateblock maps to. - SSO/auth contract (WS-SEC) — how a ServiceDefinition's
authblock (oidc / forward-auth / native / groups) maps to a Keycloak client or oauth2-proxy protection (15). Consumed by WS-APPS/WS-C2. - Conformance harness + gate (WS-TEST) — the reproducible test framework (Kyverno for L0 policy, Chainsaw for L1/L2/L3 behavior + fault-injection, ADR-0011), requirement-coverage report, and CI/phase gates every workstream's tests plug into. Each workstream authors its own behavior tests against this harness (14).
Parallelization guidance
- WS-TEST stands up the conformance harness early (Phase 0–1) so every other workstream lands with passing, reproducible tests from day one — testing is not a trailing phase.
- After WS-INFRA delivers a cluster + Flux (Phase 1), WS-NET, WS-STORAGE, WS-SEC can proceed largely in parallel (Phase 2).
- WS-OBS, WS-UPDATE, WS-VM layer on next (Phases 3–5), overlapping.
- WS-APPS is gated on the platform contracts being stable; onboard services in the dependency order below.
- WS-C2 is last-ish (Phase 6) since it aggregates everything.
WS-APPS onboarding order (respect dependencies from 13)
- pihole (DNS underpinning) →
- gitea — bootstrapping-critical; brought online early so the platform self-hosts its git
and CI/CD; after it is stable, WS-GITOPS cuts Flux's source over to Gitea and moves CI to Gitea
Actions (
../docs/05-gitops-and-delivery.md,../CONTRIBUTING.md). DR-critical → off-cluster backup + mirror. → - keycloak (+ oauth2-proxy) — foundational IdP/SSO, brought online early so later services
integrate SSO as they onboard (
../docs/15-identity-and-access.md). DR-critical + break-glass path. → - plex (largest; validates bulk tier + public exposure) →
- qbittorrent, jackett (VPN + kill-switch proof) → 6. sonarr, radarr (VPN + arr↔downloader allows) → 7. seerr (cross-service allows to arr + plex) → 8. nextcloud (DR-critical data + backups) → 9. minecraft, unifi, semaphore, kasm (remaining).
As each service onboards, it adopts SSO per its auth mode (native OIDC or forward-auth) —
../docs/15-identity-and-access.md.
GitOps source migration (WS-GITOPS, tied to step 2): local bootstrap source → self-hosted Gitea;
CI (Kyverno gate + Chainsaw conformance Job trigger) moves to Gitea Actions; PRs become the enforced
merge gate into main.
Each onboarding is a full acceptance-gate pass (../agents/definition-of-done.md),
not just a merged manifest.