12 Kubernetes Storage Classes Explained for Beginners
12 Kubernetes StorageClass examples explained: EBS gp3/io2, EFS, Azure Disk and Files, GKE PD, local, NFS, Rook Ceph, Longhorn, with field guide.
A Kubernetes StorageClass is a template that tells the cluster how to create a PersistentVolume on demand: which CSI driver provisions it, what disk type or tier to use, whether it can be expanded, when it binds and what happens to the data when the claim is deleted. This guide explains the fields, then walks through 12 real StorageClass definitions for AWS, Azure, Google Cloud and on-premises clusters.
This post focuses on writing and choosing StorageClass objects. For the wider picture of volume types (emptyDir, hostPath, PVCs, object storage and more) read our companion guide, 12 Kubernetes storage options explained. Field behaviour was checked against kubernetes.io and each driver's own documentation in November 2026.
Key takeaways
- A PVC names a StorageClass; the class's
provisioner(a CSI driver) creates the matching PersistentVolume automatically. reclaimPolicydefaults toDelete. UseRetainfor data you cannot afford to lose with a mistakenkubectl delete pvc.volumeBindingMode: WaitForFirstConsumeravoids zone mismatches by provisioning the disk where the pod is scheduled.allowVolumeExpansion: truelets users grow a PVC. Shrinking is not supported.- Exactly one class should carry the
storageclass.kubernetes.io/is-default-class: "true"annotation. - Most StorageClass fields are immutable after creation. To change IOPS or throughput on existing volumes, look at VolumeAttributesClass, which is GA.
How dynamic provisioning works
- A developer creates a PersistentVolumeClaim with
storageClassName: fast-ssdand a size. - The external provisioner sidecar for that CSI driver sees the claim.
- The driver calls the storage backend (cloud API, Ceph, NFS server) to create a volume with the class's
parameters. - Kubernetes creates a PersistentVolume and binds it to the claim.
- The kubelet on the node mounts the volume into the pod.
If the claim omits storageClassName, the default class is used. If it sets storageClassName: "", dynamic provisioning is disabled and the claim only binds to a pre-created PV.
The StorageClass fields you will actually set
| Field | What it controls | Default | Advice |
|---|---|---|---|
provisioner | The CSI driver that creates volumes | Required | Match the driver installed in your cluster |
parameters | Driver-specific settings such as disk type or IOPS | None | Read the driver's docs; keys differ per driver |
reclaimPolicy | Delete or keep the backing volume when the PVC is deleted | Delete | Retain for production databases |
volumeBindingMode | Provision immediately or when a pod uses the claim | Immediate | WaitForFirstConsumer for zonal disks |
allowVolumeExpansion | Whether PVCs can be resized larger | false | Enable where the driver supports it |
mountOptions | Mount flags for the volume | None | Mainly for NFS and file shares |
allowedTopologies | Restrict provisioning to zones or regions | None | Use for compliance or cost reasons |
The 12 StorageClass examples at a glance
| # | Class | Provisioner | Access | Typical workload |
|---|---|---|---|---|
| 1 | AWS EBS gp3 | ebs.csi.aws.com | RWO block | General apps, small databases |
| 2 | AWS EBS io2 | ebs.csi.aws.com | RWO block | Latency-sensitive databases |
| 3 | AWS EFS | efs.csi.aws.com | RWX file | Shared content, CMS uploads |
| 4 | Azure Premium SSD | disk.csi.azure.com | RWO block | Databases on AKS |
| 5 | Azure Files | file.csi.azure.com | RWX file | Shared files on AKS |
| 6 | GKE balanced PD | pd.csi.storage.gke.io | RWO block | Default GKE workloads |
| 7 | GKE SSD PD | pd.csi.storage.gke.io | RWO block | High IOPS workloads |
| 8 | Local volumes | kubernetes.io/no-provisioner | RWO, node-bound | Distributed databases on bare metal |
| 9 | Local path | rancher.io/local-path | RWO, node-bound | Dev and test clusters |
| 10 | NFS CSI | nfs.csi.k8s.io | RWX file | On-prem shared storage |
| 11 | Ceph RBD (Rook) | rook-ceph.rbd.csi.ceph.com | RWO block | Self-hosted block storage |
| 12 | Longhorn | driver.longhorn.io | RWO (RWX via share manager) | Replicated storage on edge or small clusters |
Cloud block storage classes
1. AWS EBS gp3: the everyday default on EKS
gp3 lets you set IOPS and throughput separately from size, which gp2 did not. The EBS CSI driver must be installed as an EKS add-on or with Helm.
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: ebs-gp3
annotations:
storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
parameters:
type: gp3
encrypted: "true"
iops: "3000"
throughput: "125"
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
reclaimPolicy: Delete
EBS volumes live in one Availability Zone, so WaitForFirstConsumer is important: it creates the disk in the zone where the scheduler places the pod.
2. AWS EBS io2: provisioned IOPS for databases
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: ebs-io2-retain
provisioner: ebs.csi.aws.com
parameters:
type: io2
iopsPerGB: "50"
encrypted: "true"
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
reclaimPolicy: Retain
io2 costs more, so keep it in its own class and let teams opt in. Retain means a deleted claim leaves the EBS volume in place for recovery; someone must clean it up later.
4. Azure Premium SSD on AKS
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: azure-premium
provisioner: disk.csi.azure.com
parameters:
skuName: Premium_LRS
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
reclaimPolicy: Delete
AKS ships built-in classes such as managed-csi and managed-csi-premium. Write your own when you need a different SKU (for example StandardSSD_ZRS for zone-redundant disks or PremiumV2_LRS) or a different reclaim policy.
6 and 7. GKE balanced and SSD persistent disks
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: gke-ssd
provisioner: pd.csi.storage.gke.io
parameters:
type: pd-ssd
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
GKE's built-in standard-rwo class uses pd-balanced. Change type to pd-balanced for example 6, or to pd-ssd for example 7 when you need more IOPS per GB. Newer machine series use Hyperdisk types instead; check the GKE documentation for which disk types your node machine type supports.
Shared file storage classes (ReadWriteMany)
3. AWS EFS with access points
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: efs-shared
provisioner: efs.csi.aws.com
parameters:
provisioningMode: efs-ap
fileSystemId: fs-0123456789abcdef0
directoryPerms: "700"
The EFS file system must exist first. Each PVC gets its own access point and directory. Size in the PVC is required by Kubernetes but not enforced by EFS, which grows elastically.
5. Azure Files
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: azurefile-shared
provisioner: file.csi.azure.com
parameters:
skuName: Standard_LRS
mountOptions:
- dir_mode=0770
- file_mode=0770
allowVolumeExpansion: true
Azure Files gives ReadWriteMany over SMB by default, with NFS available on premium shares. Use it for shared content, not for database data files.
10. NFS CSI driver
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: nfs-csi
provisioner: nfs.csi.k8s.io
parameters:
server: nfs.internal.example.com
share: /exports/k8s
reclaimPolicy: Retain
mountOptions:
- nfsvers=4.1
The Kubernetes SIG Storage csi-driver-nfs creates a subdirectory per volume on an existing NFS export. It is simple and works on any cluster, but performance and availability are only as good as the NFS server.
Node-local storage classes
8. Local persistent volumes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: local-nvme
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer
No dynamic provisioning happens here: an admin (or the sig-storage local static provisioner) creates PVs for each local disk. The class exists so the scheduler waits and places the pod on the node that holds the disk. Use it for databases such as Cassandra that replicate data themselves, because losing the node means losing that copy.
9. Local path provisioner
The rancher.io/local-path provisioner creates a directory on the node for each claim. It is the default storage in k3s and is convenient for development, CI and single-node clusters. It offers no replication and no size enforcement, so do not use it for production data.
Self-hosted distributed storage classes
11. Ceph RBD through Rook
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: rook-ceph-block
provisioner: rook-ceph.rbd.csi.ceph.com
parameters:
clusterID: rook-ceph
pool: replicapool
imageFormat: "2"
imageFeatures: layering
csi.storage.k8s.io/provisioner-secret-name: rook-csi-rbd-provisioner
csi.storage.k8s.io/provisioner-secret-namespace: rook-ceph
csi.storage.k8s.io/node-stage-secret-name: rook-csi-rbd-node
csi.storage.k8s.io/node-stage-secret-namespace: rook-ceph
csi.storage.k8s.io/fstype: ext4
allowVolumeExpansion: true
reclaimPolicy: Delete
Rook, a CNCF graduated project, runs Ceph inside the cluster. The provisioner name is prefixed with the operator namespace (rook-ceph here). Rook's examples also include a CephFS class (rook-ceph.cephfs.csi.ceph.com) for ReadWriteMany.
12. Longhorn
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: longhorn-3r
provisioner: driver.longhorn.io
parameters:
numberOfReplicas: "3"
staleReplicaTimeout: "2880"
dataLocality: best-effort
allowVolumeExpansion: true
reclaimPolicy: Delete
Longhorn, a CNCF incubating project, replicates each volume across nodes using local disks. It suits small on-prem or edge clusters that have no SAN. Plan disk capacity for the replica count: three replicas use three times the space.
How to choose a StorageClass
| Need | Pick |
|---|---|
| One pod writes, general workload, in the cloud | Cloud block class (gp3, Premium SSD, pd-balanced) |
| Database needing guaranteed IOPS | Provisioned IOPS class (io2, Premium SSD v2, pd-ssd or Hyperdisk) with Retain |
| Many pods share files | EFS, Azure Files, Filestore or NFS CSI |
| Bare metal, self-replicating database | Local persistent volumes |
| Bare metal, need replicated block storage | Rook Ceph or Longhorn |
| Laptop, CI or dev cluster | Local path provisioner |
Troubleshooting a PVC stuck in Pending
A claim that stays Pending is the most common storage problem beginners meet. Work through these checks in order.
kubectl get pvc -n shop
kubectl describe pvc data-orders-db-0 -n shop
kubectl get storageclass
kubectl get csidrivers
kubectl get pods -n kube-system | grep -i csi
- Read the events.
kubectl describe pvcshows events from the provisioner. A message saying the claim is waiting for first consumer is normal forWaitForFirstConsumerclasses until a pod uses the claim. - Check the class name. A typo in
storageClassName, or a class that does not exist in this cluster, leaves the claim pending with no provisioning attempt. - Check the driver. If the CSI driver's controller pods are not running, nothing creates volumes. On EKS, the EBS CSI driver also needs IAM permissions, usually through an IAM role for its service account or EKS Pod Identity.
- Check access mode. Asking for
ReadWriteManyfrom a block storage class fails, because cloud block disks only support single-node attachment. - Check capacity and quotas. Cloud account limits, a
ResourceQuotaonrequests.storagein the namespace, or a full Ceph pool all stop provisioning. - Check topology. If the pod is pinned to a zone with node affinity and the class has
allowedTopologiesthat exclude that zone, the scheduler cannot satisfy both.
When a pod is stuck in ContainerCreating with a bound claim instead, the problem is in attaching or mounting. Look at kubectl describe pod for attach errors, often caused by a disk still attached to an old node after a node failure, or a disk in a different zone from the new node.
Testing a new class safely
Before you make a class the default or hand it to application teams, create a test claim and a pod that writes to it, then check the volume end to end.
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: sc-test
spec:
accessModes: ["ReadWriteOnce"]
storageClassName: ebs-gp3
resources:
requests:
storage: 1Gi
---
apiVersion: v1
kind: Pod
metadata:
name: sc-test
spec:
containers:
- name: writer
image: busybox:1.36
command: ["sh", "-c", "echo ok > /data/check && sleep 3600"]
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: sc-test
Confirm the PV was created with the parameters you expect, expand the claim to 2Gi to test allowVolumeExpansion, then delete the claim and verify the reclaim policy did what you intended in the cloud console or storage backend.
Operational tips
- Keep one default. If several classes are marked default, Kubernetes uses the most recently created one, which surprises people. Check with
kubectl get storageclass. - Classes are mostly immutable. You cannot edit
parametersorprovisioneron an existing class. Create a new class and migrate. - Use VolumeAttributesClass for tuning. It lets you change performance attributes such as IOPS on existing volumes where the CSI driver supports it.
- Snapshots need a VolumeSnapshotClass. Backups through CSI snapshots are configured separately; see our Kubernetes backup tools guide.
- Watch orphaned volumes.
Retainclasses leave released PVs and cloud disks behind. Review them regularly to control cost.
Managed cloud storage options are compared in 10 cloud storage solutions for Kubernetes applications, and the cluster pieces that call the CSI driver are covered in Kubernetes architecture components. StorageClasses, PVCs and troubleshooting pending claims are practised hands-on in our CKA training, in Kharadi, Pune or live online.
Frequently asked questions
What is a StorageClass in Kubernetes?
It is a cluster-level object that describes a type of storage and which provisioner creates it. PVCs reference it by name so volumes are created on demand.
What happens if a PVC has no storageClassName?
The cluster's default StorageClass is used. If there is no default, the claim stays unset until one is added. A claim with storageClassName: "" never uses dynamic provisioning.
Should I use Delete or Retain as the reclaim policy?
Delete removes the backing disk when the claim is deleted and suits temporary data. Retain keeps the disk for manual recovery and suits production databases.
Why use WaitForFirstConsumer?
It delays provisioning until a pod using the claim is scheduled, so a zonal disk is created in the same zone as the pod. With Immediate, the disk may land in a zone where the pod cannot run.
Can I change a StorageClass after creating it?
Most fields, including provisioner and parameters, cannot be changed. Create a new class. To change performance on existing volumes, use a VolumeAttributesClass if your driver supports it.
Can I shrink a PersistentVolumeClaim?
No. With allowVolumeExpansion: true you can only increase the size. To shrink, create a smaller volume and copy the data.
Which StorageClass supports ReadWriteMany?
File-based classes such as AWS EFS, Azure Files, GKE Filestore, NFS CSI and CephFS. Standard cloud block disks are ReadWriteOnce.
References
What's Your Reaction?
Like
0
Dislike
0
Love
0
Funny
0
Angry
0
Sad
0
Wow
0