K3s is a lightweight version of Kubernetes (K8s) which makes it ideal for running on embedded devices like a Raspberry Pi. This guide explains how to setup a k3s cluster on your Raspberry PI's
- 2 or more Raspberry Pi devices (preferably RPI 4 with at least 2GB memory)
- microSD/SSD flashed with Raspberry Pi OS Lite via Raspberry Pi Imager
- All RPIs connected through ethernet or configured WiFi
- SSH access enabled
Once you've flashed a microSD with the latest Raspberry Pi OS Lite with Raspberry Pi Imager, you have to plug it back in your PC and make some changes to it. Before you can access your RPI remotely, you have to create an empy ssh file in the root of your boot Volume:
touch /Volumes/boot/sshEnable cgroups by appending the following options at the end of /Volumes/boot/cmdline.txt:
cgroup_memory=1 cgroup_enable=memoryIf you're running a 64-bit Raspberry PI (Raspberry Pi 3 or 4), you also need to configure the Raspberry Pi OS to run in 64-bit mode, by adding this to the bottom of /Volumes/boot/config.txt:
arm_64bit=1
cgroups, also known as control groups, are a feature in Linux to allow processes to be managed and monitored. This an essential kernel feature that allows the containerisation features that we require for K3s to work.
Time to put the microSD card in your Raspberry Pi and let it boot. With SSH access enabled, we can connect to the pi via ssh, e.g.: ssh pi@192.168.0.x
The default password is raspberry, but it's good practice to change this right away by running:
passwdChange the default hostname of your Raspberry Pi to a unique string (e.g. worker-01 or master-01). It's important that these hostnames are unique in your local network and you need to remember them when connecting your nodes to the cluster. This needs to be changed in two different places
sudo nano /etc/hostnameChange the default raspberrypi to e.g. worker-01
sudo nano /etc/hostsChange the last value after 127.0.1.1:
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
127.0.1.1 worker-01Optionally, you can also setup Static IPs for your devices.
Update and upgrade to get the latest security updates, and reboot to apply all the changes made:
sudo apt-get update && sudo apt-get upgrade -y
sudo rebootFor k3s we need to setup one of the Raspberry Pi's as a master node and all other Pi's as worker nodes. The master node acts as an orchestrator and schedules all workloads.
We start with configuring one of the Raspberry Pi's as a master node.
Run k3s installer
curl -sfL https://get.k3s.io | sh -Once installed, give it 1 or 2 minutes to successfully configure itself and then run the following command to see if your cluster is setup properly:
$ sudo kubectl get nodes
NAME STATUS ROLES AGE VERSION
master-01 Ready control-plane,master 2m14s v1.22.5+k3s1Once everything looks healthy, save the access token from the master node that the worker nodes can use to connect:
sudo cat /var/lib/rancher/k3s/server/node-tokenFollow the same steps for each worker node up until you've reached the 'Setup master node' section and then run this for each of your worker nodes:
curl -sfL https://get.k3s.io | K3S_NODE_NAME="node01" K3S_URL="https://192.168.1.100:6443" K3S_TOKEN="token from above step" sh -Replace these values to your :
K3S_NODE_NAMEshould match the hostname you gave your worker nodeK3S_URLshould match the internal IP of your master node (or its hostname)K3s_TOKENshould match the token that you've obtained from your master node earlier
Once you've set up all your nodes, run this on any of the nodes to see if everything is setup properly:
pi@master-01:~ $ sudo kubectl get nodes
NAME STATUS ROLES AGE VERSION
master-01 Ready control-plane,master 6h17m v1.22.5+k3s1
rpi-400 Ready <none> 10m v1.22.5+k3s1
rpi2 Ready <none> 17s v1.22.5+k3s1