The intersection of ARM-based single-board computers and container orchestration represents a significant shift in how homelab enthusiasts and edge computing engineers deploy scalable infrastructure. Implementing Rancher-based solutions on Raspberry Pi hardware allows for the creation of highly efficient, low-power clusters that mirror the architecture of massive data center environments. Whether utilizing the specialized RancherOS—a container-optimized operating system designed to run nothing but Docker—or a more traditional Ubuntu Server base paired with K3s (a lightweight Kubernetes distribution), the goal is to achieve a resilient, manageable cluster. The deployment journey involves navigating hardware limitations, such as SD card partition constraints and ARM64 architecture requirements, while integrating sophisticated cloud-native tools like MetalLB for load balancing, nginx for ingress traffic management, and cert-manager for automated TLS certificate issuance.

RancherOS Implementation on Raspberry Pi Hardware

RancherOS provides a unique approach to infrastructure by treating the operating system as a series of containers. This removes the bloat associated with traditional Linux distributions and optimizes the system for the specific needs of containerized workloads.

Compatibility and Initial Provisioning

As of version v0.5.0, RancherOS officially includes a Raspberry Pi image available through the official releases page. While the ecosystem of Raspberry Pi hardware is vast, it is critical to note that only the Raspberry Pi 3 has been formally tested and is known to work with this specific image. Users seeking to deploy this should follow the official Raspberry Pi documentation for the general process of flashing operating system images onto microSD cards.

One of the primary architectural constraints of the RancherOS installation process on Raspberry Pi is the lack of initial cloud-config support. In a standard cloud environment, a cloud-config file is passed during the first boot to automate networking, user creation, and package installation. On the Raspberry Pi, this is not possible.

The impact of this limitation is that the administrator must perform a manual two-stage boot process. First, the system must be booted up in its default state. Second, the administrator must manually enter the configuration changes required for the specific environment. Finally, a reboot is mandatory to apply these changes. This manual intervention ensures that the system is correctly tuned to the local network before it begins attempting to pull container images or join a cluster.

It is important to clarify a common misconception regarding the installation utility. After flashing RancherOS to an SD card, there is no requirement to run the ros install command. The image is designed to be bootable immediately upon flashing.

Managing SD Card Storage Limitations

A significant challenge when deploying RancherOS on a Raspberry Pi is that the operating system does not automatically expand the root partition to occupy the remainder of the microSD card. If a user flashes the image to a 64GB or 128GB card, the system will only recognize the small size of the original image, leaving the majority of the storage unused.

To resolve this, a manual partition expansion workaround is required to ensure that Docker containers, which consume the most disk space, are stored on a larger partition.

The technical process for expanding the usable storage is as follows:

1. Access the partition table using the following command:
   sudo fdisk /dev/mmcblk0
2. Inside the fdisk utility, create a new partition by pressing n.
3. Press [Enter] four consecutive times to accept the default sector and partition settings.
4. Write the table to the disk and exit by pressing w.
5. Reboot the system to reload the new partition tables using:
   sudo reboot
6. Create a dedicated directory to serve as the new Docker root:
   sudo mkdir /mnt/docker
7. Configure the RancherOS configuration to tell Docker to use this new directory via extra arguments:
   sudo ros config set rancher.docker.extra_args [-g,/mnt/docker]
8. Format the newly created partition as ext4:
   sudo mkfs.ext4 /dev/mmcblk0p3
9. Ensure the mount persists across reboots by updating the ROS config:
   sudo ros config set mounts "[['/dev/mmcblk0p3','/mnt/docker','ext4','']]"
10. Mount the partition to the Docker root directory:
    sudo mount /dev/mmcblk0p3 /mnt/docker
11. Restart the Docker service to initialize the new root:
    sudo system-docker restart docker

If the installation is not a fresh deployment and already contains data, the existing Docker root must be migrated to the new partition to avoid data loss. This is achieved by recursively copying all files from the old location to the new one:
sudo cp -R /var/lib/docker/* /mnt/docker
Following the copy, the Docker service must be restarted again:
sudo system-docker restart docker

Network Configuration and Wi-Fi Integration

Available as of version v1.5.2, Wi-Fi support allows Raspberry Pi nodes to be deployed without physical Ethernet cabling. This is particularly useful in home environments where cabling is limited.

For manual configuration via the terminal, the following sequence is used:

1. Load the necessary wireless driver:
   modprobe brcmfmac
2. Generate the wpa_supplicant configuration file using the SSID and PSK:
   wpa_passphrase <ssid> <psk> > /etc/wpa_supplicant.conf
3. Start the wpa_supplicant in the background:
   wpa_supplicant -iwlan0 -B -c /etc/wpa_supplicant.conf
4. Wait several seconds for the association to complete, then request an IP address via DHCP:
   dhcpcd -MA4 wlan0

Alternatively, for those utilizing cloud-config in compatible versions or environments, the following YAML structure is required to enable wireless networking:

```yaml

cloud-config

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

A critical operational note for wireless deployments is that Raspberry Pi hardware is prone to dropping Wi-Fi connections over time. This behavior is caused by the internal power management settings of the wireless chip, which may put the interface into a sleep state to save energy, potentially disrupting cluster communication and causing nodes to be marked as "NotReady" in Kubernetes.

K3s and Rancher 2.0 Architecture on Raspberry Pi 5

While RancherOS provides a specialized experience, a more modern and robust approach involves using Ubuntu Server 64-bit paired with K3s. This architecture is specifically designed to leverage the increased processing power and RAM of the Raspberry Pi 5.

Core Infrastructure Stack

The recommended stack for a production-grade Raspberry Pi cluster consists of the following components:

• Operating System: Ubuntu Server 24.04.2 LTS (64-bit is mandatory for K3s and modern container runtimes).
• Kubernetes Distribution: K3s version 1.31.
• Load Balancer: MetalLB (essential for providing external IP addresses to services).
• Ingress Controller: nginx (manages external access to services within the cluster).
• Certificate Management: cert-manager (automates the issuance and renewal of TLS certificates).
• Management Layer: Rancher 2 (provides a GUI for cluster management).

Cluster Topology and Node Roles

To ensure a base level of resiliency, a minimum of three Raspberry Pi nodes is recommended. A single-node cluster is possible but creates a single point of failure.

The distribution of roles is as follows:

• Control Plane: The primary Pi serves as the K3s server. This node manages the cluster state and schedules workloads. It requires a static or reserved IP address to ensure that worker nodes can always communicate with the API server.
• Worker Nodes: The secondary Pis run the K3s agent. These nodes execute the actual pods and containers.

For administration, it is highly recommended to configure SSH authentication across the network. While monitor and keyboard setups are valid, SSH allows for the simultaneous management of all nodes from a single workstation. Each node must be assigned a unique hostname to avoid conflicts within the Kubernetes DNS.

Deployment Workflow for K3s and Helm

Once the Ubuntu Server images are flashed and the nodes are network-configured, the deployment of management tools begins. Helm, the package manager for Kubernetes, is installed on the control plane using Snap:
sudo snap install helm --classic

Advanced Cluster Services and Rancher Integration

After the K3s cluster is operational, the focus shifts to deploying the management layer and supporting services that allow the cluster to interact with the wider internet and external storage.

Implementing cert-manager for SSL/TLS

To ensure secure communication, cert-manager is deployed to handle certificates. This process begins with the installation of CustomResourceDefinition (CRD) resources, which tell Kubernetes how to handle cert-manager objects:
kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml

Note that for legacy Kubernetes environments (v1.15 or below), the --validate=false flag must be added to the kubectl apply command to bypass validation errors related to the x-kubernetes-preserve-unknown-fields field.

The installation continues with the following steps:

1. Create the dedicated namespace:
   kubectl create namespace cert-manager
2. Add the Jetstack Helm repository:
   helm repo add jetstack https://charts.jetstack.io
3. Update the local cache:
   helm repo update
4. Install the chart:
   helm install cert-manager jetstack/cert-manager --namespace cert-manager --version v0.12.0

Once cert-manager is installed, ClusterIssuers must be created to communicate with Let's Encrypt. Two issuers are typically created: one for staging (to avoid rate limits during testing) and one for production.

Staging Issuer Configuration:
yaml apiVersion: cert-manager.io/v1alpha2 kind: ClusterIssuer metadata: name: letsencrypt-staging spec: acme: email: <EMAIL> server: https://acme-staging-v02.api.letsencrypt.org/directory privateKeySecretRef: name: letsencrypt-staging solvers: - http01: ingress: class: nginx

Production Issuer Configuration:
yaml apiVersion: cert-manager.io/v1alpha2 kind: ClusterIssuer metadata: name: letsencrypt-prod spec: acme: email: <EMAIL> server: https://acme-v02.api.letsencrypt.org/directory privateKeySecretRef: name: letsencrypt-prod solvers: - http01: ingress: class: nginx

Deploying Rancher 2 Management Server

Rancher 2 provides the centralized dashboard for managing the K3s cluster. It is installed into its own namespace to maintain isolation.

1. Create the namespace:
   kubectl create namespace cattle-system
2. Add the Rancher Helm repository:
   helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
3. Install the Rancher server:
   helm install rancher rancher-latest/rancher --namespace cattle-system --set hostname=<HOST_NAME> --set ingress.tls.source=letsEncrypt --set letsEncrypt.email=<EMAIL_ADDR>

In the event that the Rancher ingress becomes corrupted or fails to route traffic correctly, a recovery process is used. First, the current values are exported to a YAML file:
helm -n cattle-system get values rancher > rancher-values.yaml
Then, the problematic ingress is deleted:
kubectl -n cattle-system delete ingress rancher
Finally, the chart is upgraded and redeployed using the saved values:
helm -n cattle-system upgrade -i rancher rancher-latest/rancher -f rancher-values.yaml

Persistent Storage via NFS and Synology DiskStation

Since Raspberry Pi nodes rely on SD cards, which are prone to failure and have limited write endurance, using external storage is mandatory for any serious workload. A common setup involves a Synology DiskStation acting as an NFS server.

To enable Persistent Volume Claim (PVC) support on the K3s cluster, an NFS client provisioner is deployed. This allows K3s to dynamically request and mount storage from the Synology NAS.

The deployment command for the ARM64-compatible NFS provisioner is:
helm -n nfs-provisioner install diskstation stable/nfs-client-provisioner --set nfs.server=<DISKSTATION_IP> --set nfs.path=<NFS_MOUNTING_PATH> --set image.repository=kopkop/nfs-client-provisioner-arm64

This configuration ensures that data is stored on the redundant drives of the NAS rather than the volatile SD cards of the Pi nodes, providing the necessary durability for database workloads and application logs.

Comparative Analysis of Raspberry Pi Deployment Strategies

The choice between a RancherOS approach and a K3s-on-Ubuntu approach depends on the specific goals of the administrator and the hardware available.

Final Technical Analysis

The deployment of Rancher and its associated ecosystems on Raspberry Pi hardware is a balancing act between the constraints of ARM architecture and the demands of cloud-native software. The evolution from RancherOS v0.5.0 on the Raspberry Pi 3 to K3s on the Raspberry Pi 5 demonstrates a clear trajectory toward higher performance and greater stability.

The most significant technical hurdle remains the storage layer. Whether it is the manual fdisk and ros config dance required to expand the root partition in RancherOS, or the integration of a Synology NFS provisioner in a K3s cluster, the microSD card is the primary bottleneck. By offloading the Docker root or implementing PVCs via NFS, the system transforms from a fragile prototype into a resilient edge cluster.

Furthermore, the integration of the "Big Three" of Kubernetes networking—MetalLB, nginx, and cert-manager—elevates the cluster from a local experiment to a functional web-hosting environment. The use of Let's Encrypt via cert-manager's ClusterIssuers removes the burden of manual certificate rotation, while MetalLB provides the necessary networking bridge to assign stable IP addresses to services.

Ultimately, the Raspberry Pi 5 architecture combined with Ubuntu Server 24.04.2 LTS and K3s provides the most viable path forward. It leverages the 64-bit instruction set and increased RAM to handle the overhead of the Rancher 2 management server, while maintaining the flexibility to integrate with enterprise-grade storage and security tools. The shift toward using Helm for nearly every component—from the NFS provisioner to the Rancher server itself—underscores the industry's move toward declarative infrastructure, even at the smallest scale of hardware.

Sources

1. RancherOS Raspberry Pi Server
2. RancherOS Installation Guide
3. ARM64 K3s Deployment Gist
4. Rancher on K3s Integration Gist