Longhorn is a distributed block storage system for Kubernetes. It pools the local disks of worker nodes and presents them as replicated persistent volumes through the Container Storage Interface (CSI), with incremental snapshots, scheduled backups to S3 or NFS, and a web dashboard. It solves a common on-premises and edge problem: stateful workloads need volumes that survive a node failure, but a SAN or a full Ceph cluster is more infrastructure than a small platform team wants to run. Longhorn originated at Rancher Labs (now part of SUSE) and was accepted into the CNCF as a sandbox project on 11 October 2019; it moved to incubating on 4 November 2021. This brief also covers Velero, the Kubernetes backup and restore tool that complements Longhorn. Velero is a Kubernetes-native backup, restore and migration tool that Broadcom contributed to the CNCF, where it was accepted at the sandbox level on 11 March 2026.
CNCF daily · Sprint 2, day 5 · Cloud Native Storage
At a glance
| Category | Runtime › Cloud Native Storage |
| CNCF status | Longhorn: Incubating. Accepted October 11, 2019; moved to Incubating November 4, 2021 |
| Companion project | Velero: Sandbox. Accepted March 11, 2026 (Runtime › Cloud Native Storage) |
| Written in | Go |
| License | Apache 2.0 (both projects) |
| Data engines | V1 (iSCSI based, default) and V2 (SPDK based) |
| Backup targets | S3-compatible object storage or NFSv4 (Longhorn); S3, GCS, Azure Blob and others through plugins (Velero) |
Architecture
flowchart TB
APP[Application pod] ==>|mounts PVC| CSI[Longhorn CSI driver]
subgraph LH[Longhorn in longhorn-system]
CSI ==> ENG[Engine<br/>one per volume]
MGR[longhorn-manager<br/>on every node] -.->|schedules and heals| ENG
ENG ==>|synchronous writes| R1[Replica on node A]
ENG ==> R2[Replica on node B]
ENG ==> R3[Replica on node C]
end
R1 -.->|incremental backup| BS[(Backup target<br/>S3 or NFS)]
subgraph VB[Velero]
VEL[Velero server<br/>and node agent]
end
VEL ==>|reads objects| API[Kubernetes API server]
VEL -.->|VolumeSnapshot request| CSI
VEL ==>|writes backup| OBJ[(Object storage<br/>cluster state)]
classDef actor fill:#eceff1,stroke:#455a64,stroke-width:1.5px,color:#1d1c1a
classDef core fill:#0f766e,stroke:#064e4a,stroke-width:2px,color:#ffffff
classDef ctrl fill:#ede7f6,stroke:#5e35b1,stroke-width:1.5px,color:#1d1c1a
classDef data fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px,color:#1d1c1a
classDef store fill:#fff3e0,stroke:#e65100,stroke-width:1.5px,color:#1d1c1a
class APP data
class CSI,ENG,R1,R2,R3,VEL core
class MGR,API ctrl
class BS,OBJ store
style LH fill:#0f766e14,stroke:#0f766e,stroke-width:2px
style VB fill:#0f766e14,stroke:#0f766e,stroke-width:2px
Key: teal blocks are the projects themselves, blue are workloads and proxies, purple are control and configuration, amber are storage, red are security and identity, green are observability, grey are external actors. Thick arrows show the primary path, thin solid arrows other data flows, dashed arrows control, discovery and telemetry.
| Component | Responsibility |
|---|---|
| longhorn-manager | DaemonSet that exposes the API, runs the CSI driver logic, schedules replicas onto nodes and disks, and rebuilds failed replicas. |
| Engine | A lightweight controller, one per volume, that serves the block device to the pod and writes to every replica synchronously. |
| Replica | A copy of the volume stored as sparse files on a node disk. A volume normally has three replicas on different nodes. |
| Instance manager | Runs the engine and replica processes on each node, so a manager upgrade does not interrupt I/O. |
| Share manager | Exports a volume over NFS to give pods ReadWriteMany access. |
| Backup target | An S3-compatible or NFS location that stores incremental, deduplicated backups, which makes cross-cluster restore and disaster-recovery volumes possible. |
| Velero server and node agent | Velero copies Kubernetes objects to object storage and, for volume data, either triggers CSI snapshots or moves data with its node agent. |
Design principle. Longhorn runs a separate small storage controller for every volume instead of one large shared storage cluster. A fault or upgrade therefore affects one volume at a time, and the design is simple enough to understand and repair. Velero follows the same Kubernetes-native idea: backups and restores are custom resources, so they can be scheduled, audited and managed through GitOps.
Production reference design
A typical layout is a three-node (or larger) cluster on bare metal, on-premises virtualisation or EKS and similar, with a dedicated disk on each node.
- Prepare the nodes. Longhorn needs
open-iscsiand, for ReadWriteMany, an NFS client. Run the project’s preflight check before installing:sudo apt install -y open-iscsi nfs-common && sudo systemctl enable --now iscsid longhornctl check preflight - Install Longhorn with Helm, pinning the chart version:
helm repo add longhorn https://charts.longhorn.io && helm repo update helm install longhorn longhorn/longhorn -n longhorn-system --create-namespace --version 1.12.1 - Define a StorageClass with the replica count and recovery behaviour the workload needs:
apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: { name: longhorn-db } provisioner: driver.longhorn.io allowVolumeExpansion: true reclaimPolicy: Retain parameters: numberOfReplicas: "3" dataLocality: best-effort staleReplicaTimeout: "30" - Set a backup target and recurring jobs. Point Longhorn at an S3 bucket (through a Secret with the credentials) and schedule snapshots and backups per volume group.
- Add Velero for everything around the volumes. Install it with a bucket and a Longhorn-aware snapshot class, so a backup captures both the manifests and the volume data:
apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: longhorn-backup labels: { velero.io/csi-volumesnapshot-class: "true" } driver: driver.longhorn.io deletionPolicy: Delete parameters: { type: bak }velero schedule create daily --schedule "0 2 * * *" --ttl 720h --snapshot-move-data
Typical uses are PostgreSQL, MySQL and message brokers on bare-metal clusters, persistent volumes for CI systems and internal tools on edge or private-cloud Kubernetes, and cluster migration or disaster recovery with Velero restoring into a different cluster.
Operational considerations
- Replication is not a backup. Three replicas protect against a node or disk failure, not against deletion or corruption, which replicate instantly. Always configure the backup target and test a restore, including restoring into a second cluster.
- Performance depends on the network and disks. Synchronous replication adds latency and consumes bandwidth during rebuilds. Use dedicated SSD or NVMe disks and a fast node network, and use
dataLocalityto keep one replica next to the pod. The V2 engine targets higher IOPS but needs huge pages and specific kernel modules, so test it before relying on it for production data. - Capacity planning. Three replicas triple the raw space used. Longhorn keeps a minimum percentage of each disk free by default, so size disks with that margin and watch the over-provisioning setting.
- Upgrades and node maintenance. Upgrade one minor version at a time, check volume health first, and drain nodes one by one so replicas can rebuild between steps. Set a sensible node drain policy.
- Velero scope. Velero backs up API objects, not etcd itself. Keep schedules, retention (
--ttl) and the bucket under access control, and exercise a restore regularly, since restore order, CRDs and external dependencies are the usual failure points.
Adoption
- The Longhorn project’s
ADOPTERS.mdlists end users including Nemlig, which uses it as persistent storage in its internal Kubernetes platform, NAVER, Walkbase, JTEKT, which runs it in an on-premises developer platform, and Child Rescue Coalition. - Longhorn is also packaged commercially in the SUSE Rancher ecosystem and is a common default storage choice in lightweight Kubernetes distributions.
- Velero’s CNCF page lists a case study from the Infosys client programme, in which Velero is one of several tools used on a Kubernetes platform. Broadcom, Red Hat and Microsoft are named as maintainers, but the project’s CNCF history is short and few organisations are named publicly.
Alternatives
| Solution | Model | Best suited to |
|---|---|---|
| Rook (Ceph) (CNCF Graduated) | Operator-managed Ceph for block, file and object | Larger clusters needing all three storage types and very high scale |
| OpenEBS (CNCF Sandbox) | Several engines, including local and replicated volumes | Teams wanting a choice between local PV simplicity and replication |
| Piraeus / LINSTOR (CNCF Sandbox) | DRBD-based replicated block storage | Low-latency replicated volumes on Linux hosts |
| Cloud CSI drivers (EBS, Persistent Disk, Azure Disk) | Provider-managed block devices | Clusters in a single public cloud that do not need portability |
| Kasten K10, Kanister, K8up | Backup tools, some CNCF Sandbox | Application-aware backup, or an alternative to Velero |
Strengths and limitations
| Strengths | Limitations |
|---|---|
| Simple install and a clear dashboard; no separate storage cluster to run | Replicated block only; object and shared file need other tools (RWX is NFS-based) |
| Built-in snapshots, S3 and NFS backups and disaster-recovery volumes | Synchronous replication adds latency; not a match for local NVMe speed |
| Per-volume engines limit the blast radius of failures and upgrades | Three replicas mean three times the raw capacity |
| Velero adds portable, GitOps-friendly cluster backup and migration | Velero is a young CNCF project; restore testing is still the operator’s job |
| Apache 2.0, active development and a clear roadmap | The V2 engine needs extra node setup and careful testing |
Recommendation
Trial. Longhorn is a sound default for stateful workloads on small and medium on-premises, edge or private-cloud clusters, where simplicity matters more than extreme scale. Adopt it for non-critical and moderately demanding volumes first, keep an off-cluster backup target from day one, and pair it with Velero for cluster-level recovery. For very large or latency-critical systems, evaluate Rook or local storage with application-level replication.
References: CNCF project page: Longhorn · CNCF project page: Velero · Longhorn documentation · Longhorn ADOPTERS · Velero documentation · Velero 1.17 release notes · InfoQ: Broadcom donates Velero to the CNCF