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

ObjectWho creates itScopeWhat it holds
StorageClassCluster administrator or the storage driver’s installerClusterThe provisioner (usually a CSI driver), its parameters, the reclaim policy and the binding mode
PersistentVolumeClaimApplication team, or a StatefulSet’s volumeClaimTemplatesNamespaceRequested size, access mode and StorageClass
PersistentVolumeThe provisioner, or an administrator for pre-created volumesClusterThe 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

yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: fast-ssd
  resources:
    requests:
      storage: 20Gi
  1. You create the claim. It is Pending until a volume is bound to it.
  2. The StorageClass’s provisioner, a Container Storage Interface (CSI) driver, creates a disk through the storage system’s API.
  3. Kubernetes creates a PersistentVolume for that disk and binds it to the claim. The binding is one-to-one.
  4. A Pod references the claim under volumes with persistentVolumeClaim.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

ModeMeaning
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

PolicyBehavior
DeleteThe PersistentVolume and the underlying disk are deleted. Default for dynamically provisioned volumes
RetainThe PersistentVolume stays in the Released phase with its data. An administrator must clean it up or reuse it by hand
RecycleDeprecated. 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.
  • WaitForFirstConsumer delays creation until a Pod using the claim is scheduled, then creates the disk in that node’s zone. A claim showing Pending until 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.

On this page