For a while now, I’ve been running my home automation services on a Raspberry Pi. I started, like many, with a simple Docker Compose setup. It was easy to get going and served its purpose well. However, as my setup grew, I found myself wanting a more robust and scalable platform. This led me to explore Kubernetes, and specifically K3s, a lightweight distribution perfect for resource-constrained environments like the Raspberry Pi.

In a previous post, I detailed how to deploy Home Assistant on an existing Kubernetes cluster. Now, it’s time to cover the foundational step: installing that single-node K3s cluster on a Raspberry Pi 5.

Why K3s over Docker Compose?

Docker Compose is fantastic for its simplicity. A single docker-compose.yml file can define and run a multi-container application. It’s declarative and easy to understand. For a small number of services, it’s often the quickest way to get started.

However, as you add more services, you might start to miss features that Kubernetes offers out-of-the-box:

  • Declarative API: While both are declarative, Kubernetes provides a powerful API for managing the entire lifecycle of your applications, from deployments and networking to storage.
  • Self-Healing: Kubernetes can automatically restart containers that fail, ensuring your services are always running.
  • Scalability: While not a primary concern for a single-node home cluster, Kubernetes is designed for scaling. If you ever decide to add more nodes, the transition is seamless.
  • Networking: Kubernetes has a more advanced networking model, providing features like Services for stable endpoints and Ingress for managing external access.
  • Ecosystem: The Kubernetes ecosystem is vast, with a huge community and countless tools (like Helm for package management) to simplify deployments.

K3s, from Rancher (now part of SUSE), packages all this power into a single binary that’s less than 100MB. It’s optimized for ARM processors and removes non-essential features to keep the footprint minimal, making it ideal for the Raspberry Pi.

Installing K3s on Raspberry Pi 5

The installation process is surprisingly straightforward. The K3s team provides a convenient script that handles everything.

Before you start, ensure you have a fresh installation of a 64-bit OS on your Raspberry Pi 5, like Raspberry Pi OS Lite (64-bit).

  1. SSH into your Raspberry Pi.

  2. Run the installation script:

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

    This one-liner downloads and executes the installation script. It will install the K3s server and an agent on the same machine, creating a fully functional single-node cluster. Since I am not using Traefik Ingress Controller that comes with k3s I disable it by creating the file /etc/rancher/k3s/config.yaml with the following content before running the command above:

    disable:
- traefik

    But feel free to skip this step if you are planning on using Traefik as your ingress controller.

  3. Verify the installation:

    Once the script finishes, you can check if the cluster is running.

    sudo k3s kubectl get nodes

    You should see your Raspberry Pi listed as a node with the Ready status.

    The k3s command automatically uses the correct kubeconfig file, but you might want to access your cluster from your main computer. You can copy the configuration file from your Pi:

    sudo cat /etc/rancher/k3s/k3s.yaml

    Copy the output, save it to a file on your local machine (e.g., ~/.kube/config-rpi), and remember to replace the server IP 127.0.0.1 with your Raspberry Pi’s actual IP address.

What’s Next?

And that’s it! You now have a fully operational Kubernetes cluster running on your Raspberry Pi 5. It comes with the local-path storage provisioner for persistent volumes and the servicelb load balancer, which are perfect for a single-node setup.

From here, you can start deploying applications. A great next step would be to follow my guide on deploying Home Assistant on Kubernetes to see how you can move your existing services over.

While Docker Compose remains a great tool for simple projects, moving to K3s on a Raspberry Pi opens up a world of possibilities for running a resilient and scalable home lab.