Build a Raspberry Pi Kubernetes Cluster with K3s: A Hands-On Way to Learn Distributed Systems

A Raspberry Pi cluster running Kubernetes is one of the best cheap, low-stakes ways to actually learn distributed systems and container orchestration hands-on — concepts that are otherwise abstract until you've broken and fixed a real cluster yourself. This build covers assembling a multi-node Pi cluster and getting a lightweight Kubernetes distribution running across it.

Why Build This

Kubernetes runs the infrastructure behind a huge amount of production software, and understanding it hands-on is a genuinely valuable skill — but spinning up cloud VMs to learn on costs real money and doesn't give you the physical, tangible feedback of a cluster sitting on your desk with status LEDs you can actually watch. A Pi cluster is also just a satisfying object to have built, separate from any practical justification.

Hardware

ComponentRecommendation Raspberry Pi nodes3-5 Pi 4s (4GB+ RAM) is a solid starting cluster size — one control-plane node, the rest as workers. More nodes is more interesting for learning but not strictly necessary to get real value from the project MicroSD cards32GB+ per node, quality brand — a corrupted card on one node is a headache to diagnose in a cluster context Cluster caseStackable Pi cluster cases (widely available) (widely available) keep things tidy and usually include mounting for a shared switch Network switchA small gigabit switch dedicated to the cluster — keep cluster traffic on its own network segment if possible PowerA powered USB hub rated for multiple Pis, or individual supplies — undervoltage across multiple nodes causes confusing, hard-to-diagnose cluster instability

Choosing Your Kubernetes Distribution

Full upstream Kubernetes is heavyweight for Pi hardware. Lightweight distributions are the practical choice:

DistributionNotes K3sThe most common choice for Pi clusters — a genuinely lightweight, certified Kubernetes distribution from Rancher, single binary install, low resource footprint MicroK8sCanonical's lightweight distribution, snap-based install, also viable on Pi hardware Full K8s (kubeadm)Possible but genuinely heavier than necessary for a learning cluster — more resource overhead for little added educational value over K3s

K3s is the most commonly recommended starting point for Pi clusters specifically — it strips out some of full Kubernetes's heavier components while remaining a real, compliant Kubernetes implementation, meaning what you learn transfers directly to production-scale clusters.

Base OS Setup (All Nodes)

1. Flash Raspberry Pi OS Lite (64-bit) to each node's SD card
2. Enable cgroup memory and CPU controllers, required for Kubernetes, by adding to /boot/cmdline.txt: cgroup_memory=1 cgroup_enable=memory
3. Set a unique, memorable hostname per node: sudo hostnamectl set-hostname k3s-master (or k3s-worker-1, etc.)
4. Disable swap if enabled — Kubernetes generally expects swap disabled: sudo dphys-swapfile swapoff && sudo systemctl disable dphys-swapfile
5. Assign static IPs (via router DHCP reservation or static config on each Pi) so node addresses don't shift on reboot

Installing K3s: Control Plane

On your designated control-plane (master) node:

curl -sfL https://get.k3s.io | sh -

After install, get the node token needed for workers to join the cluster:

sudo cat /var/lib/rancher/k3s/server/node-token

Installing K3s: Worker Nodes

On each worker node, join it to the cluster using the control plane's IP and the token from above:

curl -sfL https://get.k3s.io | K3S_URL=https://<master-ip>:6443 K3S_TOKEN=<token> sh -

Verifying the Cluster

Back on the control-plane node:

sudo k3s kubectl get nodes

You should see all your nodes listed with Ready status. If a node shows NotReady, check that node's K3s service logs (sudo journalctl -u k3s-agent -f on workers) — common culprits are network connectivity to the master, or the cgroup settings from setup not being applied correctly.

First Deployment

A simple test deployment to confirm the cluster actually schedules and runs workloads across nodes:

sudo k3s kubectl create deployment nginx-test --image=nginx --replicas=3 sudo k3s kubectl get pods -o wide

The -o wide flag shows which node each pod landed on — you should see the three replicas distributed across your worker nodes, which is the whole point: Kubernetes deciding where to run workloads rather than you manually placing them.

What to Actually Learn On It

Once the base cluster is running, this is where the real learning value is:

• Deployments and scaling — scale a deployment up/down and watch pods get scheduled or terminated in real time
• Services and networking — expose a deployment and understand how traffic actually reaches pods across nodes
• Node failure recovery — power off a worker node mid-workload and watch Kubernetes reschedule its pods elsewhere — this single exercise teaches more about why orchestration exists than any amount of reading
• Persistent storage — understand the difference between ephemeral pod storage and persistent volumes, which matters enormously once you're running anything stateful
• Helm charts — once comfortable with raw manifests, Helm's templating for deploying more complex applications

Common Issues

SymptomLikely Cause Nodes flapping between Ready/NotReadyOften power-related on Pi hardware — undervoltage causes instability that looks like network/cluster problems but isn't Pods stuck in PendingInsufficient resources on available nodes, or a scheduling constraint that can't be satisfied — check kubectl describe pod for the actual scheduler error Worker won't join clusterToken mismatch, or master's port 6443 not reachable from the worker — verify network connectivity and firewall rules first

A Pi cluster won't run anything at real production scale, but that's not the point — it's cheap enough to break on purpose, small enough to fully understand, and physical enough that pulling a power cable to simulate node failure actually means something. That hands-on feedback loop is worth more for learning than a much larger cloud cluster you're afraid to experiment on.