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.
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.
4. How Dynamic Provisioning Works
The complete flow for a CSI-based class works as follows:
A user creates a PVC with storageClassName set to a class, for example fast-ssd.
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.
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.
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.
The driver creates the real volume in the storage backend and returns its identifier.
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.
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.
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:
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:
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:
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
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
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
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
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>
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
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.