Skip to content

Reference

Scope

Look-up facts for Longhorn: release and support matrix, host requirements, V1 vs V2 feature support, setting defaults, backup target URL formats, network ports, limits, and published benchmark and scalability numbers. Unless noted, the values are for Longhorn v1.12.1 (2026-08-14). For tasks, see How-to Guides. For internals, see Explanation.

Release and Support Matrix

The upstream README tracks each release branch. A branch marked active gets periodic patch releases. Upstream policy: a release branch reaches EOL one year after its first stable version.

Branch Latest patch (chart date) First minor release (chart date) Status (2026-09) Headline change
1.12 1.12.1 (2026-08-14) 1.12.0 (2026-06-02) Active V2 Data Engine GA, IPv6 for V2, dual-stack, topology-aware PV node affinity, internal NetworkPolicies on by default (1.12.1), experimental storage sharding (1.12.1)
1.11 1.11.3 (2026-07-02) 1.11.0 (2026-01-29) Active V2 Data Engine enters Technical Preview, V1 parallel replica rebuild, balance-aware scheduling, S.M.A.R.T. disk health, RWOP access mode
1.10 1.10.2 (2026-01-28) 1.10.0 (2025-09-25) Not active V2 interrupt mode, V2 without hugepages, unified V1/V2 settings (JSON), single-stack IPv6 (V1), longhorn.io/v1beta1 API removed
1.9 1.9.2 (2025-09-24) 1.9.0 (2025-05-27) Not active TBD (not re-verified in this refresh)
1.8 1.8.2 (2025-06-09) 1.8.0 (2025-01-22) Not active Multiple backup targets (BackupTarget CR), Kubernetes minimum raised to v1.25
1.7 1.7.3 (2025-02-19) 1.7.0 (2024-08-20) Not active Kubernetes minimum v1.21

Dates

Dates are the created timestamps of the chart entries in the official Helm repository index (longhorn/charts gh-pages branch). They match the GitHub release pages for v1.12.0 (June 2) and v1.12.1 (August 14). Minor releases have landed roughly every four to five months (2025-01, 2025-05, 2025-09, 2026-01, 2026-06). A v1.13 date is TBD. The v1.12.1 docs say only that V2 live upgrade support is "planned" for the v1.12 to v1.13 upgrade.

Upgrade path rules

Current version Target version Supported Example
x.y.* x.(y+1).* Yes v1.11.3 to v1.12.1
x.y.* x.y.(*+n) Yes v1.12.0 to v1.12.1
x.(y-1).* x.(y+1).* No, blocked by the upgrade path check (since v1.5.0) v1.10.2 to v1.12.1
Any Older version No, downgrade prevention (since v1.5.0) v1.12.1 to v1.11.3

Host and Cluster Requirements

Common requirements (V1 and V2)

Requirement Value (v1.12.1)
Kubernetes >= v1.25 (install page and chart kubeVersion: >=1.25.0-0). Tested with Kubernetes 1.33 to 1.36
CPU architecture AMD64, ARM64
Container runtime Any Kubernetes-compatible runtime (docs cite Docker v1.13+, containerd v1.3.7+)
Host tools bash, curl, findmnt, grep, awk, blkid, lsblk
Mount propagation Must be enabled
NFS client NFSv4 client on every node. RWX needs NFSv4.1. NFS backup targets need NFSv4, v4.1 or v4.2
Encryption dm_crypt module plus cryptsetup (LUKS2)
Device mapper dmsetup / device-mapper package
Privileges Longhorn pods run as root with privileged access to host paths (/dev, /proc, /var/lib/longhorn, kubelet dirs)

Doc inconsistency

The v1.12.1 best-practices page still says "at least v1.21". The install page, the v1.12.1 important notes and the Helm chart all require v1.25. Treat v1.25 as the minimum.

V1 Data Engine requirements

Requirement Value
Frontend iSCSI. Needs open-iscsi with iscsid running and the iscsi_tcp module loaded
Disk type Filesystem-type disks, default path /var/lib/longhorn
Host filesystem ext4 or XFS (must support file extents)
Known-bad package Avoid open-iscsi 2.1.12. Use <= 2.1.11 or >= 2.1.13 (Longhorn issue #13733)

V2 Data Engine requirements

Requirement Value
CPU AMD64 needs SSE4.2. ARM64 is supported (use AIO disks, see known issue below)
Kernel 5.19+ for NVMe/TCP. 6.7+ recommended for stability (SPDK issue #3116)
Kernel modules vfio_pci, uio_pci_generic, nvme-tcp
Huge pages 2 GiB of 2 MiB pages (1024 pages) per node by default. Since v1.10, can be turned off (data-engine-hugepage-enabled)
Dedicated CPU spdk_tgt busy-polls. Default mask 0x3 = 2 cores since v1.12.0 (was 0x1)
Disks Raw block-type disks. Local NVMe strongly recommended. NVMe must be isolatable in its IOMMU group for vfio-pci, otherwise use AIO mode
Frontends NVMe-TCP (default). UBLK is experimental and can kernel-panic on kernel 6.17
Upgrade No live upgrade. Detach V2 volumes before upgrading between 1.12 patch releases
Engine Nodes CPU per node Memory per node Disk
V1 3 4 vCPU 4 GiB SSD/NVMe recommended. HDD "verified" but latency-sensitive
V2 (in addition to V1) 3 +1 dedicated core per V2 instance-manager pod +2 GiB for huge pages Local NVMe strongly recommended

Production recommendations from the same page: 10 Gbps between nodes, a dedicated disk (not the root disk), a dedicated storage network (Multus), and CoreDNS with at least 2 replicas.

Verified operating systems (v1.12.1 test cycle)

OS Version
Ubuntu 26.04
SUSE Linux Enterprise Server 16.0
SUSE Linux Enterprise Micro 6.1
Red Hat Enterprise Linux 10.1
Oracle Linux 10.0
Rocky Linux 10.1
Talos Linux 1.11.5
Container-Optimized OS (GKE) 125

Known-broken kernels for RWX mounts: vanilla 6.5.6, Ubuntu 5.15.0-94, 6.5.0-21 and 6.5.0-1014-aws.

V1 vs V2 Feature Support (v1.12.1)

Subset of the upstream Data Engine Comparison page. V2 assumes the default replicated layout. The experimental sharded (erasure-coded) layout lacks backup, cloning, DR volumes and live migration.

Feature V1 V2 Note
Snapshot, backup and restore, DR volume Yes Yes
System backup and restore Yes Yes
RWX volumes (incl. encryption) Yes Yes
Volume expansion, cloning, encryption, trim Yes Yes
Fast (linked) volume cloning Not planned Yes New linked-clone design in 1.12.1. Pre-1.12.1 V2 linked clones are legacy
Data locality strict-local Yes No disabled and best-effort work on both
Online full, delta and fast rebuild Yes Yes
Offline fast rebuild Yes No
QoS No Yes
Backing images Yes Removed in 1.12.0 Use Containerized Data Importer (CDI)
Revision counter Yes No
Engine live upgrade Yes No Planned for the 1.12 to 1.13 upgrade
IPv4 / IPv6 / storage network Yes Yes Dual-stack needs the same IP-family order on all nodes

Selected Setting Defaults (v1.12.1)

Since v1.10, many settings take a JSON value per engine, for example {"v1":"3","v2":"3"}. Settings that take one value for all engines use a plain string.

Setting (UI name) Default Note
Default Replica Count {"v1":"3","v2":"3"} Use 3 with 3 or more storage nodes, else 2
Default Data Locality disabled Best practice: best-effort
Replica Node Level Soft Anti-Affinity false Keep false in production
Replica Auto Balance disabled least-effort / best-effort available
Storage Over Provisioning Percentage 100
Storage Minimal Available Percentage 25
Guaranteed Instance Manager CPU {"v1":"12","v2":"12"} Percent of allocatable node CPU
Concurrent Replica Rebuild Per Node Limit 5
Offline Replica Rebuilding false
Snapshot Maximum Count 250 Hard limit is 254 (one-byte read index)
Default Backup Block Size 2 (MiB) 2 or 16 supported
Node Drain Policy block-if-contains-last-replica
V1 Data Engine true
V2 Data Engine false Enable explicitly
Data Engine CPU Mask {"v2":"0x3"} 2 cores since v1.12.0
Data Engine Hugepage Enabled {"v2":"true"}
Data Engine Memory Size {"v2":"2048"} (MiB)
Data Engine Interrupt Mode Enabled {"v2":"false"} Trades IOPS for lower idle CPU
RWX Volume Fast Failover (experimental) false Shortens NFS grace period from 90 s to 30 s

Helm chart values of note: networkPolicies.restrictInternalTraffic: true (internal NetworkPolicies, v1.12.1), networkPolicies.enabled: false (UI policy), persistence.defaultClassReplicaCount: 3, defaultBackupStore.backupTarget / backupTargetCredentialSecret / pollInterval.

Backup Target URL Formats

Since v1.8.0 Longhorn supports multiple backup targets (BackupTarget CRs). The default target is created at install and always holds system backups.

Backupstore URL format Credential secret keys (examples)
AWS S3 / S3-compatible s3://<bucket>@<region>/[path/] AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINTS (non-AWS endpoints)
GCP Cloud Storage s3://<bucket>@us/ via the S3 interoperability API HMAC key in the AWS-style keys
NFS nfs://<server>:/<export>[?nfsOptions=...] None (network controls only)
SMB/CIFS cifs://<server>/<share>[?cifsOptions=...] CIFS_USERNAME, CIFS_PASSWORD
Azure Blob Storage azblob://<container>@core.windows.net/[path/] AZBLOB_ACCOUNT_NAME, AZBLOB_ACCOUNT_KEY

Retention

Longhorn manages the backup lifecycle itself. Upstream docs say that any retention or lifecycle policy set directly on the backupstore is strictly prohibited.

Other secret keys

The v1.12.1 docs also define AWS_CERT (custom CA for S3), AWS_IAM_ROLE_ARN (kube2iam/kiam), AZBLOB_ENDPOINT and AZBLOB_CERT. GCS uses an HMAC key mapped to AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, with the Storage URI in AWS_ENDPOINTS.

Backup and Snapshot Data Facts

Fact Value
Backup block size 2 MiB by default (16 MiB optional since v1.10). Each .blk file is compressed and addressed by checksum
Backup metadata volume.cfg per backup volume plus one small .cfg per backup (offsets and checksums)
Deduplication Unchanged blocks are shared across backups of the same volume
Read index 1 byte per 4 KiB block per replica. A 1 TiB volume uses about 256 MiB of RAM per replica
Snapshots per volume 254 hard limit. Default maximum setting is 250
Consistency Crash-consistent. Longhorn runs sync before a snapshot. Optional filesystem freeze (kernel 5.17+ recommended)
System backup contents BackingImages, ClusterRoles/Bindings, ConfigMaps, CRDs, DaemonSets, Deployments, EngineImages, PVs, PVCs, RecurringJobs, Roles/Bindings, Settings, Services, ServiceAccounts, StorageClasses, Volumes. Not Longhorn Node CRs
System backup volume policy if-not-present, always, disabled
Recurring job tasks snapshot, snapshot-force-create, snapshot-cleanup, snapshot-delete, backup, backup-force-create, filesystem-trim, system-backup

Network Ports

From the upstream Longhorn Networking reference (v1.12.1). Use it when writing NetworkPolicies.

Component Port(s) Direction and purpose
longhorn-manager 9500/TCP API: UI, CSI plugin, recurring-job pods, other managers
Conversion webhook 9501/TCP Called by kube-apiserver
Admission webhook 9502/TCP Called by kube-apiserver
Recovery backend 9503/TCP NFS lock-recovery client info. Only share-manager pods may connect
instance-manager services 8500 process-manager, 8501 proxy, 8502 disk, 8503 instance, 8504 spdk From longhorn-manager
instance-manager data path 10000-30000/TCP Engine to replica traffic between instance managers
iSCSI (V1 frontend) 3260/TCP From nodes in the cluster
share-manager (RWX) 2049/TCP NFS from cluster nodes
backing-image-manager 8000/TCP, 30001-31000/TCP From manager, between backing image managers
backing-image-data-source 8000/TCP, 8002/TCP
longhorn-frontend Service (UI) 80/TCP User-defined ingress

V2 NVMe-TCP port

The networking reference does not list a separate NVMe/TCP listener port for V2. Port 4420, cited in older notes, is the generic NVMe/TCP default. It is TBD (not verified) for Longhorn.

Custom Resources (longhorn.io/v1beta2)

The longhorn.io/v1beta1 API was removed in v1.10.0.

CRD Purpose
volumes, engines, replicas Volume and its data-plane instances
volumeattachments Attachment tickets (CSI, backup, clone, upgrade) per volume
nodes, instancemanagers, engineimages Node and disk config, per-node instance-manager pods, engine binaries
snapshots, backups, backupvolumes, backuptargets, backupbackingimages Snapshot and backup objects
recurringjobs Scheduled snapshot, backup, trim and system-backup jobs
systembackups, systemrestores Longhorn system backup and restore
sharemanagers RWX NFS server per volume
backingimages, backingimagemanagers, backingimagedatasources Backing images (V1 only since 1.12.0)
settings, supportbundles, orphans Global settings, diagnostics, orphaned data
enginefrontends, shardgroups, shards New in the v1.12.1 manifest. The shard CRDs back the experimental sharding layout. enginefrontends is not described in this refresh (TBD)

Volume Encryption Secret Keys

Key Default Meaning
CRYPTO_KEY_VALUE none Passphrase
CRYPTO_KEY_PROVIDER secret Key provider
CRYPTO_KEY_CIPHER aes-xts-plain64 dm-crypt cipher
CRYPTO_KEY_HASH sha256 Passphrase hash
CRYPTO_KEY_SIZE 256 Key size in bits
CRYPTO_PBKDF argon2i LUKS keyslot PBKDF (PBKDF2 in FIPS mode)
CRYPTO_PBKDF_FORCE_ITERATIONS 200000 Fixed iteration count
CRYPTO_PBKDF_MEMORY 0 Argon2 memory cost (KB)

Since v1.12.0 (V1) and v1.12.1 (new V2 volumes), Longhorn reserves an extra 16 MiB of raw capacity for LUKS2 metadata, so an encrypted volume exposes its full requested size.

Hardening Checklist

  • Keep networkPolicies.restrictInternalTraffic=true (default in v1.12.1) on a CNI that enforces NetworkPolicy. Validated combinations: K3s with Flannel, Calico or Cilium, and RKE2 with Canal, Calico or Cilium.
  • Set networkPolicies.kubeAPIServerSourceCIDRs to exact /32 or /128 API server source addresses, never a whole PodCIDR.
  • Configure the longhorn-grpc-tls secret to enforce mTLS on instance-manager gRPC (full coverage in v1.12.1).
  • Expose the UI only through an authenticated ingress. The UI has no built-in authentication.
  • Use encrypted StorageClasses for sensitive data. Back up the encryption Secrets separately, because restores need the same key.
  • Restrict egress from Longhorn nodes to the backupstore endpoint. Use least-privilege IAM for S3 (PutObject, GetObject, ListBucket, DeleteObject on one bucket).
  • Put replica traffic on a dedicated storage network (Multus storage-network setting).
  • Take a system backup before every upgrade.

RBAC scope by component

Component Access scope
Longhorn Manager DaemonSet CRUD on Longhorn CRs, access to Kubernetes node and pod APIs
Longhorn CSI Driver CSI secret access, PV/PVC watch, node publish operations
Longhorn UI Talks only to the Longhorn Manager API (port 9500). It holds no Kubernetes API permissions of its own
Instance Manager Managed by the Manager. No direct Kubernetes API access

Benchmarks and Scalability

Official reference setup (V1, Longhorn v1.6.0/v1.6.1)

Source: the upstream report "Reference Setup, Performance, Scalability, and Sizing Guidelines: Public Cloud, Medium Node Spec" in the longhorn/longhorn repo. Test conditions: AWS m5zn.2xlarge workers (8 vCPU, 32 GB), 10 Gbps baseline network (~0.3 ms RTT), one dedicated EBS gp3 disk per node (1 TB, 10,000 IOPS, 360 MiB/s, ext4), Ubuntu 22.04 (kernel 6.2), RKE2 v1.27.10 with Calico, 3 replicas per volume, measured with kbench (fio).

Metric (single volume) Value
Random read IOPS 22,180
Sequential read IOPS 39,772
Random write IOPS 1,150
Sequential write IOPS 2,340
Random / sequential read bandwidth 874 / 669 MiB/s
Random / sequential write bandwidth 159 / 291 MiB/s
Random read / write latency (min) 750 / 2,040 µs
Metric (all volumes, 3 workers) Value
Random read IOPS ~31,700
Sequential read IOPS ~62,500
Random write IOPS ~5,250
Sequential write IOPS ~10,400
Read / write bandwidth ~1,150 / ~380 MiB/s

The aggregate numbers scaled linearly with worker count in the report. With 3 replicas, reads can be served from all replicas, so aggregate reads reach the combined EBS limit. Writes pay the 3x replication cost.

Control-plane scale test (1 control plane node + N workers, v1.6.1) Max pods with one volume each Volumes per node Replicas per node
3 workers 699 233 669
6 workers 1,114 185 557
9 workers 1,561 173 520

Maximum volume size is bounded by replica rebuild time, which Longhorn caps at 24 h. The report measured about 30 TiB/x for full-data volumes and 772 GiB/x for the worst-case 4K data/hole pattern, where x is the maximum snapshot count including the volume head.

Scope of these numbers

These are V1 numbers on one cloud setup and an older release. V2 (SPDK) figures are published on the upstream Performance Benchmark wiki and in an arXiv paper on UBLK optimisation (2502.14419). They were not re-tabulated here. Run kbench on your own hardware before capacity planning.

Earlier vault estimates (unsourced)

The earlier version of this topic carried the tables below. They were not measured under documented conditions. They are kept for context only. Prefer the official report above.

Configuration Seq Read Seq Write Random 4K Read Random 4K Write
1 replica 500-800 MB/s 300-500 MB/s 15k IOPS 8k IOPS
2 replicas 500-800 MB/s 200-350 MB/s 15k IOPS 5k IOPS
3 replicas 500-800 MB/s 150-300 MB/s 15k IOPS 3k IOPS
Component CPU Memory Per
Longhorn Manager 100-300m 256-512Mi Per node
Engine (per volume) 50-200m 100-200Mi Per volume
Replica (per replica) 50-100m 100-200Mi Per replica

Sources