Step-by-Step Guide: Creating a Kubernetes Cluster on Raspberry Pi 5 with K3s

I recently purchased two new Raspberry Pi 5 boards, and to test out the power of these miniature computers, I decided to explore setting up a Kubernetes cluster on them.

In this article, I will guide you through the process of creating your own Kubernetes cluster on Raspberry Pi 5 using K3s. We'll start from scratch, covering everything from setting up the hardware to fine-tuning the cluster configuration. No matter if you don’t know a lot about Raspberry Pi’s or you're just starting to learn about Kubernetes, you’ll still be able to complete this project!

Why K3s?

Before we begin, let’s discuss why we’re using K3s for our Kubernetes cluster. K3s is a lightweight Kubernetes distribution specifically designed for resource-constrained environments like IoT devices and edge computing. It’s optimized for ARM architectures, making it perfect for Raspberry Pi. K3s offers a simplified installation process, reduced resource requirements, and seamless integration with IoT hardware.

While K3s is an excellent choice for Kubernetes clusters, it’s worth mentioning other alternatives such as Kubeadm. Kubeadm is a popular tool for bootstrapping Kubernetes clusters and is suitable for more traditional deployments on x86 architecture. However, it may not be as well-suited for resource-constrained environments like Raspberry Pi due to its higher resource requirements and complexity.

Requirements

Hardware:

• Two or more Raspberry Pi 5 boards (older boards work as well)
• Stable power supply to each boards
• High-quality microSD cards (16GB or higher)
• Network for interconnecting Raspberry Pi nodes

Software:

• Raspberry Pi OS
• Raspberry Pi Imager (Etcher or similar tools can also work)
• SSH client for remote access

Preparing the Raspberry Pi Nodes

In my case, sourcing for a micro HDMI seemed to be a daunting task to achieve so a headless installation is the ideal route to take. To prepare the Pis an imager is needed. It allows you to enable SSH and connect to a wireless network on installation which is vital for a headless boot.

Step-by-step guide to using Raspberry Pi Imager

With other tools like Etcher and Rufus you will need to manually download and flash the OS onto the microSD cards, however, using the Imager the process becomes more streamlined and user-friendly. Imager allows you to select the OS and it handles downloading the latest version of the selected OS.

Here's a step-by-step guide to using Raspberry Pi Imager:

Visit the official Raspberry Pi website and download the Imager for your operating system (Windows, macOS, or Ubuntu). Once downloaded, follow the installation instructions to install the Imager on your computer.

In the  Imager, you see a list of Pi Devices, kindly select the device you have. This ensures that the Imager downloads the appropriate version of OS tailored to your specific Pi model.

After selecting the device, you'll see a list of available operating systems. Choose "Raspberry Pi OS (other)" from the list. This gives you more OS options such as the Lite version which is ideal for a headless setup.

Insert your microSD card into your computer's card reader. In the Imager, click on "Choose SD Card" and select the microSD card you inserted.

Once you've selected the OS and the microSD card, click on the "Next" button. You’ll be asked to customize the OS. At this point, you'll need to set the Hostname, device name, and password under the General section and enable SSH under the Services section.

After applying the OS customisations, the Imager will download the latest version of OS and write it to the microSD card. This process may take some time depending on your internet connection speed.

After the writing process is complete, safely eject the microSD card from your computer and insert it into your Raspberry Pi's microSD card slot.

Connect your Pi to a power source using a compatible power adapter. The Pi will boot up using the newly flashed microSD card.

Note: It’s important to connect the Pi boards to the same network, either via ethernet cables or Wi-Fi.

Connecting to the Raspberry Pi 5 boards

As indicated in the OS installation steps, ensure SSH is enabled by selecting this option. An alternative would be creating an empty file named SSH (without any file extension) in the boot partition of the microSD card.

Once the Raspberry Pi booted up, identify its IP addresses on the local network using a network scanner, router interface or pinging the Pis by their hostname. In my case it is P1.local

Utilize an SSH client such as PuTTY (for Windows) or Terminal (for macOS/Linux) to establish connections to each using its IP address or hostname.

sudo ssh p1@p1.local

Kindly replace the hostname above with your IP or hostname. You will be prompted to input your password. If you set this during installation please input or if you did not make use of the default password (raspberry).

From the p1 you can also try to ssh into your other Raspberry Pi using a similar command.

sudo ssh p2@p2.local

Assign Static IPs
After confirming the OS installation, the next step would be to assign Static IPs to your Raspberry Pi to avoid IP changes.

There are two methods to accomplish this: router-based assignment or directly configuring IPs on the Raspberry Pis. In this guide, we’ll focus on the latter method, configuring IPs directly on the Raspberry Pi.

This will be done by editing the interface file.

cd /etc/network
sudo nano interfaces

In the interfaces file, you can specify static IP address configurations for your network interfaces. Here’s an example configuration for Wifi (wlan0):

P1

auto wlan0
iface wlan0 inet static
address 192.168.1.101
netmask 255.255.255.0
gateway 192.168.1.254

P2

auto wlan0
iface wlan0 inet static
address 192.168.1.65
netmask 255.255.255.0
gateway 192.168.1.254

In this configuration:

address: This is the static IP address you want to assign to each Raspberry Pi. Replace 192.168.1.101 and 192.168.1.65 with the desired IP addresses for p1 and p2 respectively.

netmask: This is the subnet mask for the network. The value 255.255.255.0 is commonly used for local networks.

gateway: This is the IP address of your router or gateway on the public network. Replace 192.168.1.254 with the IP address of your router.

After making your changes, save the interfaces file and exit the text editor.

Finally, restart the networking service to apply the changes you made to the interfaces file.

 sudo systemctl restart networking

In some systems you will need to make the change in your dhcpcd.conf file.

sudo nano /etc/dhcpcd.conf

Installing Kubernetes on Raspberry Pi 5

Before diving into K3s installation, you need to enable cgroup``s in your Raspberry Pi because standard Raspberry Pi OS installations do not start with it enabled. K3s needs cgroups to start the systemd service.

You enable it by simply appending cgroup_memory=1 cgroup_enable=memory to /boot/firmware/cmdline.txt.

The next step is to install Kubernetes on the master node, to do so, run the following installation command.

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

The installation process may take a few minutes to complete. Wait for the process to finish.

Checking K3s Status
After the installation is complete, you can check the status of the K3s service by running:

 sudo systemctl status k3s

This command will show whether the k3s service is active and running.

Access kubectl:
By default, K3s installs kubectl, the Kubernetes command-line tool, on your Raspberry Pi. You can access kubectl by simply running:

sudo kubectl

This will display the usage instructions for kubectl.

Access K3s Cluster
You can now interact with your K3s cluster. To get information about the cluster nodes, pods, deployments, etc., you can use kubectl commands. For example:

sudo kubectl get nodes

This command will display the nodes in your Kubernetes cluster.

Adding Worker Nodes
After installing the K3s agent on the master node, it’s time to add worker nodes to your Kubernetes cluster. Worker nodes are essential for distributing the workload and scaling your applications.

To add a worker node to your cluster, follow these steps:

Ensure that the Raspberry Pi intended to be a worker node is connected to the same network as the K3s master node.

Execute the provided script on the worker node, specifying the IP address of the master node and the token generated during the master node setup.

sudo curl -sfL https://get.k3s.io | K3S_URL=https://<master_node_ip>:6443 K3S_TOKEN=<your_token> sh -

Replace <master_node_ip with the IP address of your master node and <your_token> with the token generated during the master node setup.

Here’s an example

sudo curl -sfL https://get.k3s.io | K3S_URL=https://192.168.1.101:6443 K3S_TOKEN=K10b56aa01b599ff2f9a421f65a5a5dc188e76c82105470d58e8884b0e84c1273b7::server:8632d1f69d1dfce061fb59e8fb966993 sh -

Wait for the installation process to complete. The worker node will automatically join the Kubernetes cluster managed by the master node.

To confirm that the worker node has been successfully added to the cluster, you can run the following command on the master node:

sudo kubectl get nodes

This command will display a list of all nodes in the Kubernetes cluster, including both the master and worker nodes. If the worker node appears in the list, it has been successfully added to the cluster.

Conclusion

This step-by-step guide has equipped you with the knowledge and tools necessary to set up your own Kubernetes cluster on Raspberry Pi devices using K3s. We started from the hardware requirements and walked through the entire process, from preparing the Raspberry Pi nodes to configuring static IPs, installing K3s, and adding worker nodes to the cluster.

By following these instructions, you've successfully established a Kubernetes environment that can be utilized for deploying and managing containerized applications on a Raspberry PI. To learn more about Kubernetes on Raspberry Pi, check out the following resources:

• Implementation of a Prototype Kubernetes-Based Cluster for Scalable Web-Based WordPress Deployment using K3s on Raspberry Pis
• Building a four node Raspberry Pi Kubernetes Cluster