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:
  backupTargetName: "default"
  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"
#  dataEngine: "v1"
#  freezeFSForSnapshot: "ignored"
# allowedTopologies:
#   - matchLabelExpressions:
#       - key: topology.kubernetes.io/zone
#         values:
#           - us-central-1a
#           - us-central-1b

Built-in Fields

Certain fields are common to all Kubernetes storage classes.

For more details, see Kubernetes Storage Class.

Provisioner (field: provisioner)

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

For more details, see Kubernetes Storage Class: Provisioner.

Allow Volume Expansion (field: allowVolumeExpansion)

Default: true

For more details, see Kubernetes Storage Class: Allow Volume Expansion.

Reclaim Policy (field: reclaimPolicy)

Default: Delete

For more details, see Kubernetes Storage Class: Reclaim Policy.

Mount Options (field: mountOptions)

Default []

For more details, see Kubernetes Storage Class - Mount Options.

Volume Binding Mode (field: volumeBindingMode)

Default Immediate

For more details, see Kubernetes Storage Class - Volume Binding Mode.

Immediate provisions the volume immediately upon PVC creation. When using strictTopology, WaitForFirstConsumer is strongly recommended so the volume’s PV nodeAffinity follows the scheduled node of the first consumer pod.

Allowed Topologies (field: allowedTopologies)

For more details, see the Kubernetes reference StorageClass — Allowed Topologies.

It specifies the set of nodes where volumes may be provisioned by matching node labels. SUSE Storage uses this field to populate the nodeAffinity of PV via the CSI accessibleTopology field.

For allowedTopologies to take effect, the SUSE Storage setting csi-allowed-topology-keys must be configured with the corresponding topology keys (for example, topology.kubernetes.io/zone). Without this setting, no topology information is passed through and the PV will have no nodeAffinity.

For volumes with dataLocality: strict-local, allowedTopologies is not written to the PV. SUSE Storage ignores the CSI topology for these volumes and places the data directly on the workload node.

For a complete walkthrough with examples, see the Topology-Aware Provisioning.

SUSE Storage-specific Parameters

  • Parameter overrides: Some of these parameters also exist and may be specified in global settings. When a volume is provisioned with Kubernetes against a particular StorageClass, the StorageClass parameters override the global settings.

  • New volumes only: These fields will be applied for new volume creation only. If a StorageClass is modified, neither SUSE Storage 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.

  • When dataLocality is set to strict-local, numberOfReplicas must be 1.

  • 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: 2880

The number of minutes after a replica is marked unhealthy before it is deemed useless for rebuilds and is deleted. The default value 2880 corresponds to 48 hours.

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.

Backup Target Name (field: parameters.backupTargetName)

Default: default

The name of the backup target to use for backups or restores.

For more details, see default backup target and Create Volumes.

Backup Block Size (field: parameters.backupBlockSize)

Default: "" Example: "2Mi" or "16Mi"

Kubernetes quantity string for the backup block size. Specify the empty string "" to use the global setting.

Global setting - default backup block size. For more details, see Configure The Block Size Of Backup.

FS Type (field: parameters.fsType)

The filesystem used to format the volume. Supported filesystems are ext4 and xfs.

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

Enables live migration capabilities for a Longhorn volume, allowing it to be migrated from one node to another while maintaining active I/O operations.

When to use:

  1. migratable: true: For workloads requiring live migration. Must be used with ReadWriteMany access mode and volumeMode: Block.

  2. migratable: false: For standard volumes that do not require live migration capabilities.

If specified on non-RWX volumes, SUSE Storage proceeds with non-migratable RWO volume creation. For more details, see ReadWriteMany (RWX) Volumes.

Encrypted (field: parameters.encrypted)

Default: false

For more details, see 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.

  • "disabled": No co-location requirement.

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

  • "strict-local": The replica count must be 1, or volume creation fails with a validation error. Longhorn places the volume data on the workload node and ignores CSI topology/accessibility requirements; allowedTopologies is not written to the PV nodeAffinity. A displaced strict-local replica will be marked as "Stopped".

Global setting - Default Data Locality. For more details, see Data Locality.

Replica Auto Balance (field: parameters.replicaAutoBalance)

Default: ignored

If enabled, move replicas to more lightly loaded nodes.

  • "ignored": Use the global setting.

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

Global setting - Replica Auto Balance. For more details, see Auto Balance Replicas.

Disk Selector (field: parameters.diskSelector)

Default: "" Example: "ssd,fast"

A comma-separated list of disk tags to select which disks are candidates for replica placement.

For more details, see Storage Tags.

Node Selector (field: parameters.nodeSelector)

Default: "" Example: "storage,fast"

A comma-separated list of node tags to select which nodes are candidates for replica placement.

For more details, see Storage Tags.

Recurring Job Selector (field: parameters.recurringJobSelector)

Default: "" Example: [{"name":"snap-group", "isGroup":true}, {"name":"backup", "isGroup":false}]

A JSON array of recurring job or group specifications to attach to the volume.

For more details, see Recurring Snapshot and Backups.

Backing Image (field: parameters.backingImage)

Default: ""

The name of the backing image to use for the volume.

For more details, see Backing Image.

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

Default: ""

The data source type if Longhorn must create a missing backing image during CSI volume provisioning.

  • Supported via CSI: download and export-from-volume.

  • Unsupported (upload): upload is a valid Longhorn backing image source type, but it is rejected when creating a missing backing image through CSI provisioning.

  • Unsupported (clone): clone is a valid Longhorn backing image source type, but it is not created through this CSI StorageClass path.

If backingImage refers to an existing backingImage, this parameter is usually unnecessary. If specified, it must match the existing backingImage source type and source parameters.

For more details, see Backing Image.

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

Default: "" Example: '{"url": "https://backing-image-example.s3-region.amazonaws.com/test-backing-image"}'

A JSON string representing the parameters required by the specified backingImageDataSourceType.

For more details, see Backing Image.

Backing Image Checksum (field: parameters.backingImageChecksum)

Expected SHA512 checksum of the backing image file.

Default: ""

For more details, see Backing Image.

Backing Image Min Number Of Copies (field: parameters.backingImageMinNumberOfCopies)

Default: "" Example: "2"

The minimum number of backing image copies Longhorn will automatically maintain on different disks.

For more details, see Backing Image.

Backing Image Node Selector (field: parameters.backingImageNodeSelector)

Default: "" Example: "storage,fast"

A comma-separated list of node tags where copies of the backing image are allowed to be placed.

For more details, see Backing Image.

Backing Image Disk Selector (field: parameters.backingImageDiskSelector)

Default: "" Example: "ssd"

A comma-separated list of disk tags where copies of the backing image are allowed to be placed.

For more details, see Backing Image.

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

Default: ignored

  • "ignored": Use the global setting.

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

For V2 Data Engine volumes, this parameter must be "disabled" (or left unset).

Global setting - Remove Snapshots During Filesystem Trim. For more details, see Trim Filesystem.

Disable Revision Counter (field: parameters.disableRevisionCounter)

Default: true

Controls whether to disable the volume revision counter. When set to false, Longhorn tracks revision counts to detect split-brain scenarios. When set to true (default), the revision counter is disabled.

Revision counters do not apply to V2 Data Engine volumes.

Global setting - Disable Revision Counter. For more details, see Revision Counter.

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

Default: ignored

  • "ignored": Use the global setting.

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

Global setting - Replica Node Level Soft Anti-Affinity. For more details, see Scheduling and Best Practices.

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

Default: ignored

  • "ignored": Use the global setting.

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

Global setting - Replica Zone Level Soft Anti-Affinity. For more details, see Scheduling.

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

Default: ignored

  • "ignored": Use the global setting.

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

Global setting - Replica Disk Level Soft Anti-Affinity. For more details, see Scheduling and Best Practices.

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.

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

For more details, see RWX Workloads.

Data Engine (field: parameters.dataEngine)

Default: "v1"

Specifies the data engine for the volume: "v1" or "v2". When unspecified, SUSE Storage uses "v1".

Global setting: V2 Data Engine.

Frontend (field: parameters.frontend)

Default: "blockdev"

Specifies the frontend exposure mechanism for the volume:

  • For V1 Data Engine: "blockdev" or "iscsi".

  • For V2 Data Engine: "blockdev", "nvmf", or "ublk".

Ublk Number of Queues (field: parameters.ublkNumberOfQueue)

Default: 0

The number of queues for the ublk frontend.

  • 0 means unspecified and uses the global setting.

  • Explicit values must be at least 1.

  • Applies only to volumes using the V2 Data Engine with ublk frontend.

Global setting - Default Ublk Number Of Queue.

Ublk Queue Depth (field: parameters.ublkQueueDepth)

Default: 0

The queue depth of each queue for the ublk frontend.

  • 0 means unspecified and uses the global setting.

  • Explicit values must be at least 32.

  • Applies only to volumes using the V2 Data Engine with ublk frontend.

Global setting - Default Ublk Queue Depth.

Freeze Filesystem For Snapshot (field: parameters.freezeFilesystemForSnapshot)

Default: ignored

  • "ignored" instructs SUSE Storage to use the global setting.

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

Global setting - Freeze File System For Snapshot.

Strict Topology (field: parameters.strictTopology)

Default: "false"

When set to "true", the PV is pinned to the topology of the exact node selected by the Kubernetes scheduler. This is only effective when volumeBindingMode is set to WaitForFirstConsumer.

  • "false" (default): The PV nodeAffinity includes all topology segments matching the allowedTopologies (or all segments if allowedTopologies is not set).

  • "true": The PV nodeAffinity is restricted to only the topology segment of the node where the pod was scheduled.

This parameter controls only Kubernetes PV nodeAffinity. It does not persist a Longhorn replica placement constraint.

It requires csi-allowed-topology-keys to be configured. See csi-allowed-topology-keys (CSI Allowed Topology Keys).

For more details, see Topology-Aware Provisioning.

Helm Installs

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