Longhorn is distributed block storage for Kubernetes: it takes the local disks of your nodes, creates volumes on them and keeps several synchronous copies of each volume on different nodes. If a node fails, your Pod carries on with one of the remaining copies. It pays off mainly for small clusters of three or more nodes on your own hardware, on bare metal or with providers that lack good block storage. If you already have replicated cloud storage through a CSI driver, you usually don't need it. The current release is Longhorn 1.13.0 (as of 30 October 2026), installed with Helm, with open-iscsi on every node as the most important prerequisite.
I'm a CNCF Kubestronaut and wrote the Kubernetes book published by Rheinwerk. So you can place this correctly: my own production cluster on Hetzner does not run Longhorn, it runs the Hetzner CSI driver with the storage class hcloud-volumes. This article is therefore based on the official Longhorn documentation for version 1.13.0, not on running Longhorn myself. You can find all my Kubernetes articles on the Kubernetes page.
Longhorn on Kubernetes: how the architecture works
Longhorn separates control from the data path. The Longhorn Manager runs as a DaemonSet on every node and works like an operator: it watches its own custom resources and creates volumes from them (the pattern is explained in Kubernetes Operator and CRD Explained).
The Longhorn Engine handles the data path: every volume gets its own storage controller on the node where the Pod runs, and that controller writes every block synchronously to all replicas on different nodes. If one controller crashes, only that volume is affected. According to the documentation, a volume with N replicas tolerates at most N minus 1 failed replicas, because at least one healthy copy has to remain.
Engine and replicas run as processes inside the Instance Manager, one Pod per node in longhorn-system. If it restarts, every volume it serves on that node is affected, so Longhorn reserves CPU for it and protects it with a PodDisruptionBudget. The newer V2 Data Engine needs raw block devices, huge pages and a dedicated CPU core per node; for small clusters, stay with the default V1.
Replicas: how many copies on three nodes
The longhorn storage class created by the Helm chart uses three replicas. On three nodes, that puts one copy on each node. For production, the best practices recommend keeping "Replica Node Level Soft Anti-Affinity" at false, which is also the default, so two copies of the same volume never land on one node. On three nodes this means: if a node fails, the volume keeps running with two copies, but Longhorn has nowhere to put a third until the node is back.
For data-intensive applications, the best practices name two replicas as the default, because it saves disk space and write load. Applications that replicate themselves, such as a distributed database cluster, can run with dataLocality: strict-local and exactly one replica. That way the redundancy isn't doubled. How such applications get one volume per instance is shown in Kubernetes StatefulSet vs Deployment.
For planning, note that the in-memory read index costs one byte per 4 KiB block, so a 1 TB volume uses 256 MB of RAM per replica. Longhorn discards a failed replica after 48 hours (staleReplicaTimeout: 2880 minutes).
Prerequisites: open-iscsi, NFSv4 and hardware
Longhorn reaches deep into the nodes' operating system. The installation guide for 1.13.0 requires on every node:
- Kubernetes 1.34 or later and a compatible container runtime such as containerd
open-iscsi with the iscsid service running and the iscsi_tcp kernel module loaded, because V1 exposes volumes over iSCSI- an NFSv4 client if you use ReadWriteMany volumes or an NFS backup target
- the tools
bash, curl, findmnt, grep, awk, blkid and lsblk
- a host filesystem with ext4 or XFS, plus root and privileged permissions for the Longhorn Pods
The guide carries an explicit warning: don't install open-iscsi 2.1.12, because a configuration change in that version makes volume attachment fail. Versions up to 2.1.11 or from 2.1.13 onwards are fine. Supported architectures are AMD64 and ARM64.
The longhornctl command line tool checks whether your nodes are ready. On Debian or Ubuntu, you can also install the packages yourself:
# check all nodes via your kubeconfig
./longhornctl check preflight
# or by hand on every node (Debian/Ubuntu)
apt-get install open-iscsi nfs-common
modprobe iscsi_tcp
As minimum production hardware, the best practices list three nodes with 4 vCPUs and 4 GiB of RAM each, SSD or NVMe storage and a dedicated disk for Longhorn, plus 10 Gbps between nodes for good performance. Latency matters more than IOPS, since every write crosses the network synchronously.
Installing Longhorn with Helm
The installation itself is short. Helm 3 on your machine is all you need:
helm repo add longhorn https://charts.longhorn.io
helm repo update
helm install longhorn longhorn/longhorn \
--namespace longhorn-system --create-namespace --version 1.13.0
kubectl -n longhorn-system get pod
Three things to know afterwards. First, the chart marks its longhorn storage class as the default, and on k3s local-path is the default too. With two defaults, Kubernetes uses the most recently created one for a PVC without storageClassName, so pick one on purpose. Second, the web UI has no login once you expose it through an Ingress; add authentication. Third, don't change the default storage class, the documentation advises; create a new one:
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: longhorn-2r
provisioner: driver.longhorn.io
allowVolumeExpansion: true
reclaimPolicy: Delete
parameters:
numberOfReplicas: "2"
dataLocality: "best-effort"
staleReplicaTimeout: "2880"
fsType: "ext4"
If you run your cluster with GitOps, the release belongs in the repository with a pinned version, as described in GitOps with ArgoCD: Deploy from Git.
Longhorn backup: snapshots and backups to S3
A Longhorn snapshot is not a backup. Snapshots are stored as part of each replica on the same disks as the volume, up to 254 per volume. They are crash-consistent: Longhorn runs sync before taking a snapshot, but that doesn't make a database with open transactions application-consistent.
A backup lives outside the cluster in a backupstore, preferably S3-compatible, alternatively NFS, SMB or Azure Blob. The credentials go into a Secret in the longhorn-system namespace. For an S3-compatible provider other than AWS, you also set AWS_ENDPOINTS. You enter the target as s3://<bucket>@<region>/, either in the web UI or through Helm under defaultBackupStore.backupTarget and defaultBackupStore.backupTargetCredentialSecret.
Regular backups are set up as a RecurringJob. This example backs up every volume without its own assignment daily at 3 a.m. and keeps 14 backups:
apiVersion: longhorn.io/v1beta2
kind: RecurringJob
metadata:
name: backup-daily
namespace: longhorn-system
spec:
cron: "0 3 * * *"
task: "backup"
groups:
- default
retain: 14
concurrency: 2
One rule is easy to miss: Longhorn alone manages the lifecycle of the backups in the bucket. A retention policy set directly on the bucket is explicitly prohibited by the documentation. Longhorn only backs up volumes. You still need the cluster state in etcd and your manifests; how all of that fits together is in Kubernetes Backup: etcd and Volumes.
Longhorn, cloud CSI or local-path: what fits when
The basics of Persistent Volumes, storage classes and the three options are in Kubernetes Persistent Volumes and PVCs. Here is the direct comparison:
That gives you a rule of thumb. Longhorn fits without good provider block storage (your own servers, bare metal, edge sites), or when you need ReadWriteMany or backups to S3 in the storage layer. If your cloud provider already delivers replicated block storage through CSI, Longhorn on top would replicate twice and add latency. local-path is enough for caches, test environments and anything that can live with being tied to one node.
On my own cluster, as described in Kubernetes on Hetzner: k3s in Production, I use Hetzner's CSI driver, and databases run there with CloudNativePG, which handles replication itself. Whether running your own storage makes sense for you at all is something I weigh up in Kubernetes On-Premises or Cloud?.
Small clusters with three nodes: what to watch
- Dedicated disk: If you have to use the root disk, leave the "Storage Minimal Available Percentage" setting at 25 percent. With a dedicated disk, the documentation allows 10 percent.
- CPU reservation: By default, Longhorn reserves 12 percent of a node's allocatable CPU for each Instance Manager. Plan for that on small nodes.
- Maintenance: When you drain a node for updates, the Instance Manager's PodDisruptionBudget applies. With three nodes and three replicas, wait until all volumes are healthy again before you touch the next node.
- Monitoring: Longhorn exposes Prometheus metrics. More on that in Kubernetes Monitoring with Prometheus.
Frequently asked questions
Is Longhorn free?
Yes. Longhorn is free open source software, originally developed by Rancher Labs and a CNCF incubating project since 4 November 2021. Costs come only from hardware, disk space for the replicas and storage for backups.
Does Longhorn support ReadWriteMany?
Yes. Longhorn provides RWX volumes through an NFSv4.1 server in a dedicated share-manager Pod. Every node needs an NFSv4 client for that.
Does a Longhorn snapshot replace a backup?
No. Snapshots sit on the same disks as the volume. Only a backup to an external backupstore such as S3 survives losing the cluster.
Does Longhorn run on a Raspberry Pi?
Longhorn supports ARM64 but not ARM32. A Pi with a 64-bit operating system is an option; the recommended hardware with SSD and 4 GiB of RAM per node still applies. How to build a Pi cluster is shown in Kubernetes on the Raspberry Pi.
Where to go next
My suggestion for this week: run longhornctl check preflight against a test cluster to see per node which packages are missing. The Longhorn installation guide and the best practices are the binding reference for each version.
The basics of volumes, storage classes and CSI drivers are covered in detail in chapter 6 of my book "Kubernetes: Practical Guide for Developers and DevOps Teams" (Rheinwerk Computing). You can find all the information about the book on my Kubernetes page.
