k3s role in the homelab / farm platform¶
Purpose: Define what k3s is responsible for in this wiki’s platform doctrine—certified Kubernetes on small fleets—versus what belongs in compose, bare metal, or vendor appliances. Official baseline: K3s documentation (architecture, installation, HA datastore).
Package: Platform doctrine package — homelab / farm edge. Strategy: Platform strategy for farm and homestead services.
What k3s provides¶
| Responsibility | Notes |
|---|---|
| Kubernetes API | Deploy Deployments, StatefulSets, Services, Ingress—same object model as larger clusters, lower operational surface than full kubeadm in many homelab setups. |
| Node lifecycle | Server nodes (control plane + datastore) vs agent nodes (workers)—see quick-start and bootstrap sequence. |
| Embedded datastore option | Single-server SQLite / embedded etcd patterns vs HA multi-server—not interchangeable without migration planning (HA meaning and constraints). |
| Extension points | Helm, CSI (e.g. Longhorn), CNI—enables stateful farm apps without inventing a bespoke orchestrator. |
Control-plane assumptions (this repo)¶
- Phase 0/1 defaults to one k3s server and N agents unless you have written uptime and failover requirements (
platform decision memo). - etcd / datastore backups are cluster infrastructure backups—not a substitute for PostgreSQL logical dumps for farmOS (
Kubernetes platform backup / DR). - Pi-class hardware: CPU/RAM/IOPS budgets are tight; not every container deserves a cluster—see operational boundaries below.
Operational boundaries¶
| In scope for k3s here | Prefer simpler path first |
|---|---|
| farmOS + DB, MQTT stack, observability that benefits from uniform deploy/rollout | Single static service on one Pi → Docker Compose or k3s with one manifest—avoid microservice sprawl (farmOS Docker capture as lighter dev pattern). |
| StatefulSets with PVCs + backup discipline | “Kubernetes because resume keyword” without workloads |
| Same cluster at homestead controlling replication to edge | Multi-site HA Kubernetes without WAN and power truth |
Diagram — k3s in the stack¶
```mermaid flowchart LR subgraph nodes["Pi fleet"] s["k3s server"] a1["agent"] a2["agent"] end
s --> api["Kubernetes API"] a1 --> api a2 --> api api --> wl["Workloads"] wl --> csi["CSI — e.g. Longhorn"] ```