# 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.