Flatcar Homelab¶
A rack of machines and a pile of YAML: a bare metal Kubernetes cluster that provisions itself over PXE, keeps its entire state in Git, and is documented here so that nothing has to be re-derived at 02:00.
It is a real cluster doing real work, built the way a production cluster is built, at a scale where breaking it is a learning experience rather than an incident review.
Start here¶
-
I want to build this
Adapt It to Your Cluster first — the repository URL, domain and addresses are hardcoded — then the Quickstart. Set aside an afternoon.
-
I know Kubernetes, not this repo
Architecture for how it fits together, Design Decisions for why, and Known Limitations for what it does not do.
-
I am learning Kubernetes
Core Concepts covers the five ideas underneath this cluster — immutable OS, first-boot provisioning, sysexts, network boot, GitOps — and what each one costs.
-
Something is broken
Operations has the health check and the symptom-to-cause table. If it is a stalled install, the PXE troubleshooting table.
-
I am making a change
Development for the checks a pull request must pass, GitOps Strategy for what a merge does to the cluster, and the repository layout for where things live.
The stack in one table¶
Each choice had a simpler alternative that was rejected on purpose; the reasoning and what each one costs is in Design Decisions.
| Layer | Choice | Why it is not the obvious one |
|---|---|---|
| OS | Flatcar Container Linux | Read-only /usr. You cannot apt install your way out of a problem, which turns out to be the feature |
| Cluster | Kubernetes via kubeadm | Stock upstream, so the upstream docs apply verbatim |
| Network | Cilium | eBPF, no kube-proxy, no iptables archaeology. Also supplies Gateway API and the LoadBalancer addresses bare metal does not come with |
| Storage | Rook-Ceph | Replicated block storage across the nodes, and the component most likely to teach you humility |
| Secrets | OpenBao | Nothing sensitive in Git, at the price of a manual unseal after every reboot |
| Delivery | ArgoCD | If it is not in Git it is not real, and it will not survive the next reconcile |
The sections follow the reader's journey: Get Started to build it, Architecture to understand it, Platform for each of the components, Operations to run it, and Development to work on the repository.