kubernetes

Kubernetes StorageClass : Dynamic Volume Provisioning

The StorageClass is the object that removed the manual step: it tells the cluster how to create storage on demand, so that a developer can write a short PersistentVolumeClaim and receive a ready-to-use volume in seconds.

By Shubhankar Tripathi • • 5 min read

Kubernetes StorageClass Explained: Dynamic Volume Provisioning

bitcodematrix.com | Kubernetes Series

1. Introduction

In the early days of Kubernetes storage, an administrator had to create every disk by hand, wrap it in a PersistentVolume and wait for a developer to claim it. That process does not scale. The StorageClass is the object that removed the manual step: it tells the cluster how to create storage on demand, so that a developer can write a short PersistentVolumeClaim and receive a ready-to-use volume in seconds.

This article explains the StorageClass in depth: its fields, how dynamic provisioning works step by step, how provisioners and parameters fit together, why the binding mode matters, how to manage the default class, and how to design a sensible catalogue of classes for your platform. It also covers governance, troubleshooting and best practices. It builds on the earlier articles in this series about storage architecture, PersistentVolumes and PersistentVolumeClaims.

2. The Problem Dynamic Provisioning Solves

With static provisioning, every volume needs an administrator's attention. Teams must predict how much storage they will need, request it from the platform team, wait for a disk to be created and a PV to be registered, and then claim it. Over-provisioning wastes money, under-provisioning delays projects, and the process becomes a bottleneck as the number of applications grows.

Dynamic provisioning inverts this. The platform team defines classes of storage once, such as "fast SSD with encryption" or "shared file storage". Developers then request a class by name and a size, and the cluster creates the backend volume and the PV automatically when the claim appears. Developers get self-service, administrators keep control over what is offered, and the storage is created only when it is needed.

3. What Is a StorageClass?

A StorageClass is a cluster-scoped object that describes a class of storage and the component that knows how to create it. It does not hold data and it does not represent a volume. It is a template that is consulted whenever a claim asks for that class.

apiVersion: storage.k8s.io/v1

kind: StorageClass

metadata:

  name: fast-ssd

provisioner: ebs.csi.aws.com

parameters:

  type: gp3

  encrypted: "true"

reclaimPolicy: Delete

allowVolumeExpansion: true

volumeBindingMode: WaitForFirstConsumer

mountOptions:

- noatime

The provisioner name and parameters above belong to the AWS EBS CSI driver and are used here only as an example. Every storage system defines its own, so always take them from the driver's documentation.

Field

Purpose

provisioner

Names the component that creates volumes for this class, usually a CSI driver such as ebs.csi.aws.com. Required

parameters

Driver-specific key-value settings, for example disk type, IOPS, encryption or file system type. Their meaning is defined by the driver

reclaimPolicy

Delete (default) or Retain. It is copied to every PV created from this class

allowVolumeExpansion

Whether claims of this class may be grown after creation

volumeBindingMode

Immediate or WaitForFirstConsumer. Controls when provisioning and binding happen

mountOptions

Mount options copied to the PVs. Invalid options cause mount failures, because they are not validated

allowedTopologies

Restricts the zones or nodes where volumes of this class may be created

 

4. How Dynamic Provisioning Works

The complete flow for a CSI-based class works as follows:

  1. A user creates a PVC with storageClassName set to a class, for example fast-ssd.

  2. Kubernetes checks the class. If it uses WaitForFirstConsumer, nothing happens yet; the claim waits until a Pod that uses it has been scheduled to a node. With Immediate, the process continues at once.

  3. The external-provisioner sidecar of the CSI driver, which watches PVCs, notices that a claim needs a volume from a class whose provisioner is its driver.

  4. The sidecar calls the driver's CreateVolume operation, passing the requested size, the access mode, the class parameters and, when a node has been chosen, the topology of that node.

  5. The driver creates the real volume in the storage backend and returns its identifier.

  6. The sidecar creates a PersistentVolume object that describes the volume, with the reclaim policy, mount options and node affinity taken from the class and the topology, and with a reference to the claim.

  7. The binding controller binds the PVC to the new PV, and the claim becomes Bound. When a Pod mounts it, the attach and mount steps described in the storage architecture article follow.

Two properties of this design are worth stressing. First, the provisioning is declarative and asynchronous: if the backend is slow or fails, the claim remains Pending and the events explain why, and the provisioner retries. Second, the StorageClass is only consulted at provisioning time and for a few later operations such as expansion. Changing it afterwards does not rewrite volumes that already exist.

5. Provisioners and Parameters

5.1 CSI Provisioners

Today, almost all provisioners are CSI drivers. The table below shows typical examples. Names and parameters change between driver versions, so treat them as illustrations and confirm them in the documentation of the driver you install.

Storage system

Example provisioner

Example parameters

AWS EBS

ebs.csi.aws.com

type (such as gp3), encrypted, kmsKeyId

Google Persistent Disk

pd.csi.storage.gke.io

type (such as pd-balanced or pd-ssd)

Azure Disk

disk.csi.azure.com

skuName (such as Premium_LRS)

NFS

nfs.csi.k8s.io

server and share

Local path (development)

rancher.io/local-path

Usually none

 

Small development distributions such as minikube, kind and k3s ship a simple default class backed by a directory on the node. That is convenient for learning but it offers no replication, and it behaves differently from production classes, so test storage-sensitive behaviour on a realistic class.

5.2 Common Reserved Parameters

The Kubernetes CSI sidecars understand a small set of reserved parameter keys that start with csi.storage.k8s.io. The most useful is csi.storage.k8s.io/fstype, which selects the file system to create on the volume, for example ext4 or xfs. Other reserved keys reference Secrets that hold credentials for provisioning, attaching or expanding volumes, which keeps sensitive data out of the class itself. Check your driver's documentation for the keys it supports.

5.3 No Provisioner

A class can set provisioner to kubernetes.io/no-provisioner. It tells Kubernetes that volumes of this class are not created dynamically; they are created by hand, as with local volumes. Such a class still serves a purpose, because it carries the binding mode that delays binding until a Pod is scheduled.

6. Binding Mode: Immediate or WaitForFirstConsumer

The volumeBindingMode field decides when the volume is created and bound:

Mode

Behaviour

Consequence

Immediate (default)

The volume is provisioned and bound as soon as the claim is created

The volume may be created in a zone where the Pod can later not be scheduled

WaitForFirstConsumer

Provisioning waits until a Pod using the claim is scheduled; the volume is then created where that Pod runs

The scheduler's decisions, such as node selectors, affinity and spreading, are respected

 

For any storage that is tied to a zone or a node, which includes most cloud block storage and all local volumes, WaitForFirstConsumer is the right choice. Without it, a claim can be provisioned in one availability zone while the Pod ends up in another, and the Pod then stays Pending with a "volume node affinity conflict" event. The price of the delayed mode is that claims remain Pending until a Pod exists, which is expected and not a fault.

Recent Kubernetes versions help the scheduler further through storage capacity tracking. CSI drivers can publish CSIStorageCapacity objects, so that the scheduler avoids nodes or zones where a volume of the requested size could not be provisioned.

6.1 Restricting Topology

Use allowedTopologies to confine volumes of a class to certain zones, for example to keep data in an approved region or to match the zones of a node pool:

allowedTopologies:

- matchLabelExpressions:

  - key: topology.kubernetes.io/zone

    values:

    - eu-west-1a

    - eu-west-1b

The label key must be the one that your CSI driver reports in its topology. Some drivers use their own key, so look at the labels or node affinity of an existing volume from the same driver before writing this field.

7. Reclaim Policy, Expansion and Mount Options

7.1 Reclaim Policy

Every PV created from a class inherits its reclaimPolicy. The default is Delete: when the claim is deleted, the PV and the backend volume are deleted too. This is efficient but unforgiving. Create a second class with Retain for important data, so that deleting a claim by mistake does not destroy the volume. Retained volumes then need manual cleanup, as described in the PersistentVolume article.

7.2 Volume Expansion

Setting allowVolumeExpansion to true lets users grow a claim by increasing its requested size. The driver must also support expansion. Unlike most other fields, this one can be changed on an existing class, which is useful when you forgot it initially:

kubectl patch storageclass fast-ssd \

  -p '{"allowVolumeExpansion": true}'

Existing PVCs of that class can then be expanded. Shrinking is never supported.

7.3 Mount Options

The mountOptions list is passed to the mount command on the node, for example noatime for file systems or nfsvers=4.1 for NFS. Because Kubernetes does not validate the options, a typo only shows up as a mount failure when a Pod first uses the volume. Test options on a single volume before putting them in a class used by many workloads.

8. The Default StorageClass

A class can be marked as the cluster default with an annotation. Any claim that omits storageClassName receives that class, which lets simple manifests work everywhere. The annotation is storageclass.kubernetes.io/is-default-class set to "true". You can set or remove it with kubectl patch:

kubectl patch storageclass fast-ssd -p \

  '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

 

kubectl patch storageclass old-default -p \

  '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'

Keep these rules in mind:

  • Only one default should exist. With several defaults, the behaviour depends on the version: older releases rejected claims without a class, while recent ones use the most recently created default. Avoid the ambiguity by keeping exactly one.

  • An empty string means no class. A claim with storageClassName set to "" never gets dynamic provisioning and binds only to PVs that have no class.

  • Managed clusters usually include a default. Check what your provider created before adding your own, using kubectl get storageclass, where the default is marked.

  • Be explicit in production manifests. Naming the class in each claim makes the behaviour independent of whichever class happens to be the default.

9. Designing a StorageClass Catalogue

A good catalogue is small, clearly named and aligned with real workload needs. Too many classes confuse developers, and too few force every workload onto the same compromise. A typical platform offers something like this:

Class name

Purpose

Typical settings

standard

General-purpose, default for most applications

Balanced disk type, Delete, expansion allowed, WaitForFirstConsumer

fast-ssd

Latency-sensitive databases and queues

High-performance disk type, encryption, expansion allowed

retain-ssd

Irreplaceable data that must survive claim deletion

Same as fast-ssd, with reclaimPolicy Retain

shared-files

ReadWriteMany workloads such as shared uploads

A file-system driver such as NFS or a cloud file service

local-storage

Self-replicating databases wanting node-local disks

no-provisioner, WaitForFirstConsumer, manually or statically created PVs

 

Here is a class for data that must be retained, followed by one for shared file storage. As before, the provisioner names and parameters are examples to adapt to your environment.

apiVersion: storage.k8s.io/v1

kind: StorageClass

metadata:

  name: retain-ssd

provisioner: ebs.csi.aws.com

parameters:

  type: gp3

  encrypted: "true"

reclaimPolicy: Retain

allowVolumeExpansion: true

volumeBindingMode: WaitForFirstConsumer

apiVersion: storage.k8s.io/v1

kind: StorageClass

metadata:

  name: shared-files

provisioner: nfs.csi.k8s.io

parameters:

  server: nfs.example.internal

  share: /exports

reclaimPolicy: Delete

volumeBindingMode: Immediate

mountOptions:

- nfsvers=4.1

Document each class: what it is for, its performance and cost, its access modes, and whether backups cover it. A short description in a wiki or in annotations saves developers from guessing.

10. Immutability and Changing Classes

Several StorageClass fields cannot be changed after creation: provisioner, parameters, reclaimPolicy and volumeBindingMode. Attempting to edit them is rejected. Fields such as allowVolumeExpansion and mountOptions can be updated. The reasoning is that PVs were created from the old definition, and silently rewriting it would leave the cluster inconsistent.

To change an immutable setting, create a new class with the desired values and use it for new claims. Existing PVs keep the settings they were created with. If you also need to change the class of existing data, remember that a claim's storageClassName cannot be changed either. Migrate by restoring from a snapshot into a claim of the new class, or by creating a new claim and copying the data with a job. Plan this before the data grows.

Tuning performance after creation, for example changing IOPS or throughput of an existing volume, historically meant recreating the volume. Recent Kubernetes releases add a VolumeAttributesClass API for modifying such attributes on existing volumes, when the driver supports it. Check the status of this feature in your Kubernetes version and in your driver before relying on it.

11. Hands-On Walkthrough

This sequence shows dynamic provisioning from end to end, using the fast-ssd class from Section 3:

  1. Check what is installed: the classes, and the CSI drivers and their Pods.

kubectl get storageclass

kubectl get csidrivers

kubectl get pods -n kube-system | grep -i csi

  1. Create a claim that names the class.

apiVersion: v1

kind: PersistentVolumeClaim

metadata:

  name: demo-data

  namespace: shop

spec:

  accessModes:

  - ReadWriteOnce

  storageClassName: fast-ssd

  resources:

    requests:

      storage: 5Gi

  1. Observe that the claim stays Pending when the class uses WaitForFirstConsumer, and read the event.

kubectl get pvc demo-data -n shop

kubectl describe pvc demo-data -n shop

  1. Create a Pod that mounts the claim, as shown in the PersistentVolumeClaim article, and watch the claim become Bound.

kubectl get pvc demo-data -n shop -w

  1. Inspect the PV that was created and confirm that it carries the class settings, the reclaim policy and the provisioner annotation.

kubectl get pv

kubectl describe pv <pv-name>

  1. Clean up by deleting the Pod and then the claim, and confirm that the PV and the backend volume are removed, or kept if the class uses Retain.

12. Governance and Security

  • Control who can create classes. StorageClasses are cluster-wide and can select expensive or sensitive storage. Restrict create and update rights with RBAC to the platform team.

  • Limit consumption per class. Use ResourceQuota keys of the form <class>.storageclass.storage.k8s.io/requests.storage to cap how much of an expensive class a namespace can request, together with the namespace-wide requests.storage limit.

  • Enforce policy. Admission policies, using tools such as Kyverno or Gatekeeper, can require that claims name an approved class, forbid the most expensive classes outside production namespaces, or require Retain classes for certain labels.

  • Keep secrets out of parameters. Use the reserved Secret reference parameters of the CSI sidecars instead of putting credentials directly in the class.

  • Encrypt by default. Turn on encryption at rest in the parameters of the classes you offer, and manage the keys and their permissions deliberately. A missing key permission is a common cause of provisioning failures.

  • Watch cost. Dynamic provisioning makes it easy to create storage, so monitor unused claims and Retained volumes that continue to cost money.

13. Troubleshooting

Start by reading the claim's events, then check the class and the provisioner:

kubectl describe pvc <claim> -n <namespace>

kubectl get storageclass <class> -o yaml

kubectl get pods -A | grep -i csi

kubectl logs -n <driver-namespace> <csi-controller-pod> -c csi-provisioner

Symptom

Likely cause and check

Claim Pending, event says storage class not found

The class name is misspelt or the class does not exist in this cluster. Compare with kubectl get storageclass.

Claim Pending, "waiting for a volume to be created, either by external provisioner or manually"

The provisioner is not running or the provisioner name in the class does not match the installed driver.

Claim Pending, "waiting for first consumer"

Normal with WaitForFirstConsumer. Start a Pod that uses the claim.

ProvisioningFailed events

The driver could not create the volume: invalid parameters, backend quota, missing cloud permissions or key access. Read the event text and the provisioner logs.

Pod Pending after provisioning, node affinity conflict

The volume is in a zone where the Pod cannot run. Use WaitForFirstConsumer and review allowedTopologies and Pod placement rules.

Cannot edit a class field

The field is immutable. Create a new class instead.

Claims receive an unexpected class

Several defaults exist, or the default changed. Check the annotations and make claims explicit.

Expansion rejected

The class does not allow expansion, the claim was not provisioned dynamically, or the driver lacks support.

Mount fails after provisioning

Invalid mountOptions or an unsupported file system type in the class parameters.

Volumes unexpectedly deleted

The class uses Delete. Switch important data to a Retain class.

 

14. Best Practices

  • Offer a small, well-documented set of classes with clear names that describe purpose and performance, not vendor details.

  • Use WaitForFirstConsumer for all zonal and local storage.

  • Set allowVolumeExpansion to true on classes where the driver supports it, because growing a volume is far easier than migrating one.

  • Provide a Retain class for critical data and use Delete only where data is reproducible.

  • Keep exactly one default class, and name the class explicitly in production manifests.

  • Treat classes as versioned platform interfaces: create new classes for breaking changes instead of trying to edit immutable fields.

  • Enable encryption in every class that holds real data, and test the key permissions.

  • Apply quotas per class and RBAC for class management, and monitor provisioning errors and orphaned volumes.

  • Keep CSI drivers and their sidecars on supported versions, and test upgrades in non-production clusters first.

15. Conclusion

The StorageClass is the contract that turns storage into a self-service platform feature. It names the driver, captures the parameters that define quality and cost, and sets the rules for reclaiming, expanding and placing volumes. Together with a PersistentVolumeClaim, it makes provisioning a matter of a few lines of YAML, with the PV and the backend disk appearing automatically.

Design a small catalogue of classes, choose the binding mode with topology in mind, make deliberate decisions about reclaim policy and defaults, and govern access with quotas and policy. With those pieces in place, dynamic provisioning gives developers speed and gives platform teams control.