Cluster (Stage 1)¶
Stage 1 is Ansible. It takes a freshly installed Ubuntu host, hardens it, and turns it into a Kubernetes control plane, plus any worker nodes you have declared.
Everything runs from one playbook, stage1/site.yml, driven by stage1/inventories/inventory.yml.
What it produces¶
| Layer | Component |
|---|---|
| Host | Ubuntu with swap disabled, memory cgroups enabled, UFW, fail2ban, snapd removed |
| Container runtime | containerd + runc, with crictl and nerdctl for debugging |
| Kubernetes | kubeadm-provisioned control plane, kubelet as a systemd unit |
| Networking | Cilium CNI, MetalLB for LoadBalancer services |
| Metrics | metrics-server, so kubectl top works |
Cluster types¶
kubernetes_cluster_type (a Bitwarden secret, see Bitwarden secrets) selects one of three mutually exclusive paths in play 3.
Full upstream Kubernetes. This is the only path with worker-node support, rolling upgrades, preflight checks and Cilium. Everything else in these docs assumes kubeadm unless stated.
Roles: kubeadm_pre_setup → kubeadm_server, with kubeadm_node pulled in as a dependency.
Lightweight single-binary Kubernetes for resource-constrained hosts. No worker plays, no upgrade automation, built-in CNI instead of Cilium.
Roles: k3s_pre_setup → k3s_server.
Runs Kubernetes inside Docker on the host. Provisions, but is not known to work end to end with the Stage 2 platform.
Roles: minikube_pre_setup → minikube_server.
Where to go next¶
| I want to | Read |
|---|---|
| Understand what runs on a node and why | Architecture |
| Understand the playbook's six plays and their safety knobs | The site.yml playbook |
Add a worker, or understand worker_hosts_json |
Inventory and groups |
| Re-run only part of the playbook | Tags and partial runs |
| Know what triggers a reboot | Handlers |
| Read what a specific role does | Roles |
| Upgrade Kubernetes | Kubernetes upgrades |
| Look up a command | Tasks |