What are PersistentVolumes, PersistentVolumeClaims and StorageClasses?
A PersistentVolume (PV) is a piece of storage, such as a cloud disk or an NFS share, represented as an object in a Kubernetes cluster. A PersistentVolumeClaim (PVC) is a request for storage of a given size and access mode, which a Pod mounts by name. A StorageClass describes a kind of storage and lets Kubernetes create a matching PersistentVolume automatically when a claim asks for one, which is called dynamic provisioning.
How the three objects fit together
| Object | Who creates it | Scope | What it holds |
|---|---|---|---|
| StorageClass | Cluster administrator or the storage driver’s installer | Cluster | The provisioner (usually a CSI driver), its parameters, the reclaim policy and the binding mode |
| PersistentVolumeClaim | Application team, or a StatefulSet’s volumeClaimTemplates | Namespace | Requested size, access mode and StorageClass |
| PersistentVolume | The provisioner, or an administrator for pre-created volumes | Cluster | The details of the real storage: driver, volume ID, capacity, topology |
The split keeps applications portable. A manifest asks for “20 GiB of fast-ssd”, and each cluster maps that class to whatever storage it has: Amazon EBS in one cloud, a Ceph pool on-premises.
Dynamic provisioning step by step
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: data
spec:
accessModes: ["ReadWriteOnce"]
storageClassName: fast-ssd
resources:
requests:
storage: 20Gi- You create the claim. It is
Pendinguntil a volume is bound to it. - The StorageClass’s provisioner, a Container Storage Interface (CSI) driver, creates a disk through the storage system’s API.
- Kubernetes creates a PersistentVolume for that disk and binds it to the claim. The binding is one-to-one.
- A Pod references the claim under
volumeswithpersistentVolumeClaim.claimName: data, and the kubelet attaches and mounts the disk on the Pod’s node.
A claim without storageClassName gets the cluster’s default StorageClass, the one annotated with storageclass.kubernetes.io/is-default-class: "true". A claim with storageClassName: "" disables dynamic provisioning and binds only to a pre-created volume. If no default exists and no volume matches, the claim stays unbound indefinitely.
Access modes
| Mode | Meaning |
|---|---|
ReadWriteOnce (RWO) | Read-write by a single node. Several Pods on that node can still use it |
ReadOnlyMany (ROX) | Read-only by many nodes |
ReadWriteMany (RWX) | Read-write by many nodes |
ReadWriteOncePod (RWOP) | Read-write by a single Pod in the whole cluster. Stable since Kubernetes 1.29, CSI volumes only |
Cloud block disks are mounted as RWO or RWOP. RWX needs a shared file system such as NFS, CephFS or a managed file service. The documentation also warns that access modes do not enforce write protection once a volume is mounted, and that a volume can be mounted with only one access mode at a time. Which storage systems offer which modes outside the cloud is covered in storage for on-premises Kubernetes.
Reclaim policy: what happens when the claim is deleted
| Policy | Behavior |
|---|---|
Delete | The PersistentVolume and the underlying disk are deleted. Default for dynamically provisioned volumes |
Retain | The PersistentVolume stays in the Released phase with its data. An administrator must clean it up or reuse it by hand |
Recycle | Deprecated. Use dynamic provisioning instead |
With the default Delete, removing a claim deletes the data. Use a StorageClass with reclaimPolicy: Retain for data you cannot recreate, and keep backups either way. Kubernetes does protect volumes in use: a claim deleted while a Pod still uses it is only removed after the Pod stops.
Volume binding mode and zones
Cloud block volumes are zonal: a disk created in one availability zone can only attach to nodes in that zone. The StorageClass field volumeBindingMode decides when the disk is created:
Immediate, the default, creates and binds the volume as soon as the claim exists. The StorageClass documentation notes that for topology-constrained storage this happens “without knowledge of the Pod’s scheduling requirements”, which can leave the Pod unschedulable: the disk sits in zone A and the Pod’s node selector only allows zone B.WaitForFirstConsumerdelays creation until a Pod using the claim is scheduled, then creates the disk in that node’s zone. A claim showingPendinguntil its Pod exists is normal in this mode.
After the first binding, the volume pins the Pod to its zone. If no node in that zone has room, the Pod stays Pending until a node autoscaler adds one there. The scheduler reads the zone from the topology.kubernetes.io/zone label on each node. allowedTopologies on a StorageClass can restrict provisioning to specific zones.
Expanding volumes
If the StorageClass sets allowVolumeExpansion: true, you grow a volume by raising spec.resources.requests.storage on the claim. Volume expansion is stable since Kubernetes 1.24. Kubernetes cannot shrink a claim below its current size.
Volumes in StatefulSets
A StatefulSet creates one claim per replica from its volumeClaimTemplates, named after the Pod, so db-0 always gets the same disk back. Scaling down or deleting the StatefulSet keeps those claims by default. The differences from Deployments are covered in Deployment vs StatefulSet vs DaemonSet vs Job.
Persistent volumes on Cloudfleet
In Cloudfleet Kubernetes Engine (CFKE), the CSI drivers for Amazon EBS, GCP Persistent Disk and Hetzner Cloud Volumes run side by side in one cluster, and node auto-provisioning launches a node in the zone of a Pod’s volume when none is free. The documentation recommends WaitForFirstConsumer for every StorageClass. See the storage overview and persistent volume issues.