Longhorn

Cloud-native distributed block storage for Kubernetes.

Longhorn is a CNCF graduated project that provides distributed block storage for Kubernetes using replicated volumes stored on node-local disks. It supports volume snapshots, cross-node replication, scheduled backups to S3, and volume encryption. It is used in this cluster as the primary ReadWriteOnce storage class for stateful workloads that need persistent block storage with replication and encryption.

Alternatives considered

Self Hosted

Tool	Open Source	Full Features	Notes
Rook-Ceph	Yes	Yes	Ceph-based; more complex but supports RWX natively
OpenEBS	Yes	Yes	Multiple engines (Jiva, Mayastor); lighter weight
democratic-csi	Yes	Yes	Delegates to NFS/iSCSI on external storage

Installation

Architecture

HelmRelease longhorn in namespace longhorn-system, chart version 1.11.0 from https://charts.longhorn.io. Namespace labeled privileged pod security (required for DaemonSet components). Default replica count: 3. Default data path: /var/mnt/longhorn. CSI components (attacher, provisioner, resizer, snapshotter) run 2 replicas each. Longhorn UI runs 1 replica. defaultClass: false — Longhorn is not set as the default StorageClass. Image tags pinned to v1.11.0-hotfix-1 for manager and instanceManager as a temporary hotfix.

Security

Namespace enforces privileged pod security policy (required for Longhorn's node DaemonSet that mounts host volumes). RBAC is cluster-wide. Volume encryption is handled per-StorageClass using LUKS with secrets managed via SOPS.

Updates

Managed by Renovate. Chart version is semver-pinned (1.11.0). Image tags currently overridden to v1.11.0-hotfix-1 pending upstream fix.

Administration

Usage

Applications request storage by creating PVCs with the Longhorn StorageClass (or the encrypted variant). Longhorn provisions volumes backed by replicated block devices across nodes. Snapshots are created via VolumeSnapshot resources. k8up is used for off-cluster backups of Longhorn PVC data to S3. The Longhorn UI (available in longhorn-system) provides a visual overview of volumes, nodes, and replica health.

Cluster-specific deviations from the above live in the per-cluster README — see k8s/infrastructure/talos/controllers/longhorn/README.md.

Cluster Deployment

Used by on this cluster

• audiobookshelf
• baserow
• bichon
• filebrowser
• fileflows
• gitea
• immich
• jellyfin
• komga
• lldap
• memos
• n8n
• navidrome
• ntfy
• outline
• paperless
• pocketid
• privatebin
• romm
• tandoor
• tube-archivist
• vaultwarden
• vikunja

Longhorn — Talos cluster

Cluster-specific notes only. General product info, "why we use it", and alternatives live in docusaurus/docs/platform/longhorn.mdx.

Deviations from defaults

Defaults live in docusaurus/docs/platform/longhorn.mdx — document anything this cluster does differently here, with a one-line reason.

Kubernetes Metadata

• HelmRelease: longhorn@1.12.0
• HelmRepo: longhorn (https://charts.longhorn.io)

Rendered manifests (kustomize build)

apiVersion: v1
data:
  values.yaml: |
    defaultSettings:
      defaultReplicaCount: "3"
      storageReservedPercentageForDefaultDisk: "1"
      defaultDataPath: "/var/mnt/longhorn"
    persistence:
      defaultClass: false
      defaultClassReplicaCount: "1"
    preUpgradeChecker:
      jobEnabled: false
      # v1.110 Hotfix  -> TODO: Remove
      # https://github.com/longhorn/longhorn/releases/tag/v1.11.0
      upgradeVersionCheck: false
    longhornUi:
      replicas: "1"
    csi:
      attacherReplicaCount: "2"
      provisionerReplicaCount: "2"
      resizerReplicaCount: "2"
      snapshotterReplicaCount: "2"
    # v1.110 Hotfix  -> TODO: Remove
    # https://github.com/longhorn/longhorn/releases/tag/v1.11.0
    #image:
    #  longhorn:
    #    instanceManager:
    #      tag: v1.11.0-hotfix-1
    #    manager:
    #      tag: v1.11.0-hotfix-1
kind: ConfigMap
metadata:
  name: longhorn-values-b5mgf9bd9f
  namespace: longhorn-system