Installing K3s on the Raspberry Pi 5: A Step-by-Step Guide

by PicoCluster LLC November 23, 2024

The Raspberry Pi 5 is a powerhouse in the single-board computer world, making it an excellent choice for running lightweight Kubernetes distributions like K3s. Whether you’re building a home lab or setting up an edge computing cluster, K3s provides a simple and efficient way to manage containerized workloads.

In this guide, we’ll walk you through the process of installing K3s on a Raspberry Pi 5 running Raspberry Pi OS.

Be sure and check all of out Raspberry PI 5 and other desktop clusters at http://www.picocluster.com

Prerequisites

Before we dive in, ensure you have the following:

Hardware:

A Raspberry Pi 5 with a minimum of 4GB of RAM (8GB recommended for larger workloads).
A high-quality microSD card (32GB or larger recommended) or SSD via USB for booting.
A stable power supply and network connection.

Software:

Raspberry Pi OS (64-bit recommended), installed and updated.
SSH access or direct terminal access to the Raspberry Pi.

Tools:

Basic familiarity with Linux commands.
Access to the terminal or SSH client on your PC.

Step 1: Update and Prepare Your Raspberry Pi 5

Start by updating the system to ensure all packages are up-to-date.
bash
```
sudo apt install -y curl wget
```
Next, install essential tools like curl and wget (if not already installed):
bash
```
sudo apt install -y curl wget
```
Set up the Raspberry Pi to allow cgroup support, which is required for Kubernetes. Edit the cmdline.txt file:
bash
```
sudo nano /boot/cmdline.txt/span>
```
Add the following to the end of the line (ensure all parameters are on the same line):
bash
```
cgroup_memory=1 cgroup_enable=memory
```
Save the file and reboot the Raspberry Pi:
bash
```
sudo reboot
```

Step 2: Install K3s

Once your Pi is prepared, install K3s using the official installation script.

Download and run the installation script:
bash
```
curl -sfL https://get.k3s.io | sh -
```
By default, this will install K3s as a server (control plane) and create a single-node Kubernetes cluster.
Verify the installation:
After the installation completes, check the status of the K3s service:
bash
```
sudo systemctl status k3s
```
If the service is active and running, you’re good to go!

Step 3: Configure K3s

Test the Kubernetes cluster:
K3s installs kubectl by default. Check the cluster nodes and pods:
bash
```
sudo kubectl get nodes
```
You should see your Raspberry Pi listed as a single node in the Ready state.
Add a node to your cluster (Optional):
If you want to add another Raspberry Pi as a worker node, grab the node token from the server:
bash
```
sudo cat /var/lib/rancher/k3s/server/node-token
```
Run the following command on the worker node, replacing and with the appropriate values:
bash
```
curl -sfL https://get.k3s.io | K3S_URL=https://:6443 K3S_TOKEN= sh -
```

Step 4: Deploy Applications

Now that your cluster is running, you can deploy your containerized applications. For example, deploy a simple Nginx pod:
bash
```
curl -sfL https://get.k3s.io | K3S_URL=https://:6443 K3S_TOKEN= sh -
```

Check the service to find the NodePort and access Nginx from your browser:

bash

kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --type=NodePort --port=80

Visit http://:

Step 5: (Optional) Advanced Configuration

For advanced use cases, consider the following:

Persistent storage: Use an external SSD or configure network storage (e.g., NFS).
Ingress controller: Install an ingress controller like Traefik (default for K3s) to manage HTTP and HTTPS traffic.
Monitoring: Deploy Prometheus and Grafana for cluster monitoring.

Troubleshooting Tips

K3s service fails to start:
- Ensure cgroup settings are correctly applied.
- Check logs using:
bash
```
sudo journalctl -u k3s
```
Insufficient resources:
- Limit pod resource usage with resourceRequests and resourceLimits in your pod specs.
- Use Raspberry Pi 5 with at least 8GB of RAM for resource-heavy workloads.

Conclusion

With K3s running on your Raspberry Pi 5, you have a powerful, lightweight Kubernetes cluster at your fingertips. Whether you’re exploring Kubernetes for the first time or building a compact edge computing solution, the Raspberry Pi 5 provides a perfect platform to get started.