Raspberry Pi Kubernetes Cluster with K3s

By Khimananda Oli | Last reviewed: August 2026

Building a Raspberry Pi Kubernetes cluster with K3s remains the most practical way to learn cloud-native architecture on real hardware without burning through AWS bills. While cloud providers offer managed services, they abstract away the low-level networking, storage, and bootstrapping challenges that define true platform engineering competence. This guide walks you through constructing a resilient, audit-ready home lab that mirrors production patterns, bridging the gap between theoretical certification and hands-on operational reality.

How do you prepare Raspberry Pi hardware for a stable K3s cluster?

Hardware selection dictates cluster reliability more than any software configuration. In my experience helping teams build edge labs across Nepal and globally, SD card failures account for over 70% of home lab outages. The Raspberry Pi Kubernetes cluster with K3s demands persistent, high-IOPS storage because etcd is extremely sensitive to write latency. For 2026 builds, use Raspberry Pi 5 (8GB) for the control plane due to its PCIe lane support for NVMe HATs, and Pi 4 (4GB+) for workers with USB3-to-SATA adapters and quality SSDs like the Samsung T7 or Crucial X6.

Critical pre-flight checklist

• Flash 64-bit OS: Use Raspberry Pi Imager to install Ubuntu Server 24.04 LTS (arm64). K3s requires 64-bit for modern container compatibility.
• Disable swap: K3s and kubelet will refuse to start or behave erratically if swap is active. Run sudo swapoff -a and remove entries from /etc/fstab.
• Enable cgroups v2: Add cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory to /boot/firmware/cmdline.txt and reboot.
• Set static IPs: Configure Netplan on each node with predictable addresses (e.g., 10.10.50.10 for control plane). See our guide to configuring static IPs with Netplan for exact YAML syntax.
• Harden SSH: Disable password auth, enforce key-based access, and change the default port. Follow the Ubuntu security hardening guide before exposing any API server.

# Verify cgroups v2 is active after reboot
mount | grep cgroup2
# Expected output includes: cgroup2 on /sys/fs/cgroup type cgroup2

# Confirm swap is permanently disabled
sudo systemctl mask swap.target
free -h | grep Swap
# Should show all zeros

How do you install and configure K3s on Raspberry Pi nodes?

K3s strips out legacy cloud provider code and bundles dependencies into a single binary, making it ideal for ARM edge devices. Unlike full Kubernetes distributions, it uses SQLite by default for single-node setups but supports etcd for HA clusters. For a multi-node Raspberry Pi Kubernetes cluster with K3s, always initialize with embedded etcd to ensure control plane resilience.

Initialize the control plane

On your designated control plane node (10.10.50.10), run the install script with explicit network settings. Avoid letting K3s auto-detect interfaces on Pis with both WiFi and Ethernet enabled, as this causes flaky node registration.

# Install K3s server with etcd and fixed advertise address
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.30.4+k3s1" sh -s - server \
  --cluster-init \
  --advertise-address 10.10.50.10 \
  --node-ip 10.10.50.10 \
  --disable traefik \
  --disable servicelb \
  --write-kubeconfig-mode 644

# Retrieve the join token for workers
sudo cat /var/lib/rancher/k3s/server/node-token

Note the --disable traefik and --disable servicelb flags. Most production-oriented labs replace Traefik with Cilium or nginx-ingress for better observability and policy enforcement. Disabling ServiceLB prevents conflicts when you later install MetalLB or kube-vip for bare-metal load balancing.

Join worker nodes securely

Copy the node token to each worker via secure transfer (never paste tokens in chat). On each worker node:

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.30.4+k3s1" K3S_URL=https://10.10.50.10:6443 K3S_TOKEN=<YOUR_TOKEN> sh -s - agent \
  --node-ip 10.10.50.11 \
  --kubelet-arg "max-pods=30"

The --kubelet-arg max-pods=30 flag is critical on Pi hardware. Default limits assume cloud VM resources; exceeding memory on a 4GB Pi triggers OOM kills during scheduling spikes. Adjust based on your actual workload profiles and monitor with Prometheus as covered in our Prometheus metrics fundamentals guide.

How do you handle persistent storage on ARM-based K3s clusters?

Storage is where most Raspberry Pi clusters fail in production-like scenarios. The default local-path-provisioner works for ephemeral tests but offers no replication. For stateful workloads like PostgreSQL or MongoDB, you need distributed block storage that survives node failure. Longhorn has become the de facto standard for bare-metal K3s labs because it’s CNCF-certified, ARM-native, and includes built-in snapshotting.

Installing Longhorn on Pi hardware

Before installing, ensure each node has an unused partition or dedicated disk mounted at /var/lib/longhorn. Never place Longhorn data on the same device as etcd or the OS root filesystem.

# Add Longhorn Helm repo and install with Pi-optimized settings
helm repo add longhorn https://charts.longhorn.io
helm repo update

helm install longhorn longhorn/longhorn \
  --namespace longhorn-system --create-namespace \
  --set persistence.defaultClassReplicaCount=2 \
  --set defaultSettings.taintToleration="node-role.kubernetes.io/control-plane=true:NoSchedule" \
  --version 1.7.0

Set defaultClassReplicaCount=2 instead of 3 on a three-node cluster. With only three nodes, losing one during maintenance would make 3-replica volumes unschedulable. Two replicas plus regular snapshots provide adequate safety for lab environments while preserving upgrade flexibility. Refer to the Longhorn distributed storage guide for backup-to-S3 configuration and disaster recovery patterns.

What are the key differences between K3s and other lightweight Kubernetes options for Raspberry Pi?

Choosing the right distribution prevents costly rework. While MicroK8s and k0s also target edge, K3s dominates the Raspberry Pi ecosystem due to lower resource overhead and tighter integration with Rancher’s GitOps tooling. The table below reflects real-world benchmarks from my 2026 lab testing on identical Pi 5 hardware.

K3s wins for Raspberry Pi specifically because its single-binary design avoids snapd overhead (MicroK8s) and complex controller meshes (k0s). If you’re already invested in Canonical’s ecosystem or need Juju charms, MicroK8s makes sense. Otherwise, K3s delivers the fastest path to a functional Raspberry Pi Kubernetes cluster with K3s that behaves like managed cloud Kubernetes.

How do you monitor and maintain a Raspberry Pi K3s cluster reliably?

A cluster without observability is just expensive blinking lights. Resource constraints on Pis mean you must choose monitoring stacks carefully. Avoid full ELK or Thanos; they’ll consume half your cluster’s capacity. Instead, deploy the lightweight Prometheus + Grafana stack with node-exporter and kube-state-metrics. Our Prometheus and Grafana setup guide provides Pi-tuned retention and scrape intervals.

Essential maintenance routines

1. Automate OS patching: Use unattended-upgrades with reboots scheduled during off-hours. K3s tolerates rolling reboots if you’ve configured pod disruption budgets.
2. Rotate certificates proactively: K3s auto-renews certs, but verify monthly with k3s certificate check. Expired certs cause silent API failures.
3. Monitor etcd disk latency: Add etcd_disk_wal_fsync_duration_seconds alerts. Values above 10ms on Pi indicate storage degradation before crashes occur.
4. Test restore procedures quarterly: Back up etcd snapshots to S3/R2 and practice restoration. Documentation without tested runbooks is compliance theater.

Deploy Your Raspberry Pi Kubernetes Cluster with Confidence

A well-built Raspberry Pi Kubernetes cluster with K3s teaches more about distributed systems than any certification exam. Focus on getting storage and networking right first; everything else layers cleanly on top. Start with three nodes, validate etcd performance before adding workloads, and treat your lab with the same rigor as production infrastructure. If you’re planning a cluster for team training or client demos and want architecture review tailored to your constraints, reach out to discuss your specific requirements.