StorageClass Parameters

Overview

Storage Class as a resource object has a number of settable parameters. Here’s a sample YAML:

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: longhorn-test
provisioner: driver.longhorn.io
allowVolumeExpansion: true
reclaimPolicy: Delete
volumeBindingMode: Immediate
parameters:
  numberOfReplicas: "3"
  staleReplicaTimeout: "2880"
  fromBackup: ""
  fsType: "ext4"
#  mkfsParams: ""
#  migratable: false
#  encrypted: false
#  dataLocality: "disabled"
#  replicaAutoBalance: "ignored"
#  diskSelector: "ssd,fast"
#  nodeSelector: "storage,fast"
#  recurringJobSelector: '[{"name":"snap-group", "isGroup":true},
#                          {"name":"backup", "isGroup":false}]'
#  backingImageName: ""
#  backingImageChecksum: ""
#  backingImageDataSourceType: ""
#  backingImageDataSourceParameters: ""
#  unmapMarkSnapChainRemoved: "ignored"
#  disableRevisionCounter: false
#  replicaSoftAntiAffinity: "ignored"
#  replicaZoneSoftAntiAffinity: "ignored"
#  replicaDiskSoftAntiAffinity: "ignored"
#  nfsOptions: "soft,timeo=150,retrans=3"
#  v1DataEngine: true
#  v2DataEngine: false
#  freezeFSForSnapshot: "ignored"

Built-in Fields

Some fields are common to all Kubernetes storage classes. See also Kubernetes Storage Class.

Provisioner (field: provisioner)

Specifies the plugin that will be used for dynamic creation of persistent volumes. For Longhorn, that is always "driver.longhorn.io".

See Kubernetes Storage Class: Provisioner.

Allow Volume Expansion (field: allowVolumeExpansion)

Default: true See Kubernetes Storage Class: Allow Volume Expansion.

Reclaim Policy (field: reclaimPolicy)

Default: Delete See Kubernetes Storage Class: Reclaim Policy.

Mount Options (field: mountOptions)

Default [] See Kubernetes Storage Class: Mount Options.

Volume Binding Mode (field: volumeBindingMode)

Default Immediate See Kubernetes Storage Class: Volume Binding Mode.

Longhorn-specific Parameters

Note that some of these parameters also exist and may be specified in global settings. When a volume is provisioned with Kubernetes against a particular StorageClass, StorageClass parameters override the global settings. These fields will be applied for new volume creation only. If a StorageClass is modified, neither Longhorn nor Kubernetes is responsible for propagating changes to its parameters back to volumes previously created with it.

Number Of Replicas (field: parameters.numberOfReplicas)

Default: 3

The desired number of copies (replicas) for redundancy.

  • Must be between 1 and 20.

  • Replicas will be placed across the widest possible set of zones, nodes, and disks in a cluster, subject to other constraints, such as NodeSelector.

Global setting: Default Replica Count.

Stale Replica Timeout (field: parameters.staleReplicaTimeout)

Default: 30

Minutes after a replica is marked unhealthy before it is deemed useless for rebuilds and is just deleted.

From Backup (field: parameters.fromBackup)

Default: "" Example: "s3://backupbucket@us-east-1?volume=minio-vol01&backup=backup-eeb2782d5b2f42bb"

URL of a backup to be restored from.

FS Type (field: parameters.fsType)

Default: ext4 For more details, see Creating Longhorn Volumes with Kubernetes

Mkfs Params (field: parameters.mkfsParams)

Default: "" For more details, see Creating Longhorn Volumes with Kubernetes

Migratable (field: parameters.migratable)

Default: false

Allows for a Longhorn volume to be live migrated from one node to another. Useful for volumes used by Harvester.

Encrypted (field: parameters.encrypted)

Default: false More details in Encrypted Volumes

Data Locality (field: parameters.dataLocality)

Default: disabled

If enabled, try to keep the data on the same node as the workload for better performance.

  • For "best-effort", a replica will be co-located if possible, but is permitted to find another node if not.

  • For "strict-local" the Replica count should be 1, or volume creation will fail with a parameter validation error.

  • If "strict-local" is not possible for whatever other reason, volume creation will be failed. A "strict-local" replica that becomes displaced from its workload will be marked as "Stopped".

Global setting: Default Data Locality More details in Data Locality.

Replica Auto-Balance (field: parameters.replicaAutoBalance)

Default: ignored

If enabled, move replicas to more lightly-loaded nodes.

  • "ignored" means use the global setting.

  • Other options are "disabled", "least-effort", "best-effort".

Global setting: Replica Auto Balance More details in Auto Balance Replicas.

Disk Selector (field: parameters.diskSelector)

Default: "" Example: "ssd,fast"

A list of tags to select which disks are candidates for replica placement.

More details in Storage Tags

Node Selector (field: parameters.nodeSelector)

Default: "" Example: "storage,fast"

A list of tags to select which nodes are candidates for replica placement.

More details in Storage Tags

Recurring Job Selector (field: parameters.recurringJobSelector)

Default: "" Example: [{"name":"backup", "isGroup":true}]

A list of recurring jobs that are to be run on a volume.

More details in Create a Recurring Snapshot or Backup Job

Backing Image Name (field: parameters.backingImageName)

Default: "" See Backing Image

Backing Image Checksum (field: parameters.backingImageChecksum)

Default: "" See Backing Image

Backing Image Data Source Type (field: parameters.backingImageDataSourceType)

Default: "" See Backing Image

Backing Image Data Source Parameters (field: parameters.backingImageDataSourceParameters)

Default: "" See Backing Image

Unmap Mark Snap Chain Removed (field: parameters.unmapMarkSnapChainRemoved)

Default: ignored

  • "ignored" means use the global setting.

  • Other values are "enabled" and "disabled".

Global setting: Remove Snapshots During Filesystem Trim. More details in Trim Filesystem.

Disable Revision Counter (field: parameters.disableRevisionCounter)

Default: true

Global setting: Disable Revision Counter. More details in Revision Counter.

Replica Soft Anti-Affinity (field: parameters.replicaSoftAntiAffinity)

Default: ignored

  • "ignored" means use the global setting.

  • Other values are "enabled" and "disabled".

Global setting: Replica Node Level Soft Anti-Affinity. More details in Scheduling and Best Practices.

Replica Zone Soft Anti-Affinity (field: parameters.replicaZoneSoftAntiAffinity)

Default: ignored

  • "ignored" means use the global setting.

  • Other values are "enabled" and "disabled".

Global setting: Replica Zone Level Soft Anti-Affinity. More details in Scheduling.

Replica Disk Soft Anti-Affinity (field: parameters.replicaDiskSoftAntiAffinity)

Default: ignored

  • "ignored" means use the global setting.

  • Other values are "enabled" and "disabled".

Global setting: Replica Disk Level Soft Anti-Affinity. More details in Scheduling.

NFS Options (field: parameters.nfsOptions)

Default: "" Example: "hard,sync"

  • Overrides for NFS mount of RWX volumes to the share-manager. Use this field with caution.

  • NOTE: Built-in options vary by release. Check your release details before setting this.

More details in RWX Workloads

Data Engine (field: parameters.dataEngine)

Default: "v1"

  • Specify "v2" to enable the V2 Data Engine (preview feature in v1.6.0). When unspecified, Longhorn uses the default value ("v1").

Global setting: V2 Data Engine. More details in V2 Data Engine Quick Start.

Freeze Filesystem For Snapshot (field: parameters.freezeFilesystemForSnapshot)

Default: ignored

  • "ignored" instructs Longhorn to use the global setting.

  • Other values are "enabled" and "disabled".

Global setting: Freeze File System For Snapshot.

Helm Installs

If Longhorn is installed via Helm, values in the default storage class can be set by editing the corresponding item in values.yaml. All of the Storage Class parameters have a prefix of "persistence". For example, persistence.defaultNodeSelector.