Cover image for How to set up a Raspberry Pi K3s cluster

How to set up a Raspberry Pi K3s cluster

bassonrichard profile image Richard Basson ・5 min read

The why

Why would you use K3s on a Raspberry Pi and not plain Kubernetes? The short answer is that Kubernetes was not developed with your small Raspberry Pi processor and memory in mind.

The longer answer is that K3s has everything you need for your Raspberry Pi from Kubernetes. It was developed for small servers without all of the unnecessary extras that Kubernetes has. This allows the memory footprint to be smaller on your Raspberry Pi and uses less than 40mb of space on your SD card so no wasting space.

So now that you know the why, let’s get started!

What you need to get started.

  • (2+) x Raspberry Pi (please note raspberry pi zero won’t work with K3s)

  • USB cable/charger (make sure it can support 3A output if you don’t use the
    official charger)

  • Fly leads — as many as you have raspberry pi’s

  • Micro SD cards — preferably class 10. Here are more tips on how to choose a micro SD card

  • Network Switch (or router with open ports)

Nice to haves

Case(s) for the raspberry pi(s) with fans to keep the raspberry pi(s) cool
A USB hub with 3A output for all ports
Micro SD card reader

Now you need to setup Raspbian OS on the Raspberry Pi.

Raspberry Pi imager interface

  • Download the latest version of Raspberry Pi Imager and install

  • Connect an SD card reader with the SD card inside.

  • If you used the card for another project you will first need to
    clean the micro SD card by using the erase option on the
    Raspberry Pi Imager.

  • Open Raspberry Pi Imager and choose the Raspbian lite from the
    list presented.

  • Choose the SD card you wish to write your image to.

  • Review your selections and click ‘WRITE’ to begin writing data
    to the SD card.

You can find the official guide here

When you are done writing to the SD card, add a file named SSH to the card in the root folder (boot). The file does not have to contain anything, it can just be a plain text file.

Now to boot up your Pi’s.

When you finally finish writing the image to the SD card, plug in your SD card. You can plug in the fly lead and the USB-C cable and power the Pi(s) up!

Image of Raspberry Pi with cabels plugged in

The default setup of the Raspberry Pi.

When you connect for the first time you can use the following command to access the Raspberry Pi:

ssh pi@raspberrypi.local

It will then prompt you for a password which by default is: raspberry

When you’re done with that you should be in and ready to set up some defaults. First, let’s change the default password. Use the following command to access the Raspberry Pi config:

sudo raspi-config

Image of Raspberry pi config interface

Change the password to a secure password that you can access again. If you struggle to think of a password you can use the following tool to generate one:

Please keep this password safe as you will need it to be able to access the Pi again.

Once you’ve changed the password a good next step would be to change the hostname of the Raspberry Pi. You can get to the hostname by choosing network options on the main raspberry pi config menu then choosing the hostname. I like to change the hostname to pi0 for the master node and then the worker nodes pi1, pi2 etc…(or Blueberry Pi, Pecan Pi, Lemon Meringue Pi).

Getting to the clustering

You will need to start by enabling container feature. You can do this by exiting the /boot/cmdline.txt file by using your favorite editor: I prefer to use nano.

Run the following command to edit this file:

sudo nano /boot/cmdline.txt

Then append the following to the top line of the file:

cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory

Then save it to the file and reboot your Raspberry Pi by running

sudo reboot

Repeat the above on all of your Raspberry Pi’s

On your master node:

SSH back into the Raspberry Pi. You will need to download the latest version of K3s by using the following command on the Raspberry Pi :

curl -sfL https://get.k3s.io | sh -

You can run the following command to see if K3s started up correctly

sudo systemctl status k3s

If all went well you will see your master node up and running when you run the following command:

sudo k3s kubectl get nodes

Do the following on your worker nodes

You will first need to run the following command to get the K3s server token so that you can later use it to register the worker nodes. Once you have the token, keep it safe so you can use it later. If you lose the token you can always run the command again on the master node to get the token again.

sudo cat /var/lib/rancher/k3s/server/node-token

You will need to replace ‘myserver’ with the IP of your master node and xxx after K3s_TOKEN to the token on your master node which you can obtain by running on your master node.

sudo curl -sfL https://get.k3s.io | K3S_URL=”https://myserver:6443” K3S_TOKEN=XXX sh -

When you’re done doing that on all your worker nodes you can run the below command on your master node again to get all the nodes.

sudo k3s kubectl get nodes

Powershell interface showing kubernetes nodes

K3s comes standard with containerd and not Docker to save space. If you want to use Docker you can install it by running the following command on your Raspberry Pi’s.

curl -sSL https://get.docker.com | sh

Then run the following command so you don’t have to run docker as sudo:

sudo usermod -aG docker pi

If you want to find out more about docker I wrote an article you can find here

There you have it, you’re done setting up your K3s cluster!!!

Feel free to let me know how it goes, you are welcome to dm me on twitter if you get stuck somewhere @bassonrichard.

Resources for some further reading:


Editor guide