Home-Network/home-network-k3s
2
0 Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
c626349c7d5bc9e6966d742a7f87c0b917ae487d
home-network-k3s/roadmap/workstreams.md
T
jakman85andClaude Opus 5.5 250fb54154 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]>
2026-11-08 22:46:00 -06:00

5.9 KiB
Raw Blame History

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, image pipeline, PM agent 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 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 dependencies and egress compile to CiliumNetworkPolicies/egress routing. Consumed by WS-APPS/WS-VM.
  • StorageClasses (WS-STORAGE) — the longhorn family (replicated, including static and VM variants) and bulk (media, NFS). 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) — the Renovate conventions a ServiceDefinition's update block maps to.
  • SSO/auth contract (WS-SEC) — how a ServiceDefinition's auth block (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)

  1. pihole (DNS underpinning) →
  2. 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. →
  3. 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. →
  4. plex (largest; validates bulk tier + L4 remote access) →
  5. 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 (delivered as Crafty, platform-managed), unifi (a KubeVirt VM), semaphore → kasm (not onboarded).

As each service onboards, it adopts SSO per its auth mode (native OIDC or forward-auth) — ../docs/15-identity-and-access.md.

GitOps source (WS-GITOPS, tied to step 2): Flux follows the self-hosted, in-cluster Gitea; CI (Kyverno gate + Chainsaw conformance Job trigger) runs on Gitea Actions; PRs are the enforced merge gate into main.

Each onboarding is a full acceptance-gate pass (../agents/definition-of-done.md), not just a merged manifest.

Reference in new issue View Git Blame Copy Permalink