jakman85andClaude Opus 4.8
e8c555cfeb
Greenfield spec set for a GitOps-driven PaaS+IaaS home platform: vision & requirements (R-* IDs), architecture, 14 domain specs, 11 ADRs, roadmap (phases + workstreams), and AI-agent coordination (roles, protocol, definition-of-done, task board). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
33 lines
1.8 KiB
Markdown
33 lines
1.8 KiB
Markdown
# ADR-0001 — Kubernetes distribution: k3s
|
|
- Status: Accepted
|
|
- Date: 2026-08-15
|
|
- Serves: R-PLAT-01, R-PLAT-02, R-ENV-01/02/03
|
|
- Supersedes: —
|
|
|
|
## Context
|
|
The platform runs on 3 small nodes (dev: KVMs; prod: mini-PCs) and must offer a full Kubernetes API
|
|
for both containers and VMs. It must be lightweight enough for constrained hardware yet
|
|
production-capable, HA, and identical across dev/test and prod.
|
|
|
|
## Decision
|
|
Use **k3s** as the Kubernetes distribution, deployed as a 3-node HA cluster with **embedded etcd**
|
|
(all three nodes are servers). Bundled components that conflict with our chosen stack are disabled at
|
|
install time: flannel (→ Cilium), kube-proxy (→ Cilium kube-proxy replacement), Traefik (→ Gateway
|
|
API via Cilium), and servicelb where a different LB strategy is selected. Nodes are provisioned by
|
|
OpenTofu (libvirt, dev) / bare-metal imaging (prod) + cloud-init, and joined/configured by Ansible.
|
|
|
|
## Alternatives considered
|
|
- **Full kubeadm/vanilla Kubernetes** — heavier operationally for 3 small nodes; k3s gives the same
|
|
API with far less overhead.
|
|
- **k0s / MicroK8s / Talos** — all viable. Talos is attractive (immutable, API-driven) and may be
|
|
revisited via a superseding ADR for prod hardening; k3s chosen now for its ubiquity, small
|
|
footprint, single-binary simplicity, strong community, and the operator's existing familiarity.
|
|
- **Managed cloud Kubernetes** — out of scope; this is on-prem home hardware.
|
|
|
|
## Consequences
|
|
- Lightweight, HA, uniform dev↔prod topology (R-ENV-02).
|
|
- Must explicitly disable bundled CNI/ingress/proxy to make room for Cilium + Gateway API (ADR-0002)
|
|
— captured in the Ansible bootstrap.
|
|
- Embedded etcd across 3 nodes tolerates single-node loss; do not reduce below 3 servers in prod.
|
|
- Revisit Talos for prod if immutability/hardening becomes a priority.
|