// Module included in the following assemblies:
//
// * storage/persistent_storage_local/persistent-storage-using-lvms.adoc

:_mod-docs-content-type: CONCEPT
[id="storageclass-options_{context}"]
= StorageClass options for LVMS device classes

[role="_abstract"]
You can configure custom StorageClass behaviors for each device class, including reclaim policy, volume binding mode, and custom parameters and labels, by defining the storageClassOptions field in the LVMCluster custom resource.

If you set an empty configuration (storageClassOptions: {}) or omit the field entirely, the Operator uses the following default settings: 

.StorageClass Options Reference
[cols="1,1,1,3,2", options="header"]
|===
| Field | Type | Immutable | Description | Example

| `reclaimPolicy`
| `string`
| Yes
a|
Controls what happens to the PersistentVolume (PV) and its underlying logical volume when the PersistentVolumeClaim (PVC) is deleted.

Allowed values: `Delete` (default), `Retain`

When set to `Retain`, deleting a PVC does not delete the PV or the underlying logical volume on disk. Data is preserved, useful for data protection scenarios where accidental PVC deletion must not cause data loss. Manual cleanup is required before you can delete the `LVMCluster`.

When set to `Delete`, both the PV and the on-disk logical volume are removed when the PVC is deleted.
a|
[source,yaml]
----
storageClassOptions:
  reclaimPolicy: Retain
----

| `volumeBindingMode`
| `string`
| Yes
a|
Controls when volume binding and dynamic provisioning occur.

Allowed values: `WaitForFirstConsumer` (default), `Immediate`

`WaitForFirstConsumer` delays PV provisioning until a pod that uses the PVC is scheduled, enabling topology-aware scheduling where LVMS creates the PV on the node where the pod will run.

`Immediate` provisions and binds the PV as soon as the PVC is created, without waiting for a consumer pod. On multi-node clusters, PVs might be provisioned on nodes where the consuming pod cannot run. Use `Immediate` only on single-node clusters or when node affinity is managed externally.
a|
[source,yaml]
----
storageClassOptions:
  volumeBindingMode: Immediate
----

| `additionalParameters`
| `map[string]string`
| Yes
a|
Adds custom key-value pairs to the `StorageClass .parameters` map.

Default: `{}` (empty). Maximum entries: 16.

StorageClass parameters are passed to the CSI driver (TopoLVM) during volume provisioning. TopoLVM recognizes only `topolvm.io/device-class` and `csi.storage.k8s.io/fstype`. Use `additionalParameters` for forward-compatibility or for parameters consumed by other Kubernetes components.

The following keys are managed by LVMS and are rejected at admission:

* `topolvm.io/device-class` — automatically set to the device class name
* `csi.storage.k8s.io/fstype` — automatically set from the `fstype` field on the device class

[IMPORTANT]
====
To change the filesystem type, use the `fstype` field on the device class directly. Do not use `additionalParameters`.
====
a|
[source,yaml]
----
storageClassOptions:
  additionalParameters:
    custom-param-key: custom-param-value
----

| `additionalLabels`
| `map[string]string`
| No
a|
Adds custom labels to the StorageClass metadata.

Default: none. Maximum entries: 16.

Use for organizational tagging, cluster policy integration, or monitoring. When you remove a label from `additionalLabels`, the operator removes it from the StorageClass during the next reconciliation. Labels added directly by other tools are not affected.

The following label keys are reserved and cannot be set through `additionalLabels`:

* `app.kubernetes.io/managed-by`
* `app.kubernetes.io/part-of`
* `app.kubernetes.io/name`
* `app.kubernetes.io/component`
* Any key with the prefix `owned-by.topolvm.io/`
a|
[source,yaml]
----
storageClassOptions:
  additionalLabels:
    environment: production
    team: storage
----

|===