How to Build a Kubernetes Cluster on Raspberry Pi for Edge Computing

Quick Summary

Building a Kubernetes cluster on Raspberry Pi is an excellent way to learn container orchestration while creating a low-cost, energy-efficient edge computing platform. This guide walks you through the entire process—from selecting hardware to deploying your first edge application. You’ll use Raspberry Pi OS Lite, Docker, and kubeadm to create a multi-node cluster capable of running real workloads. By the end, you’ll have a functional cluster that can serve as a testing ground for edge computing scenarios, IoT data processing, or a home lab for Kubernetes certification prep.

Key Takeaways:

A minimum of 3 Raspberry Pi 4 nodes (1 master, 2 workers) is recommended for a functional cluster
Raspberry Pi OS Lite (64-bit) is the ideal operating system for minimal resource overhead
kubeadm simplifies cluster initialization and node joining significantly
Edge computing on Pi requires lightweight images and ARM-compatible containers
Expect to spend 2-4 hours for a complete setup, depending on your experience level

Introduction

The intersection of edge computing and Kubernetes represents one of the most exciting developments in modern infrastructure. Edge computing brings computation and data storage closer to the devices where data is generated, reducing latency and bandwidth usage. Kubernetes, the de facto standard for container orchestration, provides the management layer needed to deploy, scale, and operate applications across these distributed edge nodes.

Raspberry Pi devices have emerged as the perfect platform for experimenting with edge Kubernetes clusters. They’re affordable (a 4GB Pi 4 costs around $55), energy-efficient (drawing 3-5 watts under load), and powerful enough to run real containerized workloads. A cluster of Pis can simulate a production edge environment for a fraction of the cost of traditional servers.

This guide provides a comprehensive, hands-on approach to building your own Kubernetes cluster using Raspberry Pi. Whether you’re a developer exploring edge computing, a student learning container orchestration, or an IT professional prototyping a distributed system, this tutorial will give you the knowledge and practical skills to create a working cluster.

Why Use Raspberry Pi for Edge Computing?

Edge computing addresses the limitations of centralized cloud architectures by processing data closer to its source. Raspberry Pi clusters offer several compelling advantages for this use case:

Cost Efficiency

A 3-node Raspberry Pi cluster costs approximately $200-300 complete with power supplies, SD cards, and cases. Compare this to cloud instances or enterprise edge servers that can cost thousands of dollars. For development, testing, and educational purposes, the cost difference is staggering.

Energy Consumption

A Raspberry Pi 4 draws between 3-7 watts under typical load. A complete 3-node cluster might consume 15-20 watts total—less than a single traditional server’s idle power draw. This makes Pi clusters ideal for:

Remote locations with limited power
Solar-powered deployments
24/7 always-on edge nodes
Green computing initiatives

ARM Architecture Relevance

The ARM architecture is increasingly important in edge and IoT devices. By building your cluster on Raspberry Pi, you’re working with the same architecture used in many production edge devices, smart sensors, and industrial IoT equipment. This experience translates directly to real-world edge deployments.

Learning Value

A Raspberry Pi cluster provides hands-on experience with:

Distributed systems concepts
Container orchestration
Network configuration
High availability patterns
Infrastructure as code

Practical Use Cases

IoT Data Processing: Ingest and process sensor data locally
Private Cloud: Run personal services like Nextcloud or Pi-hole
CI/CD Pipeline: Test ARM container builds
Machine Learning Inference: Run lightweight ML models at the edge
Development Environment: Test multi-node applications locally

Hardware Requirements

Before diving into the build, let’s ensure you have the right hardware. Here’s what you’ll need:

Essential Components

Component	Recommended	Minimum	Notes
Raspberry Pi boards	3-4× Pi 4 (4GB or 8GB)	3× Pi 3 B+	Pi 4 has better performance and more RAM
Power supplies	Official USB-C 15W (Pi 4)	2.5A micro-USB (Pi 3)	One per Pi, don’t skimp on quality
MicroSD cards	32GB Class 10/A2	16GB Class 10	A2 rated cards improve I/O performance
Network switch	Gigabit 5-port switch	Gigabit router	Wired networking is essential for stability
Ethernet cables	Cat5e or Cat6	Cat5e	One per Pi, keep them short
Heat sinks/cases	Aluminum case with fan	Basic heat sinks	Pi 4 runs hot under sustained load

Optional but Recommended

USB SSD drives (instead of SD cards) for better durability and performance
UPS/battery backup for uninterrupted operation
Rack mount or cluster case for organized setup
Ethernet cable labels for easy identification
Power distribution board to manage multiple Pi power supplies

Hardware Configuration Tips

RAM matters: Choose 4GB or 8GB Pi 4 models. Kubernetes components and container workloads consume significant memory. The 8GB version gives you headroom for larger applications.
Storage considerations: SD cards are the default choice, but they have limited write endurance. For production-like setups, consider USB-attached SSDs. A 120GB SSD provides better performance and reliability for container workloads.
Network topology: Connect all Pis to the same switch. Avoid Wi-Fi for cluster nodes—wired connections provide lower latency and better reliability for Kubernetes networking.
Cooling is crucial: Under sustained load, Pi 4 processors can throttle. Invest in aluminum heatsink cases or active cooling fans to maintain consistent performance.

Software Requirements

You’ll need specific software versions and tools for a smooth setup. Here’s what to prepare:

Operating System

Raspberry Pi OS Lite (64-bit) — The minimal version without desktop environment
Download from the official Raspberry Pi website
Use Raspberry Pi Imager for easy flashing

Required Software Packages

Component	Version	Purpose
Container Runtime	Docker 24.x or containerd 1.7.x	Runs containers
Kubernetes	v1.28.x or newer	Orchestration platform
kubeadm	Matches Kubernetes version	Cluster bootstrap tool
kubelet	Matches Kubernetes version	Node agent
kubectl	Matches Kubernetes version	CLI for cluster management
crictl	Latest	Container runtime CLI (debugging)

Network Configuration

Static IP addresses for each node (or DHCP reservations)
Hostname configuration for easy identification
DNS resolution working between nodes

ARM Architecture Compatibility

All software must support arm64 architecture. Kubernetes and Docker provide official ARM builds, but you may encounter issues with:

Third-party container images that only support amd64
Some monitoring and logging tools
Certain CNI plugins (we’ll use Flannel for ARM compatibility)

Time Synchronization

Kubernetes requires synchronized clocks across nodes:

Enable NTP (Network Time Protocol) in Raspberry Pi OS
Ensure all nodes use the same time servers

Step 1: Prepare the Raspberry Pi OS

Let’s start building! This step covers flashing the operating system and configuring each Pi for cluster use.

1.1 Flash Raspberry Pi OS Lite

Download Raspberry Pi Imager from the official website
Insert your SD card into your computer
Launch Raspberry Pi Imager
Select your device (Raspberry Pi 4)
Choose OS: Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit)
Select your SD card
Click the gear icon to configure advanced options:
- Enable SSH
- Set hostname (e.g., k8s-master, k8s-worker1)
- Set username/password (default: pi/raspberry)
- Configure Wi-Fi (optional, but use Ethernet for cluster)
- Set locale settings
Click Write and wait for the process to complete

1.2 Initial Boot and Configuration

Insert the SD card into your Pi and power it on. Wait for it to boot, then SSH into it:

ssh pi@<node-ip-address>

The default password is raspberry (unless you changed it during flashing).

1.3 System Updates

Run these commands on each node:

sudo apt update && sudo apt upgrade -y
sudo apt install -y vim git curl wget

1.4 Configure Hostnames

Set a unique hostname for each node:

sudo hostnamectl set-hostname k8s-master   # On master node
sudo hostnamectl set-hostname k8s-worker1  # On worker node 1
sudo hostnamectl set-hostname k8s-worker2  # On worker node 2

1.5 Update /etc/hosts

Add all cluster nodes to the /etc/hosts file on every node:

sudo nano /etc/hosts

Add these lines (replace IPs with your actual addresses):

192.168.1.100   k8s-master
192.168.1.101   k8s-worker1
192.168.1.102   k8s-worker2

1.6 Enable Kernel Modules

Kubernetes requires specific kernel modules:

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

1.7 Configure sysctl Parameters

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

1.8 Disable Swap

Kubernetes requires swap to be disabled:

sudo dphys-swapfile swapoff
sudo dphys-swapfile uninstall
sudo update-rc.d dphys-swapfile remove

Edit /etc/fstab and comment out any swap lines:

sudo nano /etc/fstab
# Comment out any line containing "swap"

1.9 Reboot

sudo reboot

Repeat these steps for all nodes before proceeding to the next step.

Step 2: Install Docker and Kubernetes Tools

With the OS prepared, we’ll install the container runtime and Kubernetes components.

2.1 Install Docker

Run these commands on all nodes:

# Update package index
sudo apt update

# Install prerequisites
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo "deb [arch=arm64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

# Enable and start Docker
sudo systemctl enable docker
sudo systemctl start docker

2.2 Configure Docker for Kubernetes

Kubernetes requires cgroup management. Configure Docker:

cat <<EOF | sudo tee /etc/docker/daemon.json
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m"
  },
  "storage-driver": "overlay2"
}
EOF

sudo systemctl restart docker

2.3 Install Kubernetes Components

Add the Kubernetes repository and install tools:

# Add Kubernetes apt repository
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list

# Install kubeadm, kubelet, and kubectl
sudo apt update
sudo apt install -y kubelet kubeadm kubectl

# Hold their versions to prevent accidental updates
sudo apt-mark hold kubelet kubeadm kubectl

2.4 Verify Installation

Check that all tools are installed:

kubeadm version
kubelet --version
kubectl version --client
docker --version

2.5 Configure containerd (if using containerd instead of Docker)

If you prefer containerd, configure it for Kubernetes:

sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# Edit config to enable SystemdCgroup
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

sudo systemctl restart containerd

Repeat these installation steps on all nodes.

Step 3: Initialize the Kubernetes Cluster

Now we’ll initialize the master node and set up the control plane.

3.1 Initialize on the Master Node

SSH into your master node and run:

sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=<master-node-ip>

Parameters explained:

--pod-network-cidr: CIDR for pod network (10.244.0.0/16 is required for Flannel)
--apiserver-advertise-address: The IP address of your master node

3.2 Configure kubectl

Set up kubectl for your user:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

3.3 Save the Join Command

The kubeadm init output includes a join command. Save this carefully—you’ll need it for worker nodes:

kubeadm join 192.168.1.100:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

If you lose it, regenerate with:

kubeadm token create --print-join-command

3.4 Install a Pod Network

For ARM-compatible networking, we’ll use Flannel:

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

3.5 Verify Control Plane

Check that the control plane components are running:

kubectl get pods -n kube-system

Wait for all pods to be in Running state:

kubectl wait --namespace kube-system --for=condition=Ready pods --all --timeout=300s

3.6 Check Node Status

kubectl get nodes

The master node should show Ready status.

Step 4: Join Worker Nodes

With the control plane running, let’s add worker nodes to the cluster.

4.1 Prepare Worker Nodes

Ensure each worker node is:

Running the same OS and software versions
Configured with proper hostnames and network settings
Has SSH access enabled

4.2 Execute Join Command

SSH into each worker node and run the join command you saved earlier:

sudo kubeadm join 192.168.1.100:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

4.3 Verify Node Joining

From the master node, check if workers have joined:

kubectl get nodes

You should see all nodes with Ready status:

NAME          STATUS   ROLES                  AGE     VERSION
k8s-master    Ready    control-plane,master   10m     v1.28.2
k8s-worker1   Ready    <none>                 5m      v1.28.2
k8s-worker2   Ready    <none>                 3m      v1.28.2

4.4 Label Worker Nodes

Add labels for better workload distribution:

kubectl label node k8s-worker1 node-role.kubernetes.io/worker=worker
kubectl label node k8s-worker2 node-role.kubernetes.io/worker=worker

4.5 Test Cluster Functionality

Run a simple test to ensure everything works:

kubectl run test-pod --image=nginx:arm64 --port=80
kubectl get pods -o wide

If the pod runs successfully, your cluster is functional!

Step 5: Deploy an Edge Application

Now let’s deploy a real edge application to demonstrate the cluster’s capabilities. We’ll create a simple IoT data processing service.

5.1 Create a Deployment

Create a file named edge-app.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: edge-processor
  labels:
    app: edge-processor
spec:
  replicas: 3
  selector:
    matchLabels:
      app: edge-processor
  template:
    metadata:
      labels:
        app: edge-processor
    spec:
      containers:
      - name: processor
        image: arm64v8/python:3.9-slim
        command: ["/bin/sh"]
        args: ["-c", "while true; do echo 'Processing edge data...' $(date); sleep 5; done"]
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "128Mi"
            cpu: "250m"
      nodeSelector:
        kubernetes.io/arch: arm64

5.2 Deploy the Application

kubectl apply -f edge-app.yaml

5.3 Create a Service

Add a service to expose the application:

apiVersion: v1
kind: Service
metadata:
  name: edge-processor-service
spec:
  selector:
    app: edge-processor
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

Save as edge-service.yaml and apply:

kubectl apply -f edge-service.yaml

5.4 Verify Deployment

# Check pods
kubectl get pods -o wide

# Check services
kubectl get services

# View logs
kubectl logs deployment/edge-processor

5.5 Scale the Application

Demonstrate Kubernetes scaling:

kubectl scale deployment edge-processor --replicas=5
kubectl get pods

Watch as Kubernetes distributes the new pods across your cluster nodes.

Best Practices for Edge Kubernetes

Optimize your Raspberry Pi cluster for edge computing with these best practices:

Resource Management

Practice	Implementation	Benefit
Resource limits	Set CPU/memory requests and limits	Prevents resource hogging
Pod anti-affinity	Spread pods across nodes	Improves fault tolerance
Horizontal scaling	Use HPA for auto-scaling	Handles variable workloads
Node taints	Mark nodes for specific workloads	Controls pod placement

Image Optimization

Use ARM-specific images (check for arm64v8 tags)
Keep images small — use Alpine or slim variants
Multi-stage builds to reduce final image size
ImagePullPolicy: IfNotPresent to reduce network usage

Storage Considerations

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: edge-data
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: local-path

Monitoring and Observability

Deploy Prometheus and Grafana for metrics
Use kubectl top for quick resource checks
Implement centralized logging with Loki
Set up alerting for node failures

Security Hardening

Keep all systems updated
Use private container registry
Implement RBAC for access control
Enable network policies
Rotate certificates regularly

Performance Tuning

Use SSDs instead of SD cards
Enable cgroup memory limits
Configure CPU governor to performance mode
Monitor thermal throttling

Troubleshooting Common Issues

Here are solutions to the most frequent problems you might encounter:

Node Not Ready

Symptoms: Node shows NotReady status

Solutions:

# Check kubelet status
sudo systemctl status kubelet

# View kubelet logs
sudo journalctl -u kubelet -f

# Check container runtime
sudo systemctl status docker

# Restart kubelet
sudo systemctl restart kubelet

Pods Stuck in Pending

Symptoms: Pods never schedule to nodes

Solutions:

# Check for taints
kubectl describe nodes | grep -i taint

# Check node resources
kubectl describe node <node-name>

# View pod events
kubectl describe pod <pod-name>

Network Issues

Symptoms: Pods can’t communicate

Solutions:

# Verify CNI plugin
kubectl get pods -n kube-system

# Check Flannel logs
kubectl logs -n kube-system -l app=flannel

# Test pod connectivity
kubectl exec <pod-name> -- ping <other-pod-ip>

Memory Issues

Symptoms: OOM kills, slow performance

Solutions:

# Check memory usage
free -h

# View cgroup limits
cat /sys/fs/cgroup/memory/memory.limit_in_bytes

# Increase swap (not recommended for production)
sudo dphys-swapfile swapoff && sudo nano /etc/dphys-swapfile

Certificate Expiry

Symptoms: API server access failures

Solutions:

# Check certificate expiry
kubeadm certs check-expiration

# Renew certificates
sudo kubeadm certs renew all

# Restart control plane
sudo systemctl restart kubelet

ARM Compatibility Issues

Symptoms: Image pull failures

Solutions:

# Check image architecture
docker manifest inspect <image-name>

# Use multi-arch images
# Manually specify arm64 tag
kubectl set image deployment/edge-processor processor=arm64v8/python:3.9-slim

Conclusion

You’ve successfully built a Kubernetes cluster on Raspberry Pi for edge computing! This achievement puts you at the intersection of two transformative technologies: container orchestration and edge computing. Your cluster is now a functional platform for developing and testing edge applications, learning Kubernetes concepts, and experimenting with distributed systems.

What You’ve Accomplished

Hardware setup: Configured multiple Raspberry Pi nodes with proper cooling, storage, and networking
OS preparation: Installed and optimized Raspberry Pi OS Lite for Kubernetes
Software installation: Set up Docker and Kubernetes tools across all nodes
Cluster initialization: Created a functional control plane with kubeadm
Node joining: Added worker nodes and verified cluster health
Application deployment: Deployed and scaled a sample edge application

Next Steps

To deepen your Kubernetes and edge computing skills:

Deploy real edge workloads — Try running Node-RED, MQTT brokers, or TensorFlow Lite
Implement monitoring — Set up Prometheus and Grafana for cluster observability
Explore service mesh — Install Linkerd or Istio for advanced networking
Add CI/CD — Set up GitLab Runner or GitHub Actions for automated deployments
Try k3s — Experiment with the lightweight Kubernetes distribution optimized for edge
Implement GitOps — Use ArgoCD or Flux for declarative cluster management

Final Thoughts

Your Raspberry Pi Kubernetes cluster is more than a learning toy—it’s a stepping stone to understanding how modern distributed systems operate. The principles you’ve learned apply directly to cloud-native development, edge computing deployments, and infrastructure automation at any scale.

Remember that edge computing is about bringing computation closer to where data is generated. Your cluster now has that capability, whether you use it for personal projects, educational purposes, or as a prototype for production edge deployments.

Keep experimenting, keep learning, and enjoy your journey into the world of edge Kubernetes!

FAQ

What is the minimum number of Raspberry Pi nodes needed for a Kubernetes cluster?

You can start with a single node, but for a proper cluster, at least 3 nodes are recommended (1 master, 2 workers) to test high availability and load balancing. A single node can run Kubernetes for learning purposes, but you won’t experience the true benefits of distributed orchestration. With 3 nodes, you can demonstrate pod scheduling across multiple machines, test node failures, and implement basic high availability.

Which Raspberry Pi model is best for a Kubernetes cluster?

Raspberry Pi 4 (4GB or 8GB RAM) is recommended for better performance. The 4GB version handles most workloads comfortably, while the 8GB version provides headroom for memory-intensive applications. Older models like Pi 3 B+ can work but may have limited resources—the 1GB RAM limitation makes them suitable only for very lightweight clusters or specialized roles like worker nodes running minimal containers.

Can I use Raspberry Pi OS Lite for the cluster?

Yes, Raspberry Pi OS Lite (64-bit) is ideal because it has a minimal footprint, leaving more resources for Kubernetes workloads. The Lite version has no desktop environment, reducing memory usage by hundreds of megabytes. The 64-bit version is strongly recommended because it allows containers to access the full ARM64 instruction set and is better supported by modern container images.

How do I enable SSH on Raspberry Pi for remote management?

You can enable SSH by creating an empty file named ‘ssh’ in the boot partition of the SD card, or by using raspi-config after boot. The file method is easiest during initial setup—just create an empty file called ssh (no extension) in the root of the boot partition. Alternatively, boot the Pi with a monitor and keyboard, then run sudo raspi-config → Interface Options → SSH → Enable.

What is the role of kubeadm in setting up the cluster?

kubeadm is a tool that simplifies the process of initializing a Kubernetes cluster and joining nodes. It handles the bootstrap process and generates necessary certificates. Specifically, kubeadm performs these critical functions: initializes the control plane components (API server, etcd, controller manager, scheduler), generates and distributes certificates, configures kubelet for each node, and provides a secure join mechanism for adding worker nodes.

How can I ensure my cluster is suitable for edge computing?

Optimize for low power consumption, use lightweight container images, and consider using k3s (a lightweight Kubernetes distribution) for better performance on resource-constrained devices. Additionally, implement resource limits on all pods, use efficient storage solutions (SSDs over SD cards), enable monitoring to track resource usage, and design your applications to work within the constraints of edge devices. For production edge deployments, k3s reduces memory usage by up to 50% compared to standard Kubernetes.

What are common issues when building a cluster on Raspberry Pi?

Common issues include network configuration problems, insufficient memory, and compatibility issues with ARM architecture. Ensure you use ARM-compatible container images and check your network settings. Specifically, watch out for: DHCP IP changes (use static IPs), firewall rules blocking Kubernetes ports, swap not being fully disabled, cgroup configuration mismatches, and outdated firmware. Most issues can be resolved by checking system logs (journalctl -u kubelet) and verifying that all nodes have consistent software versions.