Security¶

Longhorn provides volume-level encryption using Linux dm-crypt, integrates with Kubernetes RBAC for API access control, and supports network policies to isolate storage traffic. As a Kubernetes-native system, Longhorn inherits much of its security posture from the cluster's own security configuration.

See also: index, architecture, operations

Volume Encryption (LUKS/dm-crypt)¶

Longhorn supports per-volume encryption for both Filesystem and Block volume modes, protecting data against unauthorized access, physical disk theft, and compliance violations.

How It Works¶

Longhorn volume encryption relies on three Linux/Kubernetes components:

dm-crypt (Linux kernel module): Creates and manages encrypted block devices.
cryptsetup (CLI utility): Formats and opens encrypted devices using the LUKS header.
Kubernetes Secrets: Store encryption keys and are referenced by the StorageClass.

When a volume is provisioned with encryption enabled:

The CSI driver reads the encryption secret (passphrase and cipher configuration) from the referenced Kubernetes Secret.
On node staging, cryptsetup opens the underlying Longhorn block device using the secret.
The resulting decrypted device is formatted and mounted into the Pod.
On detach, the encrypted device is closed, leaving only ciphertext on disk.

Encryption Secret Format¶

Longhorn encryption secrets are stored as Kubernetes Secrets in the longhorn-system namespace. Each secret requires:

Key value field: The actual passphrase used to encrypt/decrypt the volume.
Provider field: Typically set to secret for Kubernetes Secret-based key management.
Cipher specification: dm-crypt cipher configuration (e.g., AES with XTS mode).
Hash algorithm: Used for key derivation from the passphrase (typically SHA-256 or better).
Key size: Key length in bits (typically 256 for modern deployments).
PBKDF: Password-based key derivation function (e.g., Argon2i for better security against brute-force).

Refer to Longhorn's official documentation for the complete encryption secret schema and example templates.

StorageClass Configurations¶

Longhorn supports two encryption strategies:

Global encryption key (one key for all volumes):

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: longhorn-crypto-global
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "3"
  encrypted: "true"
  csi.storage.k8s.io/provisioner-secret-name: "longhorn-crypto"
  csi.storage.k8s.io/provisioner-secret-namespace: "longhorn-system"
  csi.storage.k8s.io/node-publish-secret-name: "longhorn-crypto"
  csi.storage.k8s.io/node-publish-secret-namespace: "longhorn-system"
  csi.storage.k8s.io/node-stage-secret-name: "longhorn-crypto"
  csi.storage.k8s.io/node-stage-secret-namespace: "longhorn-system"

Per-volume encryption key (unique key per PVC):

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: longhorn-crypto-per-volume
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "3"
  encrypted: "true"
  csi.storage.k8s.io/provisioner-secret-name: "${pvc.name}"
  csi.storage.k8s.io/provisioner-secret-namespace: "${pvc.namespace}"
  csi.storage.k8s.io/node-publish-secret-name: "${pvc.name}"
  csi.storage.k8s.io/node-publish-secret-namespace: "${pvc.namespace}"
  csi.storage.k8s.io/node-stage-secret-name: "${pvc.name}"
  csi.storage.k8s.io/node-stage-secret-namespace: "${pvc.namespace}"

The ${pvc.name} and ${pvc.namespace} template variables are expanded by the CSI driver at provisioning time, allowing each PVC to reference its own unique encryption Secret.

Encrypted Backups

Backups created from encrypted volumes are also encrypted. The backup data stored in the external backupstore (S3 or NFS) contains ciphertext, not plaintext.

Online Expansion of Encrypted Volumes

For Kubernetes v1.25-v1.28, the CSINodeExpandSecret feature gate must be enabled for online expansion of encrypted volumes. Kubernetes v1.29+ supports this natively. The node-expand-secret-name and node-expand-secret-namespace parameters must be specified in the StorageClass.

CSI Driver Security¶

The Longhorn CSI driver operates as a Kubernetes CSI plugin with the following security properties:

Sidecar containers: External provisioner, attacher, resizer, and snapshotter sidecars handle CSI RPC calls and communicate with the Longhorn Manager via the Longhorn API.
Secret handling: Encryption keys and credentials are passed through the CSI secret mechanism, never logged or exposed in CRD status fields.
Node operations: The CSI node plugin runs on each node and performs device attachment, formatting, and mounting. It requires privileged access to the host for block device management.
Identity: The CSI driver uses the Longhorn Manager ServiceAccount, which should have the minimum required RBAC permissions.

RBAC and Kubernetes API Access¶

Longhorn defines several ClusterRoles and ClusterRoleBindings for its components:

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	Read/write access to Longhorn CRs (mirrors Manager permissions)
Instance Manager	Managed by the Manager; no direct API access

Best practices:

Deploy Longhorn in its own namespace (longhorn-system) to isolate its resources.
Use Kubernetes NetworkPolicies to restrict ingress to the Longhorn Manager API.
Restrict access to the Longhorn UI via an ingress controller with authentication.
Audit the ClusterRole bindings periodically to ensure least privilege.

Network Policies¶

Longhorn does not ship with default NetworkPolicies. Administrators should create policies to:

Isolate storage traffic: Restrict inter-node replica traffic (TCP port 9500-9505 for V1 data plane) to only Longhorn nodes.
Protect the Manager API: Allow CSI driver and UI traffic to the Manager (TCP port 9500), deny all other namespaces.
Restrict CSI communication: Only allow CSI sidecars to communicate with the Longhorn Manager Service.
Control backup traffic: If backups go to S3, restrict egress from Longhorn nodes to only the backup target endpoint.

For the V2 Data Engine, additional considerations apply:

NVMe-TCP traffic uses port 4420 by default.
UBLK uses a Unix domain socket on the host.
SPDK requires huge pages and VFIO/UIO device access, which increases the host attack surface.

Backup Encryption¶

Backups created from encrypted volumes retain their encrypted state in the backupstore. This means:

The backup target (S3 bucket or NFS share) stores ciphertext.
To restore, the same encryption secret must be available in the target cluster.
Backup blocks are transmitted over the network in encrypted form.

For backup target authentication, Longhorn supports:

S3: AWS access key and secret key stored in a Kubernetes Secret referenced by the backup target settings.
NFS: No built-in authentication beyond NFS export rules. Use network-level controls.

Backing Image Encryption¶

Longhorn supports encrypting backing images used as volume templates. The encrypted backing image is stored with a LUKS header, and volumes cloned from it inherit the encryption. The encryption secret is specified in the StorageClass via the backingImage parameter along with the CSI secret references.

Threat Model Summary¶

Threat	Mitigation
Data exposure from stolen disks	Volume-level LUKS encryption
Unauthorized API access	Kubernetes RBAC, namespace isolation
Network interception of replica traffic	Deploy on a private storage network; apply NetworkPolicies
Compromised backup target	Encrypted backups; S3 bucket policies
Privilege escalation via CSI driver	Pod Security Standards; restricted ServiceAccount RBAC
Host-level attack via V2 SPDK	VFIO device isolation; huge pages reservation limits