Skip to content

How to provision k3s, Longhorn, and Rancher on a Raspberry Pi fleet

Purpose

Canonical operator runbook for standing up a small Raspberry Pi (or Pi-class ARM) fleet running k3s, Longhorn, and optionally Rancher, with either distributed Longhorn disks or central / multi-server storage—without assuming unbounded CPU, RAM, or disk IOPS on the nodes.

Doctrine package (what the platform is for, HA meaning, approved vs deferred): Platform doctrine package — homelab / farm edge. Strategy and tradeoffs (why, not only how): Platform strategy for farm and homestead services, Platform decision memo — phase, HA scope, deferrals. Per-node checklist: Raspberry Pi fleet provisioning standard. Captures: K3s / Longhorn / Rancher / Pi platform source note.

Legend (used across this package)

Tag Meaning
Mandatory Required for a minimal working cluster on Pi-class hardware.
Optional (HA / scale) Improves availability or capacity; adds complexity, power, and ops burden—do not mix into Phase 0/1 without intent.
P0 Lab / learning—throwaway data OK; fastest path.
P1 Pilot on real workloads (e.g. farmOS trial)—backups and resource limits expected.
Later Production-style HA, multi-site, or heavy Rancher coupling—after k3s + storage are boring.

Package map (read in order)

Step Page What you do there
0 Prerequisites and assumptions Confirm OS, RAM/disk reality, scope (P0 vs P1 vs Later).
1 Hardware BOM and node roles Assign server / agent / storage roles; size SSD vs SD.
2 Network and power prerequisites Stable LAN, DNS, time, UPS / brownout behavior.
3 Central and HA storage options Pick Longhorn-only, central NAS, or hybrid; optional HA etcd path.
4 Bootstrap sequence Install k3s server → agents → kubeconfig hygiene.
5 Longhorn storage configuration sequence open-iscsi, Longhorn install, StorageClass, replica policy on Pi.
6 Rancher installation sequence Defer for P0; Helm install when ingress + certs ready (Later default for farm edge).
7 Backup and restore sequence App dumps + Longhorn + etcd awareness—see also Kubernetes platform backup / DR.
8 Validation checklist kubectl, Longhorn UI, workload smoke tests.
9 Troubleshooting and degraded modes OOM, disk pressure, split-brain, WAN-down farm edge.

End-to-end flow (reference)

mermaid flowchart LR subgraph prep [Prep] A[Prereqs + BOM] --> B[Network / power] B --> C[Storage model] end subgraph cluster [Cluster] D[Bootstrap k3s] --> E[Longhorn] E --> F{Need Rancher UI?} F -->|P0/P1 often no| G[Workloads + limits] F -->|Later| H[Rancher Helm] H --> G end subgraph protect [Protect] G --> I[Backup / restore drills] end prep --> cluster --> protect

Resource rule (all phases)

Treat each Pi as a small, battery- and thermally constrained node: cap Longhorn replicas, limit cluster add-ons, prefer logical DB backups over churning snapshots, and measure idle watts and peak CPU before declaring production. For farm-site power context see Off-grid power strategy — Demory.