jakman85andClaude Opus 4.8
de26a53d4b
- Add CONTRIBUTING.md: interim local-git rules (no work on main; every change a feature branch merged into main) and the target state (Gitea-hosted repos, GitOps source cutover, CI/CD via Gitea Actions running the Kyverno gate + Chainsaw conformance Job, PR merge gate). Note the self-hosted-git bootstrapping circularity + off-cluster mirror/backup mitigation. - AGENTS.md: add section 12 (version-control workflow). - docs/05: source-of-truth migration (local bootstrap -> self-hosted Gitea). - docs/13 + roadmap: reprioritize Gitea as bootstrapping-critical, onboarded early (WS-APPS step 2); nextcloud onboarding split out. - task-board: T-6.1a (gitea early), T-6.1b (source+CI migration to Gitea). Co-Authored-By: Claude Opus 4.8 (1M context) <[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).
- 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.
- 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.
Two environments
| 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 |
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.
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 → main; Gitea/CI-CD to come)
├── 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
├── 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, deploy to two environments. dev/test and prod differ only by scoped overrides.