jakman85andClaude Opus 5.5
250fb54154
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]>
6.1 KiB
6.1 KiB
Home Platform — k3s + Longhorn Onboarding Platform
This repository is a specification, not an implementation. It defines what to build and how the work is organized so that teams of AI agents (and their human reviewers) can implement a self-service onboarding platform for home infrastructure at both the PaaS (containerized apps) and IaaS (virtual machines) level.
What we are building
A single, GitOps-driven platform, running on a k3s Kubernetes cluster backed by Longhorn distributed storage, that lets an operator onboard, run, update, and tear down services — both containers and virtual machines — through one consistent Kubernetes API, CLI, and YAML configuration surface.
The platform must provide:
- PaaS: containerized workloads onboarded via GitOps.
- IaaS: virtual machines managed through the same Kubernetes API/CLI/YAML (via KubeVirt), for workloads that cannot be containerized.
- Network isolation: default-deny east-west traffic; explicit, port-level allow rules between services (firewall-like).
- Multiple egress paths: some services egress the normal internet; others are routed through a custom VPN connection. Egress path is a declarative property of a service.
- Stateful durability: any service can be destroyed and rebuilt on a whim without losing data.
- Hands-off updates: services update to latest stable versions on a schedule — no human, no AI, no hand-written GitOps change required.
- Trusted TLS: every service gets an auto-issued, auto-renewed, non-self-signed certificate.
- Observability: services are monitored; issues are reported by email and on dashboards.
- A command & control center: the root of
home.keithjackson.devis a UI that surfaces and controls everything running in the cluster. - Provable conformance: every requirement is verified by an automated, reproducible, behavior- based test — and the specifications themselves are human-owned and immutable to the implementing agents.
One live environment
| Environment | Substrate | Purpose | Status |
|---|---|---|---|
| prod | 3× mini-PC bare-metal k3s cluster, each with local storage | The real deployment | Live; roadmap Phase 7 open |
The dev/test cluster that proved the platform was decommissioned in 2026-09 (ADR-0017). Configuration is authored once as a base plus an environment-scoped overlay, so any future environment needs overrides only. The platform is built in the implementation repo.
How to use this repository (start here)
- Read
AGENTS.md— the rules of engagement for every AI agent working here. - Read
docs/00-vision-and-scope.md— the north star and the non-negotiable requirements (with stable requirement IDs). - Read
docs/01-architecture-overview.md— the chosen stack and how the pieces fit. - Consult
decisions/— the Architecture Decision Records (ADRs) that lock in every major technology choice and why. Do not re-litigate a decision; if you disagree, open a superseding ADR per the process indecisions/README.md. - Pick up work from
roadmap/andagents/task-board.md— phased delivery plan, workstreams, dependencies, and the live task board.
Repository map
home-network-k3s/
├── README.md ← you are here
├── AGENTS.md ← rules of engagement for AI agents
├── CONTRIBUTING.md ← git workflow (feature branches → PRs → main)
├── GLOSSARY.md ← shared vocabulary (read to avoid ambiguity)
├── docs/ ← the specification, by domain
│ ├── 00-vision-and-scope.md
│ ├── 01-architecture-overview.md
│ ├── 02-environments-and-provisioning.md
│ ├── 03-networking-isolation-and-egress.md
│ ├── 04-storage-and-state.md
│ ├── 05-gitops-and-delivery.md
│ ├── 06-vm-workloads-kubevirt.md
│ ├── 07-security-and-secrets.md
│ ├── 08-tls-and-certificates.md
│ ├── 09-dns-and-ingress.md
│ ├── 10-observability-and-alerting.md
│ ├── 11-automated-updates.md
│ ├── 12-command-center-ui.md
│ ├── 13-service-catalog.md
│ ├── 14-testing-and-conformance.md
│ ├── 15-identity-and-access.md
│ └── 16-known-gaps.md
├── decisions/ ← ADRs (one decision per file) + index/template
├── roadmap/ ← phases.md, workstreams.md
└── agents/ ← roles, coordination protocol, DoD, task board
Requirement traceability
Every hard requirement has a stable ID (e.g. R-NET-01) defined in
docs/00-vision-and-scope.md. Implementation work, ADRs, and
task-board items must reference the requirement IDs they satisfy. This is how we prove the built
system meets the spec.
Ground rules (the short version — full detail in AGENTS.md)
- Specs are the source of truth — and are immutable to agents. Code and tests serve the spec.
AI agents may not change the
docs/, requirements, or accepted ADRs; a spec that is wrong or can't be met is an escalation to the human, never an edit (R-TEST-06). - Done means a green, reproducible, behavior-based test. Every requirement is verified by an
automated, requirement-tagged conformance test (
docs/14-testing-and-conformance.md, ADR-0010); a manual demo or "it merged" is not acceptance. - Everything is GitOps. No click-ops in the cluster except where an ADR explicitly allows it.
- Nothing is self-signed, nothing is manual, nothing loses data. These three properties are acceptance gates, not aspirations — and each is proven by a test.
- Design once. Configuration is one base plus scoped overlay overrides.