Setting up a Raspberry Pi cluster

Let’s build a Raspberry Pi cluster with Kubernetes (or actually a Kubernetes implementation) step by step.

Hardware requirements

We need multiple Raspberry Pi. I have chosen for the Raspberry Pi 3B+. This is not the most recent version, but it will do. A Pi needs

  • power, so I decided to connect them to a USB power charger containing 6 ports which fits on the cluster,
  • an Operating System on a memory SD card,
  • a switch connecting them and fits on the cluster,
  • and the cluster case which should look like the one from the James Bond movie “Skyfall”. So a transparent cluster supporting the selected Pi model.

My cluster contains four Raspberry Pi with the following hardware shopping list.

  • 4 x Raspberry Pi 3B+
  • 1x power supply: Anker 60W 6-Port PowerPort USB Charger (white)
  • 4 x Anker 1ft / 0.3m PowerLine USB 2 to micro USB cable (white)
  • 4 x UTP cat5 cable 1ft / 0.3m (white)
  • 2 x ModMyPi stackable Raspberry Pi case (transparant)
  • 4 x 16 or 32 GB micro SD-card class 10
  • D-Link Switch GO-SW-8E 8-Port

Now that we got the parts, prepare for assembling. We need a screwdriver, double sided tape for power bank, hardware to flash an OS on the memory SD card.

Hardware alternatives

Instead of a USB charger with multiple ports, you can also choose a power HAT for the Raspberry Pi.

The Raspberry Pi Power over Ethernet HAT is a small accessory for the Raspberry Pi computer which allows you to power your Raspberry Pi using Power over Ethernet–enabled networks

There are newer cluster cases which includes fans.

Configure the cluster Pi by Pi, so each Pi will have it’s own host name. First download OS and flash OS on the memory SD card.We will configure each Pi with the command line as much as possible, just for fun.

Optional steps

We will use wget for this. On MacOs this is not available by default, so let’s install wget first (assuming HomeBrew is already installed).

No HomeBrew?

Now install wget for MacOS

Download OS

Now download Raspbian Lite. We will use this OS for the Pi. You can download it using the browser from

of use the command line.

You will see something like

We will flash the file 2020–02–13-raspbian-buster-lite.img to the memory SD card.

Flash OS to disk

Determine SD card device. On MacOS we use the tool diskutil.

This will show all disks on your machine. The SD card will most likely NOT be /dev/disk0 or /dev/disk1. Show below is a possible output for /dev/disk2

Unmount and flash OS using CLI

Now flash OS to the memory card. We will use as output the raw device /dev/rdisk2, as this will be faster.

Enable SSH

SSH is disabled by default on the Pi. As I want to use the command line, we need to enable SSH here, so we can access the Pi from the Mac without a screen directly attached to the Pi. We will use the command line with SSH to access the Pi. Now start enabling SSH.

Locate SD card boot volume first

This should show the boot partition as Volume on MacOS.

Now enable ssh on the Pi by adding an empty file named “ssh” on the boot partition of the SD card. When the Pi will boot with this SD card, SSH will be enabled

SSH will be enabled now. The SD card is ready. Now eject the SD card.

Remove the SD card from your Mac.

Put the SD card in the Pi. Attach network cable of the Pi to the switch, switch the router, USB cable to the power bank, et cetera.

We will configure each Pi separately so we know which Pi has which host name (and IP address).

Configure the Pi

We should be able to access the Pi from the MacOS when it is attached to the cluster and the cluster is connected to the same network as the Mac.

IP address

But what is the IP address of the Pi in the cluster and in the network? Handy tool is nmap, available on Linux. But we are working now on MacOS. Install nmap using homebrew (or sdkman).

Now scan the network. Check the IP address of your router

In the next examples I will use the following IP address as example:

This might gave the following output:

So the IP address of the router is

Now scan the network using the IP address of the router.

In the output, find the IP address and name of the Raspberry Pi.

As you can see the hostname of the Raspberry Pi is “raspberrypi”. This will be the hostname for each Pi in the network if we don’t change it. We will change it later on the command line. First access the Pi.

As we have enabled SSH, let’s access the Pi using the network. Using the command line. We can either use the name of the Pi or the IP address.

using the name “raspberrypi” it would be:

or using the IP address

The default password is raspberry.

We are in using SSH.

Login using ssh key (Optional)

If you have a ssh key, you can log into the Pi with your key after you copy the ssh key to the Pi. From the MacOS command line you can use the command ssh-copy-id

The name of the Pi is now rpimaster or rpinode<x>.

Next time you log into the Pi use command

BUT the password is now the password of the ssh key (assuming it is password protected).

Configure Pi hostname

Now verify and change the name of our Pi, so each Pi will have it’s own unique hostname within the network.

will show the output

Now change hostname

Change the name to

  • rpimaster for the first Pi. We will use this as the master for Kubernetes.
  • rpinode1, rpinode2, et cetera for the next Pi

We will change also file /etc/hosts


change to

Kubernetes for the Pi cluster

Besides the enterprise Kubernetes, also known as K8S, there are also other distributions. We will use k3s, “the certified Kubernetes distribution built for IoT & Edge computing”, for the Pi cluster. We will install k3s separately on each Pi, one being the master node.

Installing k3s on master

Switch to root for now. On the (master) Pi

Enabled Linux control groups

We need to setup Linux Control Groups so we can use resource monitoring and enables isolation that are needed by Kubernetes or an Kubernetes implementation like k3s.

Edit /boot/cmdline.txt and add the following line to the end of the file.

Starting installation on the master node

Wow, that was easy. Verify k3s, for example get the node.

Now determine the token of the master, we need it for the worker nodes.

This will output something like the following (not showing the real key):

Install k3s on worker node

Now we will prepare and configure the worker node Pi almost the same as the master node. Only the hostname is rpinode<x> instead of rpimaster

ssh into the worker node (first node is named rpinode1), like the following:

You will see at least the following message

The pi is connected on switch, so we leave Wi-Fi for now. Prepare for installation k3s on the worker node.

Technical Workout!!

Due to the following issue, we will use the IP address of the master.

We need to have the IP address of the master node:

Now export some variables which are need by k3s. The variable K3S_URL is used to point to the master. Also we need a token.

Install k3s on worker node, like we did on the master node.

This will show that the agent is installed and starting

You can verify the status

if you see that the k3s-agent gives errors concerning the CA (certificates)

then you can alter the config.

edit the K3S_URL and use the IP address of the master instead of the hostname.

Restart the agent and check again.

Now the errors related to the certificates should be gone. At least this node worker can join. Repeat this for rpinode2 and rpinode3 as well.

Verify cluster

We have made sure that at least one Pi, rpinode1, could join. Let’s verify on the master node

Giving the following output:

You can see that we still use containerd instead of Docker. We leave it for now and deploy a hello world app.

Choose correct container image

For deployment we can use a hello world application in a container. Choose one for the correct architecture.

We need to make sure that the container matches the architecture. An image for X86_64 will not run on a ARM.

First time I deployed a hello-world application for a AMD64 architecture. Finally the container crashed with the following message:

Deploy pod

As one of my references is the blog of, we will take the hello world app from that blog. See

The service YAML ,with name openfaas-figlet-svc.yaml, should look like this:

and the deployment of the service, with name openfaas-figlet-dep.yaml, like the following.

Notice that the image name is functions/figlet:latest-armhf. It supports ARM and so the container made from that image can run on a Raspberry Pi.

Deploy Pod

verify the rollout of the deployment

Now we can list the pods

The openfaas-figlet pod, with name openfaas-figlet-5c5887f45–4s92c, has status Running. The pods with the wrong container image architecture show status CrashLoopBackOff. When we check pod with command

we can see that the status is Running and the Raspberry Pi is rpinode1:


We have setup our cluster and verified that deploying a pod is working. Be aware that if you want to shutdown the cluster you need to gracefully shutdown the individual Raspberry Pi.

SSH into the Pi. Example shows only node1.

Now shutdown the Pi with option halt and power

We are done for now.

My references

I used the following references for setting up the cluster and could not have done it with them.

Software Developer — Loves Scala and Rust.