Install Kubernetes on Raspberry Pi OS

We will use k3s, a lightweight Kubernetes distribution, to get the most out of our hardware. This tutorial uses a Raspberry Pi 4 and the latest Raspberry Pi OS 32-bit (formerly known as Raspbian). The 64-bit version is pretty much the same for these steps.

Flash the OS image on your SD card and, if necessary, add Wi-Fi credentials so you can access it.

Enable cgroups support and disable IPv6 by appending the following to /boot/cmdline.txt (remember that /boot refers to the boot partition on your SD card).

cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory ipv6.disable=1

I also recommend disabling swap.

dphys-swapfile swapoff && systemctl disable dphys-swapfile.service

If your workloads don’t require GPU, you may want to change the Memory Split to 16 using raspi-config. You’ll have a little extra RAM this way.

You can force the OS to use legacy iptables to ensure compatibility with older Kubernetes versions, but this step is optional.

iptables -F
update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

Install and test k3s.

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable=traefik" sh -

# After a minute, you should be able to test it
kubectl get nodes

The kubeconfig YAML will be available at /etc/rancher/k3s/k3s.yaml.

If you have worker nodes to add, use the following command. Find the cluster token at /var/lib/rancher/k3s/server/node-token on the server node.

curl -sfL https://get.k3s.io | K3S_URL=https://<server_ip>:6443 K3S_TOKEN="<cluster_token>" sh -

Maintenance

Things should run smoothly from here, but if they don’t, the next few commands might help:

# See current status of k3s
systemctl status k3s

# See system logs (including k3s)
journalctl -xe

# Uninstall k3s
/usr/local/bin/k3s-uninstall.sh

Kubernetes automatically performs cleanup of unused containers and images on nodes. Still, if you feel your filesystem is getting bloated by them, you can force a safe deletion with:

k3s crictl rmi --prune

Further reading

Configuration options for k3s