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

+12 -10
View File
@@ -19,8 +19,8 @@ The platform must provide:
for workloads that cannot be containerized.
- **Network isolation**: default-deny east-west traffic; explicit, port-level allow rules between
services (firewall-like).
- **Multi-WAN egress**: some services egress the normal internet; others are routed through a
custom VPN connection. Egress path is a declarative property of a service.
- **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.
@@ -32,15 +32,16 @@ The platform must provide:
based test — and the specifications themselves are human-owned and immutable to the implementing
agents.
## Two environments
## One live environment
| Environment | Substrate | Purpose | Status |
|---|---|---|---|
| **dev/test** | Local KVM virtual machines on a workstation, provisioned by IaC | Prove the platform end-to-end before hardware exists | **Active development target** |
| **prod** | 3× mini-PC bare-metal k3s cluster, each with local storage | The real deployment | **Not ready — design for it, do not build on it yet** |
| **prod** | 3× mini-PC bare-metal k3s cluster, each with local storage | The real deployment | **Live; roadmap Phase 7 open** |
The dev/test environment is the proving ground. Everything must be authored so that the *same*
GitOps configuration promotes to production with only environment-scoped overrides.
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](https://gitea.home.keithjackson.dev/Home-Network/home-network-k3s-impl).
## How to use this repository (start here)
@@ -61,7 +62,7 @@ GitOps configuration promotes to production with only environment-scoped overrid
home-network-k3s/
├── README.md ← you are here
├── AGENTS.md ← rules of engagement for AI agents
├── CONTRIBUTING.md ← git workflow (feature branches → main; Gitea/CI-CD to come)
├── 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
@@ -79,7 +80,8 @@ home-network-k3s/
│ ├── 12-command-center-ui.md
│ ├── 13-service-catalog.md
│ ├── 14-testing-and-conformance.md
│ └── 15-identity-and-access.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
@@ -104,4 +106,4 @@ system meets the spec.
- **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, deploy to two environments.** dev/test and prod differ only by scoped overrides.
- **Design once.** Configuration is one base plus scoped overlay overrides.