Longhorn: Distributed Storage for Kubernetes

By Kokil Thapa | Last reviewed: September 2026

Stateful workloads on Kubernetes need storage that survives pod rescheduling and node failure. Longhorn: Distributed Storage for Kubernetes fills that gap on bare metal and small clusters. It runs as a CNCF project from Rancher/SUSE and exposes block volumes through the Container Storage Interface (CSI). You get synchronous replication, snapshots, and S3 backups without standing up a full Ceph cluster. If you already manage Kubernetes persistent volumes and storage classes, Longhorn is the next layer: replicated disks on the nodes you already pay for.

What Is Longhorn and How Does Distributed Storage Work on Kubernetes?

Longhorn turns local disk space on Kubernetes worker nodes into replicated block volumes. Each volume is a thin-provisioned replica set managed by a dedicated engine and controller pod. The Longhorn Manager coordinates scheduling, health checks, and rebuilds when a node disappears.

Kubernetes itself only knows about PersistentVolumeClaims (PVCs). Longhorn registers a CSI driver that provisions volumes when a PVC binds to a StorageClass. The kubelet mounts the block device into your pod. From the application side, it behaves like any other persistent disk.

In my experience maintaining production Linux infrastructure, the appeal is operational simplicity. You do not need a separate storage team or dedicated storage servers. Three worker nodes with spare SSD space can host a highly available MySQL or PostgreSQL instance. That trade-off suits teams running K3s at the edge or self-hosted clusters where cloud EBS equivalents are unavailable.

Core components you will interact with

• Longhorn Manager — DaemonSet on every node; handles volume lifecycle and replica placement.
• Instance Manager — Runs the iSCSI engine process for attached volumes on a node.
• CSI Plugin — Implements create, attach, detach, expand, and snapshot operations.
• Longhorn UI — Web dashboard for volume status, node disks, backups, and recurring jobs.

The official project documentation at longhorn.io/docs remains the authoritative reference for version-specific behaviour. Cross-check CSI behaviour against the Kubernetes CSI volume documentation when debugging mount failures.

How Do You Install Longhorn on a Kubernetes Cluster?

Installation takes minutes on a three-node cluster with openiscsi and sufficient disk space. Longhorn ships as a Helm chart or a single manifest bundle. Most production teams use Helm for upgrade control.

Prerequisites on every worker node

1. Install open-iscsi and ensure the service is running.
2. Mount a dedicated disk or partition at a path like /var/lib/longhorn.
3. Open port 9500 for the UI if you expose it through an Ingress.
4. Confirm your Kubernetes version is supported by the Longhorn release you pick.

# Ubuntu 24.04 worker nodes
sudo apt-get update
sudo apt-get install -y open-iscsi nfs-common
sudo systemctl enable --now iscsid

# Add the Longhorn Helm repo
helm repo add longhorn https://charts.longhorn.io
helm repo update

# Install into dedicated namespace
kubectl create namespace longhorn-system
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --set defaultSettings.defaultReplicaCount=3

After pods reach Ready state, port-forward the UI for a first look:

kubectl port-forward -n longhorn-system svc/longhorn-frontend 8080:80

On bare-metal clusters I have supported, the first failure is almost always missing open-iscsi. The Longhorn Manager logs show attach errors that look like generic volume mount problems. Fix the host package before chasing Kubernetes RBAC.

For Laravel or PHP workloads moving to containers, pair this storage layer with guidance from Kubernetes for Laravel getting started. Your PVC holds uploaded files, session data, or queue payloads the same way a local disk would on a VM.

How Do You Create and Configure Longhorn Volumes for Production Workloads?

Once installed, define a StorageClass and let applications claim volumes through standard PVC manifests. Longhorn creates a default StorageClass named longhorn unless you disable it at install time.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-fast
provisioner: driver.longhorn.io
allowVolumeExpansion: true
reclaimPolicy: Retain
parameters:
  numberOfReplicas: "3"
  staleReplicaTimeout: "2880"
  fsType: "ext4"
  dataLocality: "best-effort"

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-data
  namespace: production
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: longhorn-fast
  resources:
    requests:
      storage: 50Gi

Bind that PVC to a StatefulSet or Deployment. ReadWriteOnce is the common mode for databases. Longhorn does not provide ReadWriteMany natively; use NFS or another shared filesystem layer if multiple pods must write concurrently. See NFS as Kubernetes persistent storage for that pattern.

Settings that matter in production

• numberOfReplicas — Use 3 for HA; use 2 only when you accept higher risk on two-node clusters.
• dataLocality — Set strict-local for latency-sensitive databases on known node pools.
• reclaimPolicy: Retain — Prevents accidental data loss when someone deletes a PVC.
• allowVolumeExpansion — Lets you grow disks without rebuilding the volume from scratch.

Track disk consumption early. Longhorn reports per-node usage in the UI. Pair that with cluster-level monitoring from Kubernetes cost monitoring with Kubecost so storage growth does not surprise finance.

How Does Longhorn Compare to OpenEBS, Ceph, and Cloud Block Storage?

Choosing storage is a capacity, ops overhead, and performance decision. Longhorn targets teams that want replicated block storage without Ceph's learning curve. OpenEBS offers multiple engines with different trade-offs. Cloud block storage offloads replication entirely but ties you to a vendor.

Deeper comparisons live in dedicated posts on OpenEBS for Kubernetes storage and Ceph storage fundamentals. For Gluster-based approaches, read GlusterFS distributed storage.

Longhorn wins when you run Kubernetes on your own hardware in Nepal or abroad and cloud disks are expensive or unavailable. A three-node VPS cluster at Rs 15,000/month (~USD 110) per node can host both apps and storage. Ceph on the same hardware often needs more RAM and dedicated tuning time.

How Do Snapshots, Backups, and Disaster Recovery Work in Longhorn?

Longhorn distinguishes snapshots from backups. Snapshots are copy-on-write checkpoints stored on the same nodes as the volume. Backups upload snapshot data to external S3-compatible object storage.

Configure a recurring backup job in the UI or through a custom resource. Point it at MinIO, AWS S3, or Backblaze B2. After a total cluster loss, reinstall Longhorn and restore from backup into a fresh PVC.

apiVersion: longhorn.io/v1beta2
kind: RecurringJob
metadata:
  name: nightly-backup
  namespace: longhorn-system
spec:
  cron: "0 2 * * *"
  task: backup
  groups:
    - default
  retain: 7
  concurrency: 2

Combine Longhorn backups with cluster-level tooling from Velero backup and restore for Kubernetes. Velero captures Kubernetes objects and PVC snapshots. Longhorn backups protect the block data even when etcd restore alone is insufficient.

For point-in-time recovery inside the same cluster, use native volume snapshots in Kubernetes. Longhorn implements the VolumeSnapshotClass so CSI snapshots integrate with standard kubectl workflows.

Test restores quarterly. A backup you have never restored is a guess. On a booking platform like Adventure Third Pole Trek, database downtime during trekking season has real revenue impact. A documented restore runbook beats heroic debugging at 2 AM.

What Production Problems Should You Watch for With Longhorn?

Longhorn is reliable when nodes have clean disk paths and stable networking. Most incidents trace back to configuration gaps rather than software bugs.

Common failure modes and fixes

• Volume stuck in Attaching — Check open-iscsi on the target node and verify the Instance Manager pod is Running.
• Degraded replica count — A node drained for maintenance without replica eviction leaves volumes under-replicated. Use Longhorn's node drain policy.
• Disk pressure — Longhorn schedules new replicas onto nodes with free space. Monitor /var/lib/longhorn usage and add disks before you hit 80%.
• Network partition — Split-brain is mitigated by quorum logic, but fix flaky VLANs or MTU mismatches first.
• Slow rebuilds — Rebuilding a 500 GiB volume over 1 Gbps links takes time. Plan maintenance windows accordingly.

When pods enter CrashLoopBackOff after a storage event, follow the diagnostic sequence in debug a CrashLoopBackOff in Kubernetes. The root cause is often a stale mount rather than application code.

Tune worker nodes using guidance from Kubernetes performance tuning and Kubernetes resource limits and requests. Longhorn engine pods consume CPU during rebuilds. Without limits, a rebuild can starve application pods on the same node.

Understand the full PVC lifecycle in Kubernetes persistent volume lifecycle. A Retain policy saves data but orphan PVs accumulate unless you garbage-collect them deliberately.

If your team lacks in-house cluster ops capacity, Linux system administration and support and maintenance services cover storage layer health checks alongside application uptime. For greenfield platforms, enterprise application development can design stateful workloads with the right storage class from day one.

Key Takeaways

• Longhorn: Distributed Storage for Kubernetes delivers replicated block volumes through CSI on commodity worker nodes—no separate storage cluster required.
• Install open-iscsi on every node, use three replicas for HA, and set StorageClass reclaimPolicy to Retain for production databases.
• Configure S3-compatible recurring backups and test restores before you need them during an outage.
• Choose Longhorn over Ceph for small-to-medium bare-metal clusters; choose cloud block storage when you already run on AWS, GCP, or DigitalOcean.
• Monitor disk usage on Longhorn data paths and plan rebuild time into node maintenance windows.
• Pair Longhorn volume backups with Velero for full cluster disaster recovery that includes Kubernetes object state.

People Also Ask

Is Longhorn production-ready for Kubernetes?

Yes. Longhorn is a CNCF incubating project used in production by Rancher customers and self-hosters worldwide. It suits clusters with three or more worker nodes, stable networking, and SSD-backed disks. Very large multi-petabyte deployments typically outgrow it and move to Ceph.

Can Longhorn volumes expand without downtime?

Yes, when the StorageClass sets allowVolumeExpansion: true. Expand the PVC through kubectl or the Longhorn UI. The filesystem inside the pod may need a manual resize with resize2fs or xfs_growfs depending on the fsType you chose at provision time.

Does Longhorn support ReadWriteMany access modes?

Not natively. Longhorn volumes are ReadWriteOnce block devices. For shared file access across multiple pods, front Longhorn with an NFS provisioner or use a dedicated shared filesystem layer documented in the NFS persistent storage guide on this site.

How much CPU and RAM does Longhorn consume?

Idle overhead is modest—roughly 200–400 MB RAM per node for Manager and Instance Manager pods. Rebuild and backup jobs spike CPU and network I/O. Size nodes with headroom beyond application requests so storage maintenance does not trigger eviction storms.

Run Longhorn With Confidence on Your Cluster

Longhorn: Distributed Storage for Kubernetes gives small teams enterprise-style replicated storage without a dedicated storage department. Install it on three nodes, define a StorageClass with three replicas, wire S3 backups, and prove recovery before production traffic depends on it. Validate your YAML manifests with the JSON formatter when converting between API shapes, and review related architecture posts on the blog.

Need help designing a stateful platform or hardening cluster storage? Contact us to discuss your workload, or browse the portfolio for examples of production systems that depend on reliable infrastructure. You can also read more about the author on the about me page or explore the homepage for services that cover the full stack from code to server.