The implementation of container orchestration on ARM-based single-board computers represents a significant shift for developers seeking low-power, high-efficiency edge computing environments. Deploying Rancher-based solutions on the Raspberry Pi platform allows for the creation of localized Kubernetes clusters that mirror production-grade infrastructure while operating on a fraction of the energy and hardware cost. This architectural approach spans from the specialized, immutable RancherOS—designed specifically to run Docker containers—to the lightweight K3s distribution, which optimizes the Kubernetes binary for resource-constrained environments like the Raspberry Pi 5. Understanding the nuances of this deployment requires a deep dive into partition management, networking configurations, and the specific interplay between the control plane and worker nodes.

RancherOS Implementation on Raspberry Pi

RancherOS provides a specialized environment where the operating system itself is treated as a container. For the Raspberry Pi, specific image releases became available starting with version v0.5.0. These images are designed to strip away the overhead of a traditional Linux distribution, leaving only the essential components required to host Docker containers.

The installation process for RancherOS on a Raspberry Pi differs fundamentally from standard cloud deployments. In a traditional cloud environment, a cloud-config file is passed during the initial boot to handle networking, user creation, and initial package installation. However, when flashing RancherOS to a microSD card for a Raspberry Pi, there is no mechanism to pass in a cloud-config during the initial flashing phase.

This limitation creates a specific operational workflow for the administrator. The device must first be booted up with the default image. Once the system is live, the administrator must manually modify the configuration to suit the local network and application requirements. After these changes are committed, a full system reboot is mandatory to apply the updated configuration across the immutable layers of the OS.

It is important to note that the standard ros install command, which is typically used in other RancherOS deployments to initialize the system, is not necessary when the OS has been installed directly to an SD card.

Hardware Compatibility and Versioning

Hardware support for RancherOS has historically been conservative to ensure stability. While the ARM ecosystem is vast, the official testing and verification process has focused on specific iterations of the hardware.

For official RancherOS releases, the Raspberry Pi 3 is the only model that has been explicitly tested and is known to work reliably. This ensures that the kernel and drivers provided in the image are compatible with the SoC and peripherals of that specific board.

In contrast, more modern implementations utilizing K3s and Ubuntu Server have expanded the horizon to include the Raspberry Pi 5. The Raspberry Pi 5 offers significantly higher compute power and I/O throughput, making it a superior choice for the control plane of a cluster. For these advanced setups, the requirement shifts toward using 64-bit operating systems to fully leverage the ARM64 architecture.

Storage Optimization and Partition Expansion

A critical limitation of the initial RancherOS installation is its handling of the microSD card's capacity. RancherOS does not automatically expand the root partition to occupy the remaining space on the SD card. If left unaddressed, the system will only utilize a small fraction of the available storage, leading to rapid disk exhaustion as Docker images and container logs accumulate.

To resolve this, a manual workaround is required to create a secondary partition specifically for Docker storage. This process involves repartitioning the disk and reconfiguring the Docker root directory.

The following sequence outlines the technical execution for expanding storage:

1. Access the disk partition table using sudo fdisk /dev/mmcblk0.
2. Create a new partition by selecting n and pressing Enter four times to accept all default values.
3. Write the changes to the disk and exit using w.
4. Perform a system reboot with sudo reboot to ensure the kernel recognizes the new partition table.
5. Create a dedicated mount point for Docker by running sudo mkdir /mnt/docker.
6. Inform RancherOS to use this new path for Docker by executing sudo ros config set rancher.docker.extra_args [-g,/mnt/docker].
7. Format the newly created partition to the ext4 filesystem using sudo mkfs.ext4 /dev/mmcblk0p3.
8. Ensure the mount persists across reboots by configuring the mount points via sudo ros config set mounts "[['/dev/mmcblk0p3','/mnt/docker','ext4','']]".
9. Mount the partition immediately with sudo mount /dev/mmcblk0p3 /mnt/docker.
10. Restart the Docker service to initialize the new root using sudo system-docker restart docker.

For users who are not performing a fresh installation, existing data must be migrated to prevent loss of containers. This is achieved by recursively copying the existing Docker root directory to the new mount point using sudo cp -R /var/lib/docker/* /mnt/docker, followed by a final restart of the Docker service.

Network Configuration and Wi-Fi Management

Connectivity is the backbone of any Kubernetes cluster. While Ethernet is preferred for stability, RancherOS supports Wi-Fi configurations, which became more streamlined as of version v1.5.2.

There are two primary methods for establishing a wireless connection on a Raspberry Pi running RancherOS.

The first method is the manual command-line approach, which is useful for immediate connectivity or troubleshooting. This involves loading the necessary driver and configuring the wpa_supplicant.

The manual process is as follows:

• Load the wireless driver using modprobe brcmfmac.
• Generate the configuration file with the SSID and Pre-Shared Key (PSK) using wpa_passphrase <ssid> <psk> > /etc/wpa_supplicant.conf.
• Initialize the wireless interface in the background using wpa_supplicant -iwlan0 -B -c /etc/wpa_supplicant.conf.
• Request an IP address from the DHCP server using dhcpcd -MA4 wlan0.

The second method utilizes the cloud-config format, which allows for a more declarative approach to network management. The configuration is structured as follows:

```yaml

cloud-config

rancher:
network:
interfaces:
wlan0:
wifinetwork: network1
wifinetworks:
network1:
ssid: "Your wifi ssid"
psk: "Your wifi password"
scan_ssid: 1
```

A known behavioral characteristic of the Raspberry Pi on this setup is that the device may automatically drop the Wi-Fi connection after a period of inactivity. This is not a software bug but a result of the hardware's internal power management settings, which attempt to conserve energy by putting the wireless chip into a low-power state.

K3s Cluster Architecture on Raspberry Pi 5

For those seeking a more modern approach than the legacy RancherOS, K3s provides a highly optimized Kubernetes distribution. A robust production-like environment on Raspberry Pi 5 requires a multi-node architecture to ensure resiliency. While a single-node cluster is possible, a minimum of three nodes is recommended.

In this architecture, one Raspberry Pi serves as the control plane (the master node), which manages the cluster state and API server. The remaining Raspberry Pis act as worker nodes (agents), which execute the actual containerized workloads.

The software stack for a high-performance Raspberry Pi cluster typically includes:

• OS: Ubuntu Server 24.04.2 LTS (64-bit)
• Orchestrator: K3s (Version 1.31)
• Load Balancer: MetalLB (to handle external traffic to services)
• Ingress Controller: nginx (to manage routing into the cluster)
• Certificate Management: cert-manager (for automated SSL/TLS certificates)
• Management Layer: Rancher (for a GUI-based administration of the K3s cluster)

Initial setup for each node requires a unique hostname and a static or reserved IP address, particularly for the control plane, to ensure that worker nodes can always locate the master server. Helm, the Kubernetes package manager, should be installed on the control plane via Snap.

K3s Server Installation and Configuration

The installation of the K3s server on the primary node is streamlined through a curated installation script. This script handles the downloading of binaries and the configuration of the master node.

To install the K3s server, the following command is used:

bash curl -sfL https://get.k3s.io | sh -s - server &

Upon completion, the system stores the Kubeconfig file at /etc/rancher/k3s/k3s.yaml. This file is essential for interacting with the cluster. To manage the cluster from a remote laptop or desktop, the administrator must copy this file and modify the server IP address from the default 127.0.0.1 to the actual static IP address of the Raspberry Pi master node.

The process for exporting the Kubeconfig for remote access is as follows:

1. Copy the file to the home directory: sudo cp /etc/rancher/k3s/k3s.yaml ~/kubeconfig.
2. Change ownership to the current user: sudo chown $(whoami):$(whoami) ~/kubeconfig.
3. Transfer the file to the remote machine using SCP: scp pi@pi1:~/kubeconfig ~/kubeconfig.
4. Set the environment variable on the local machine: export KUBECONFIG=~/kubeconfig.

Verification of the installation is performed using the command sudo k3s kubectl get nodes, which should show the master node as Ready.

Expanding the Cluster with Agent Nodes

Once the control plane is operational, the cluster can be expanded by adding agent nodes. This process requires a secure token generated by the master node to authenticate the new agents.

To retrieve the server token from the master node, run the following command:

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

Once the token is obtained, it can be passed to the other Raspberry Pis to join them to the cluster. For efficiency, this can be done by SSHing into each worker node and executing the agent installation script.

The installation command for an agent node is:

bash export TOKEN=***REDACTED*** curl -sfL https://get.k3s.io agent | INSTALL_K3S_EXEC="agent --server https://192.168.1.10:6443 --token $TOKEN" sh -

In this command, https://192.168.1.10:6443 must be replaced with the actual IP address of the master node. After a few minutes, the agent node will register with the control plane. The administrator can verify the successful addition of the node by running kubectl get nodes from the master or the configured remote machine.

Comparison of Deployment Methodologies

The choice between RancherOS and a K3s-on-Ubuntu approach depends on the specific goals of the project. The following table summarizes the primary differences.

Technical Analysis of the Raspberry Pi Kubernetes Ecosystem

The evolution from RancherOS to K3s on the Raspberry Pi platform reflects a broader trend in the industry toward "Edge Kubernetes." The initial RancherOS approach sought to treat the entire OS as a disposable container image, which minimized the attack surface and ensured consistency. However, the lack of automatic partition expansion and the limited hardware support for newer Pi models created friction for the end user.

K3s solves these problems by decoupling the orchestrator from the operating system. By running K3s on a stable 64-bit OS like Ubuntu Server 24.04.2 LTS, users gain access to a wider array of drivers, better memory management, and the ability to use standard Linux tools for system maintenance.

The introduction of MetalLB and nginx into this stack is crucial. Because Raspberry Pi clusters usually live on a local network without a cloud-provider load balancer, MetalLB simulates this functionality by providing a virtual IP that can be shared across the nodes. Nginx then handles the Layer 7 routing, allowing the user to host multiple services on a single IP address using different hostnames.

The reliance on the ARM64 architecture is not merely a preference but a requirement for modern Kubernetes workloads. 32-bit ARM systems often struggle with the memory overhead of the Kubelet and the container runtime. By utilizing the Raspberry Pi 5 and Ubuntu 64-bit, the system can address significantly more RAM and handle larger container images, making the cluster viable for more than just simple "hello world" apps.

Sources

1. RancherOS Raspberry Pi Server Documentation
2. RancherOS Installation Guide
3. ARM64 Raspberry Pi 5 Implementation Gist
4. Sidenote K8s on Raspbian Guide