August 20, 2026
9 min read
Table of Contents
By Kokil Thapa | Last reviewed: August 2026
Building a Raspberry Pi Kubernetes cluster with K3s is the most practical way to learn distributed systems or run lightweight production workloads without cloud bills. While full Kubernetes is too heavy for ARM SBCs, K3s strips out legacy cloud-provider code and runs efficiently on Pi hardware. This guide covers the exact hardware, OS tuning, networking, and storage configuration needed for a stable cluster in 2026, based on patterns I use when prototyping infrastructure for scalable startup systems before committing to paid cloud resources.
Quick answer: A Raspberry Pi Kubernetes cluster with K3s requires three or more Pi 5 nodes running Ubuntu Server 24.04 LTS 64-bit, static IPs, cgroup memory enabled, and K3s v1.32+ installed via the official script. Use Longhorn for replicated storage and MetalLB for bare-metal load balancing to achieve production parity.
What Hardware Do You Need for a Raspberry Pi Kubernetes Cluster with K3s?
Hardware selection determines whether your cluster is a learning toy or a reliable platform. In 2026, the Raspberry Pi 5 (8GB) is the baseline for any serious K3s deployment. The Pi 4 (4GB) can still serve as a worker node for light tasks, but etcd and control-plane components benefit significantly from the Pi 5’s faster CPU and PCIe 2.0 bus. Avoid Pi 3 or Zero models entirely; they lack the RAM and 64-bit performance headroom required by modern K3s releases.
You need at least three nodes to maintain etcd quorum during updates or failures. A typical starter configuration uses one Pi 5 as the control plane and two Pi 5s (or Pi 4s) as workers. For storage-intensive workloads like databases or media servers, add a dedicated NVMe SSD via the Pi 5’s PCIe HAT instead of relying on microSD cards, which fail predictably under container write loads.
- Control Plane: Raspberry Pi 5 8GB + active cooler + NVMe SSD (128GB minimum)
- Worker Nodes: Raspberry Pi 5 4GB/8GB or Pi 4 4GB + high-endurance microSD (SanDisk Max Endurance) or USB3 SSD
- Networking: Gigabit switch (unmanaged is fine), CAT6 cables, optional USB-C power hub with per-port switching
- Power: Official 27W USB-C PD supplies for Pi 5; avoid multi-port chargers that drop voltage under load
Thermal management is non-negotiable. K3s control planes sustain 30–50% CPU usage during reconciliation loops, and Pi 5s throttle within minutes without active cooling. Budget cases with passive heatsinks are insufficient for clustered workloads. Invest in the official Pi 5 Active Cooler or equivalent PWM-controlled fans. Monitor thermals post-install with vcgencmd measure_temp; sustained temps above 70°C indicate inadequate cooling.
How Do You Prepare the Operating System for K3s on Raspberry Pi?
K3s requires specific kernel parameters that Raspberry Pi OS and Ubuntu disable by default. Skipping this step causes silent pod evictions and OOM kills under load. Always use a 64-bit OS; K3s dropped 32-bit ARM support in 2024. Ubuntu Server 24.04 LTS is the recommended base in 2026 due to its long support window, mainline kernel, and seamless cgroup v2 integration.
Enable cgroup Memory and Swap Accounting
Edit the boot command line to enable memory tracking for containers. Without this, K3s cannot enforce resource limits or report accurate metrics.
<!-- /boot/firmware/cmdline.txt -->
console=serial0,115200 console=tty1 root=PARTUUID=xxxxx rootfstype=ext4 fsck.repair=yes rootwait cgroup_enable=cpuset cgroup_memory=1 swapaccount=1Reboot after editing. Verify with cat /proc/cgroups | grep memory; the hierarchy should show 1 in the enabled column.
Disable Swap and Set Static IPs
Kubernetes refuses to schedule pods on nodes with swap enabled. Disable it permanently:
sudo swapoff -a
echo 'CONF_SWAPSIZE=0' | sudo tee /etc/dphys-swapfile
sudo systemctl disable dphys-swapfileAssign static IPs via your router’s DHCP reservations or netplan. Dynamic IPs break K3s node registration and certificate validation. Reserve a contiguous block (e.g., 192.168.1.100–192.168.1.110) for cluster nodes. Document these assignments; debugging IP-related TLS errors hours after setup is painful.
Harden SSH and Time Sync
Disable password authentication and enforce key-based SSH. K3s tokens are sensitive; treat node access like production. Ensure systemd-timesyncd or chrony is active. Clock drift exceeding 500ms causes etcd leader elections and API server authentication failures. On my legal-tech portals running on similar ARM infrastructure, time sync issues were the #1 cause of intermittent auth bugs until we enforced NTP discipline.
How Do You Install and Configure K3s on Raspberry Pi?
K3s installation is a single command, but production clusters require explicit configuration. Never use the default install script without flags on bare metal. The following setup disables unnecessary components, sets the correct network interface, and configures etcd for low-resource environments.
Install the Control Plane Node
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.32.4+k3s1" sh -s - server \
--cluster-init \
--disable traefik \
--disable servicelb \
--flannel-iface eth0 \
--etcd-expose-metrics true \
--write-kubeconfig-mode 644 \
--node-taint "node-role.kubernetes.io/control-plane=true:NoSchedule"This disables Traefik and ServiceLB (replaced by MetalLB later), binds Flannel to the physical Ethernet interface (not wlan0), and taints the control plane to prevent user workloads from competing with etcd. Pinning the version avoids surprise upgrades during setup.
Join Worker Nodes
Retrieve the token from the control plane:
sudo cat /var/lib/rancher/k3s/server/node-tokenOn each worker, run:
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.32.4+k3s1" K3S_URL=https://192.168.1.100:6443 K3S_TOKEN=<TOKEN> sh -s - agent \
--flannel-iface eth0Verify nodes are Ready with kubectl get nodes -o wide. If a node stays NotReady, check journalctl -u k3s-agent for cgroup or network errors. Common mistakes include wrong interface names (enp0s3 vs eth0) or firewall rules blocking port 6443.
How Do You Handle Storage and Networking in a Bare-Metal Pi Cluster?
Bare-metal clusters lack cloud provider integrations, so you must manually configure storage classes and load balancers. Getting this wrong means pods stuck in Pending state or services unreachable from your LAN.
Persistent Storage with Longhorn
Longhorn is the de facto standard for K3s on Pi. It provides replicated block storage across nodes without external NAS dependencies. Install via Helm:
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"Set replica count to 2 (not 3) on three-node clusters to tolerate one failure while conserving Pi storage. Create a StorageClass referencing longhorn and set it as default. Test with a PVC-bound StatefulSet before deploying databases. MicroSD cards will degrade quickly under Longhorn’s write patterns; NVMe or USB3 SSDs are mandatory for persistent volumes.
Load Balancing with MetalLB
MetalLB assigns real LAN IPs to LoadBalancer services, replacing cloud provider LBs. Configure it in L2 mode for home/lab networks:
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: lan-pool
namespace: metallb-system
spec:
addresses:
- 192.168.1.200-192.168.1.250
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: l2-advert
namespace: metallb-system
spec:
ipAddressPools:
- lan-poolReserve the IP range in your router to prevent DHCP conflicts. After applying, Services of type LoadBalancer receive routable IPs within seconds. This is essential for exposing ingress controllers or development APIs to your local network, a pattern I rely on when testing Laravel API endpoints against real cluster infrastructure before staging.
| Component | Pi-Optimized Choice | Avoid On Pi | Reason |
|---|---|---|---|
| Ingress Controller | Nginx Ingress (lightweight) | Traefik (default) | Lower memory footprint, better Pi thermal profile |
| Storage | Longhorn (replicated) | hostPath / NFS | No single point of failure; survives node reboots |
| Load Balancer | MetalLB L2 | ServiceLB / NodePort | Real LAN IPs; no port management overhead |
| Monitoring | kube-prometheus-stack (tuned) | Datadog / New Relic | Self-hosted; no egress costs or ARM agent issues |
| CNI Plugin | Flannel (VXLAN) | Calico / Cilium | Lower CPU overhead on ARM; sufficient for <20 nodes |
What Workloads Run Reliably on a Pi K3s Cluster?
Not every application belongs on ARM SBCs. Focus on stateless services, development environments, and lightweight stateful apps. Avoid JVM-heavy stacks, large ML inference, or high-IOPS databases unless you’ve validated performance on your specific hardware.
Ideally suited workloads include:
- Development/Staging APIs: Laravel, Symfony, or Node.js apps mirroring production architecture
- GitOps Controllers: ArgoCD or Flux managing manifests for larger cloud clusters
- Monitoring Stacks: Prometheus, Grafana, Loki with retention tuned for SD card longevity
- Home Automation: Home Assistant, MQTT brokers, DNS/DHCP servers
- CI Runners: Self-hosted GitLab/GitHub Actions runners for ARM builds
Always set resource requests and limits. Pi nodes have finite RAM; unbounded pods will trigger OOM kills that cascade through etcd. Use Vertical Pod Autoscaler in recommendation mode to right-size workloads over time. For teams evaluating whether to invest in physical clusters versus cloud, understanding these constraints informs better cloud hosting decisions when scaling beyond lab scale.
Maintaining Your Raspberry Pi Kubernetes Cluster with K3s
Ongoing maintenance separates functional clusters from abandoned projects. Automate OS and K3s updates separately. Use k3sup or Ansible for orchestrated upgrades that drain nodes gracefully. Never upgrade all nodes simultaneously; etcd quorum loss during rolling updates is recoverable but tedious.
Monitor SD card health with smartctl if using USB adapters that support SMART, or track write amplification via Longhorn metrics. Replace cards proactively every 12–18 months under continuous write loads. Keep backups of etcd snapshots (k3s etcd-snapshot save) on external storage. Test restores quarterly; untested backups are fiction.
Finally, document everything. Your future self debugging a flaky node at 2 AM needs to know which Pi has the NVMe drive, what IP range MetalLB owns, and where the recovery playbook lives. Treat your Pi cluster with the same operational rigor as production cloud infrastructure. The skills transfer directly, and the cost of mistakes is measured in hours, not dollars.
Next Steps for Your Pi K3s Journey
A Raspberry Pi Kubernetes cluster with K3s delivers tangible value as both a learning platform and a lightweight production environment when configured correctly. Start with three Pi 5 nodes, Ubuntu 24.04, pinned K3s versions, and disciplined storage/networking choices. Validate workloads against ARM constraints before deploying. When you’re ready to apply these patterns to business-critical systems or need guidance on infrastructure decisions, reach out to discuss your project requirements.
Frequently Asked Questions
Raspberry Pi 4 Model B with at least 4GB RAM is the practical minimum. The 8GB variant is preferred for control plane nodes running etcd and API server workloads without swapping.
Expect Rs 25,000 to Rs 35,000 (USD 190–265) for three Pi 4 8GB units, PoE HATs, SD cards, and a network switch, excluding power supply and enclosure costs.
Technically possible but not recommended for production. Limited RAM and USB-based networking cause instability under load; stick to Pi 4 or Pi 5 for reliable cluster operations.
K3s is a single binary under 100MB with reduced memory footprint, making it viable on ARM hardware with limited resources. It replaces etcd with SQLite by default and bundles essential components like Traefik and CoreDNS, eliminating complex setup steps that standard k8s requires on constrained devices. In my experience deploying lightweight clusters, this reduction translates directly to faster boot times and lower idle resource consumption on Pi hardware.
Use local-path-provisioner for single-node testing or NFS backed by a dedicated NAS for multi-node persistence. SD cards wear out quickly under database write loads; I have seen card corruption within months when running MySQL directly on Pi storage. For production workloads on projects like legal-tech portals, I mount external SSDs via USB3 or use network storage to separate compute from stateful data, significantly improving reliability and lifespan of the cluster nodes.
Active cooling is mandatory for sustained Kubernetes workloads. Passive heatsinks alone cannot dissipate heat during pod scheduling bursts or image pulls. I use PoE HATs with integrated fans on cluster nodes because they provide both power and cooling through a single cable, reducing clutter. Monitor temperatures with vcgencmd measure_temp and set up alerts if readings exceed 70C consistently. Without proper cooling, CPU frequency scaling will degrade cluster performance unpredictably during peak loads.
Use a dedicated gigabit switch rather than relying on WiFi or shared home networks. K3s node communication is sensitive to latency and packet loss; WiFi introduces jitter that causes intermittent node NotReady states. Assign static IPs via DHCP reservation or configure netplan with fixed addresses. I always separate management traffic from application traffic using VLANs when possible. For clusters running services like eSewa payment webhooks, reliable networking prevents callback failures that are difficult to debug in distributed systems.
Use the official install script with INSTALL_K3S_VERSION pinned to your target release, then drain and cordon nodes sequentially. K3s supports in-place upgrades better than full k8s, but always backup etcd or SQLite datastore first. On clusters managed via Deployer or Ansible, I automate this as a rolling update task. Test upgrades on a non-production node before applying cluster-wide. Skipping versions is generally safe in K3s, but read release notes for breaking changes in CRDs or deprecated flags that might affect your specific workload configurations.
Insufficient memory is the most frequent cause; Pi 4 4GB nodes exhaust resources quickly with multiple workloads. Check kubectl describe pod for FailedScheduling events indicating insufficient cpu or memory. Also verify architecture labels match your container images; many Docker Hub images lack arm64 variants and will never schedule on Pi hardware. Taints applied to control plane nodes can also block scheduling if tolerations are missing. I regularly see this when developers test amd64 images locally then deploy to ARM clusters without rebuilding.
K3s enables TLS encryption between components by default and supports RBAC, network policies, and secrets encryption at rest. However, physical security matters more with Pi clusters since anyone with SD card access can extract credentials. Disable unused services, enforce SSH key authentication only, and keep the OS patched. For client projects handling sensitive data like legal documents, I run K3s behind a reverse proxy with WAF rules and never expose the API server directly. Treat Pi clusters as edge infrastructure requiring the same hardening as cloud deployments.
Yes, but separate the database from the cluster. Running MySQL on Pi storage causes performance bottlenecks and card wear. Deploy WordPress pods with Redis caching and mount uploads to NFS or S3-compatible storage. I have tested WooCommerce stores on Pi K3s for development and staging environments successfully, but for production eCommerce sites serving real transactions, I prefer traditional VPS hosting or managed platforms. Pi clusters excel at CI runners, monitoring stacks, and learning environments rather than customer-facing commerce workloads requiring consistent sub-second response times.
Install metrics-server for basic kubectl top functionality and Prometheus with Grafana for detailed dashboards. Lightweight exporters like node-exporter-lite reduce overhead on ARM hardware. Set up alerts for memory pressure, disk saturation, and temperature thresholds before they cause node failures. On clusters I maintain, I use Loki for log aggregation instead of Elasticsearch to avoid Java heap exhaustion on constrained nodes. Monitoring is non-negotiable; without visibility into per-node resource consumption, you will troubleshoot phantom issues caused by silent OOM kills or thermal throttling during critical operations.
Orange Pi 5 Plus with Rockchip RK3588 offers superior performance and NVMe support at similar pricing. Used thin clients with Intel Celeron J4125 provide x86 compatibility for broader container image support. For learning purposes, Multipass or kind on an existing laptop simulates multi-node clusters without hardware investment. When sourcing Pi alternatives locally in Kathmandu, verify community support for K3s ARM builds before purchasing; some boards require custom kernel patches that complicate maintenance. I evaluate alternatives based on long-term software support availability, not just benchmark scores.
For SQLite backend, copy /var/lib/rancher/k3s/server/db/state.db while K3s is stopped or use the built-in snapshot command. For etcd, use etcdctl snapshot save with regular cron jobs. Store backups off-cluster on NAS or cloud storage; keeping backups on the same SD card defeats the purpose. Test restores quarterly on fresh hardware to validate procedures. On production-adjacent clusters, I automate daily snapshots via GitLab CI scheduled pipelines pushing encrypted archives to S3. Documented recovery procedures matter more than backup frequency; untested backups provide false confidence during actual failure scenarios.
Excellent for learning Kubernetes concepts, testing Helm charts, and running CI pipelines locally. Not suitable as primary production infrastructure for revenue-generating applications due to hardware limitations and lack of vendor support. I use Pi clusters for prototyping architectures before deploying to cloud or VPS environments for clients. The gap between Pi cluster behavior and production k8s manifests in storage performance, network reliability, and scaling characteristics. Treat it as an advanced sandbox that accelerates skill development while maintaining realistic expectations about operational boundaries for business-critical systems.
