application · storage · kubernetes

Block storage that survives,Longhorn.

A cloud-native, distributed block storage system for Kubernetes that turns the local disks across your nodes into replicated, persistent volumes — with snapshots and backups to NFS or S3. This guide covers installation via Helm, NFS setup, the storage namespace, and the StorageClass that provisions it all.

Install via HelmNFS setupStorageClass

Replicated by default

Every volume is synchronously replicated across nodes, so a single node failure doesn't lose data. Snapshots stay in-cluster; backups ship incrementally to NFS or S3 targets and restore anywhere.

• Replication — synchronous copies via numberOfReplicas.
• Backups — incremental, to NFS or S3 targets.
• CSI native — provisioned through driver.longhorn.io.

CNCFGovernance

driver.longhorn.ioCSI driver

open-iscsiNode prerequisite

NFS / S3Backup targets

FeaturesFAQRelated

On this page

What this guide covers

Install

The Helm install path, plus the open-iscsi prerequisite that trips up most first attempts with volumes stuck in Attaching.

NFS setup

Prepare an Ubuntu host with nfs-common and nfs-kernel-server for NFS-backed storage and backup targets.

Longhorn Uno StorageClass

The KBVE StorageClass — replica count, data locality, reclaim policy, and the parameters worth tuning.

Namespace

Create the dedicated storage namespace that holds production data resources.

Start here

Overview

Longhorn is a cloud-native, distributed block storage system for Kubernetes (originally by Rancher, now a CNCF project). It turns the local disks across your nodes into replicated, persistent volumes — with snapshots and backups to NFS or S3 — all managed through Kubernetes CRDs and a built-in UI.

Every volume is synchronously replicated across nodes, so a single node failure doesn’t lose data.

This guide covers install, NFS setup, the namespace, and the StorageClass.

Helm path

Install

• This current information sheet is in reference to Longhorn 1.3v , be aware that 1.4v will be in production around 2023. Thus this might become obsolete information.

• Before installing, look over the requirements for storage.

• Requirements for 1.3v Longhorn

The recommended install path is Helm. Every node needs open-iscsi and a compatible kernel first:

# On each node (Debian/Ubuntu)
sudo apt-get install open-iscsi -y

# Install Longhorn via Helm
helm repo add longhorn https://charts.longhorn.io
helm repo update
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system --create-namespace

Caution

Longhorn needs open-iscsi running on every node that will host a replica. A missing iSCSI daemon is the most common cause of volumes stuck in Attaching.

Backup target prep

NFS

• Ubuntu NFS Setup

  • Make sure system is updated / upgrade

    • sudo apt-get update && sudo apt-get upgrade -y

  • Install nfs-common and nfs-kernel-server

    • sudo apt-get install nfs-common nfs-kernel-server -y

Production home

Namespace

• Creating a custom namespace to hold the storage.

  Kubectl command to create the namespace:

  • kubectl create namespace storage

  • std out: namespace/storage created

• This namespace will be where we store our production data.

StorageClass

Longhorn Uno

Under storage class, we will be creating the longhorn uno and then deploying it under that.

 annotations:
    longhorn.io/last-applied-configmap: |
      kind: StorageClass
      apiVersion: storage.k8s.io/v1
      metadata:
        name: longhorn-uno
        annotations:
          storageclass.kubernetes.io/is-default-class: "true"
      provisioner: driver.longhorn.io
      allowVolumeExpansion: true
      reclaimPolicy: "Delete"
      volumeBindingMode: Immediate
      parameters:
        numberOfReplicas: "1"
        staleReplicaTimeout: "30"
        fromBackup: ""
        fsType: "ext4"
        dataLocality: "best-effort"
        unmapMarkSnapChainRemoved: "ignored"
        disableRevisionCounter: "true"
        dataEngine: "v1"
    storageclass.beta.kubernetes.io/is-default-class: 'false'
    storageclass.kubernetes.io/is-default-class: 'false'

The key parameters: numberOfReplicas controls how many synchronous copies of the volume exist (raise to 3 for HA), dataLocality: best-effort keeps a replica on the same node as the workload to cut latency, and reclaimPolicy: Delete removes the underlying volume when its PVC is deleted.

Questions

Frequently asked

What is Longhorn?

Longhorn is a cloud-native, distributed block storage system for Kubernetes, originally by Rancher and now a CNCF project. It provides persistent volumes with synchronous replication across nodes, snapshots, and backups to external targets like NFS or S3, all managed through a Kubernetes-native UI and CRDs.

How does Longhorn replicate data?

Longhorn creates a replica of each volume on multiple nodes and writes to them synchronously, so the volume survives a node failure. The number of copies is set by the numberOfReplicas parameter on the StorageClass — for example 3 for high availability, or 1 for single-node or non-critical data.

How do I install Longhorn on Kubernetes?

The recommended path is Helm — add the longhorn repo, then helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace. Every node needs open-iscsi installed and a compatible kernel. You can also apply the official YAML manifest directly with kubectl.

Does Longhorn support backups?

Yes. Longhorn takes in-cluster snapshots of a volume and can back them up to an external backup target such as an NFS share or an S3-compatible bucket. Backups are incremental after the first full copy and can be restored to a new volume in the same or another cluster.

What is a Longhorn StorageClass?

A StorageClass tells Kubernetes to provision volumes with Longhorn's CSI driver (driver.longhorn.io) and carries parameters like numberOfReplicas, staleReplicaTimeout, fsType, and dataLocality. Marking it the default class lets PersistentVolumeClaims use Longhorn automatically without naming it.

Keep exploring

Related applications

KubernetesThe cluster orchestration layer Longhorn provisions volumes for.ProxmoxVirtualization host layer underneath many KBVE nodes.LinuxLVM, filesystems, and the sysadmin skills behind node disks.