Kubernetes PersistentVolumeClaim
Kubernetes PersistentVolumeClaim Explained
Kubernetes PersistentVolumeClaim Explained
bitcodematrix.com | Kubernetes Series
1. Introduction
If a PersistentVolume is the storage a cluster has, a PersistentVolumeClaim (PVC) is the storage an application asks for. It is the object that developers actually write, the one that shows up in Helm charts and StatefulSet templates, and the one that you look at first when a Pod is stuck waiting for its disk.
This article explains the PVC in depth: its specification, how it binds, its phases, how it interacts with StorageClasses, how to use it correctly from Pods, Deployments and StatefulSets, and how to resize, clone, restrict and delete claims safely. It complements the earlier articles in this series on storage architecture and PersistentVolumes, and avoids repeating their detail where it can.
2. What Is a PersistentVolumeClaim?
A PVC is a namespaced request for storage. It states how much storage is needed, how the volume will be accessed and, optionally, which class of storage is wanted. Kubernetes then binds the claim to a suitable PersistentVolume, either one that already exists or one that is created on demand by a StorageClass. The binding is exclusive: one claim, one volume.
The claim is also the unit of access control. A Pod can mount only claims in its own namespace, so the claim is the boundary between teams, while the PV beneath it is a cluster-wide resource that users typically never see. This makes the PVC the natural place to apply quotas, naming conventions and ownership.
3. Anatomy of a PVC
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: app-data
namespace: shop
spec:
accessModes:
- ReadWriteOnce
storageClassName: fast-ssd
volumeMode: Filesystem
resources:
requests:
storage: 20Gi
Note that the claim has no field for the number of IOPS, the disk type or the encryption key. Those belong to the StorageClass, and this is by design: the claim says what the application needs and the class says how it is delivered.
4. The Binding Lifecycle and Phases
A claim reports its state in status.phase:
The normal path for a dynamically provisioned claim runs like this:
The claim is created and shows Pending.
If the class uses WaitForFirstConsumer, the claim remains Pending until a Pod that uses it is scheduled. The event reads "waiting for first consumer to be created before binding".
The provisioner creates the backend volume and a PV. The claim events show the provisioning activity, for example ExternalProvisioning while a CSI driver works.
The PV is bound to the claim, and the phase changes to Bound. status.capacity shows the real size of the PV.
A Pod mounts the claim, and the volume is attached and mounted on the node.
A Pending claim is therefore not necessarily a problem. It becomes one when it stays Pending without a good reason, such as a missing Pod under WaitForFirstConsumer. The events on the claim always state which case you are in.
5. How Claims Interact with StorageClasses
The storageClassName field has three distinct meanings, which is a common source of confusion:
Check what is available before writing claims:
kubectl get storageclass
The default class is marked "(default)" in the output. One further rule is worth remembering: a claim with a non-empty selector cannot normally be satisfied by dynamic provisioning, because the selector applies to existing PVs. Use selectors only for static provisioning scenarios.
6. Using a Claim in a Pod
A Pod refers to a claim by name in its volumes section and mounts it into one or more containers:
apiVersion: v1
kind: Pod
metadata:
name: app
namespace: shop
spec:
containers:
- name: app
image: nginx:1.27
volumeMounts:
- name: data
mountPath: /var/lib/app
subPath: app
volumes:
- name: data
persistentVolumeClaim:
claimName: app-data
readOnly: false
A few practical notes apply:
The claim must be in the same namespace as the Pod. A missing claim leaves the Pod Pending with an event that the claim was not found.
Setting readOnly: true on the volume mounts it read-only for that Pod, which is useful for consumers of shared data.
subPath mounts a subdirectory of the volume instead of its root. This is a common fix for databases that complain about the lost+found directory that a freshly formatted ext4 volume contains. Mount a subdirectory, or point the database at a subdirectory of the volume.
Several containers in one Pod can mount the same claim, and several Pods can too if the access mode and the backend allow it.
7. Claims with Deployments and StatefulSets
7.1 Deployments
A Deployment shares one claim among all its replicas, because the Pod template names a single claim. That is only safe when the access mode allows it:
With a ReadWriteOnce claim, all replicas must run on the same node, otherwise Pods on other nodes cannot attach the volume and fail with a Multi-Attach or attach error. Scaling such a Deployment above one replica is usually a mistake.
During a rolling update, the new Pod may be scheduled on a different node while the old Pod still holds the volume, which causes the same error until the old Pod terminates. For a single-replica Deployment with a ReadWriteOnce claim, set the update strategy to Recreate so the old Pod stops before the new one starts.
If several replicas genuinely need to write to shared data, use a ReadWriteMany claim backed by a shared file system. If you need to guarantee that only one Pod ever uses a volume, use ReadWriteOncePod.
7.2 StatefulSets
A StatefulSet is the right tool when each replica needs its own disk. Its volumeClaimTemplates section generates one claim per Pod, named after the template, the StatefulSet and the ordinal, for example data-db-0, data-db-1 and data-db-2. Each Pod always reattaches to its own claim after restarts and rescheduling.
By default, these claims are kept when the StatefulSet is deleted or scaled down, which protects data but leaves unused volumes behind. The persistentVolumeClaimRetentionPolicy field lets you choose per situation:
spec:
persistentVolumeClaimRetentionPolicy:
whenDeleted: Retain
whenScaled: Delete
Choose Delete only for data that can be rebuilt, such as replicas that resync from a primary. Check the documentation of your Kubernetes version for the current status of this field.
8. Choosing Access Modes in Practice
Always check which modes your StorageClass and driver really support. A claim requesting ReadWriteMany from a block-storage class will stay Pending, because no PV can satisfy it.
9. Resizing a Claim
Growing a claim is a request to change the size in the spec. It works only when the StorageClass has allowVolumeExpansion set to true and the driver supports expansion.
Confirm that the class allows expansion: kubectl get storageclass <name> -o yaml and look for allowVolumeExpansion.
Increase the requested size on the claim.
kubectl patch pvc app-data -n shop \
-p '{"spec":{"resources":{"requests":{"storage":"40Gi"}}}}'
Watch the claim. Its conditions can show Resizing while the backend volume grows and FileSystemResizePending while the file system inside is waiting to be resized.
kubectl describe pvc app-data -n shop
kubectl get pvc app-data -n shop -o jsonpath='{.status.capacity.storage}'
Depending on the driver, the file system is resized online while the Pod runs, or when the Pod is next restarted. Verify the new size from inside the Pod with df.
Two limits matter. Shrinking a claim is not supported, so choose sizes with care. And a StatefulSet's volumeClaimTemplates cannot normally be edited in place, so you resize each existing claim directly and then update the template for future replicas, commonly by deleting the StatefulSet with the orphan cascade option so that Pods and claims are left in place before re-applying the manifest. Test this on a non-production StatefulSet first.
10. Creating Claims from Existing Data
A claim can start with data instead of an empty disk, using the dataSource field. Two sources are common, both requiring support from the CSI driver:
A snapshot: the claim is restored from a VolumeSnapshot in the same namespace. The snapshot approach was shown in the storage architecture article.
Another claim (a clone): the new claim is a copy of an existing PVC.
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: app-data-clone
namespace: shop
spec:
storageClassName: fast-ssd
dataSource:
kind: PersistentVolumeClaim
name: app-data
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 20Gi
A clone must be in the same namespace and use the same StorageClass and volume mode as its source, and its size must be at least that of the source. The related dataSourceRef field extends this idea to volume populators, which can fill a new volume from other sources such as an external data set; this is an advanced feature that depends on installed populator components.
11. Raw Block Claims
Some databases and storage engines want the raw device without a file system. Request it with volumeMode Block on the claim and attach it with volumeDevices instead of volumeMounts:
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: raw-data
spec:
accessModes:
- ReadWriteOnce
volumeMode: Block
storageClassName: fast-ssd
resources:
requests:
storage: 50Gi
spec:
containers:
- name: db
image: example/db:1.0
volumeDevices:
- name: raw
devicePath: /dev/block-data
volumes:
- name: raw
persistentVolumeClaim:
claimName: raw-data
The driver must support block mode, and the application becomes responsible for partitioning or formatting the device. Use it only when the workload requires it.
12. Governing Claims: Quotas and Limits
Because claims can create real, billable storage, shared clusters should limit them per namespace. A ResourceQuota caps the total requested storage and the number of claims, and can also set limits per StorageClass:
apiVersion: v1
kind: ResourceQuota
metadata:
name: storage-quota
namespace: shop
spec:
hard:
requests.storage: 200Gi
persistentvolumeclaims: "10"
fast-ssd.storageclass.storage.k8s.io/requests.storage: 100Gi
A LimitRange of type PersistentVolumeClaim sets the minimum and maximum size for each individual claim:
apiVersion: v1
kind: LimitRange
metadata:
name: storage-limits
namespace: shop
spec:
limits:
- type: PersistentVolumeClaim
min:
storage: 1Gi
max:
storage: 100Gi
A claim that breaks either rule is rejected at creation time, which gives users immediate feedback instead of a mysterious Pending state.
13. Deleting Claims Safely
Deleting a claim is the most consequential routine operation in Kubernetes storage, because what happens next depends on the reclaim policy of the PV beneath it:
With Delete, the PV and the backend volume are removed, and the data is gone.
With Retain, the PV and data survive in the Released state and must be handled by an administrator.
Before deleting, check the policy and take a snapshot or backup of anything important:
kubectl get pvc app-data -n shop -o jsonpath='{.spec.volumeName}'
kubectl get pv <pv-name> -o jsonpath='{.spec.persistentVolumeReclaimPolicy}'
The finalizer kubernetes.io/pvc-protection stops a claim from being removed while a Pod still uses it. A claim that shows Terminating is waiting for its last Pod to go away, and the describe output lists the Pods under "Used By". Stop or delete those Pods rather than stripping the finalizer by hand. Also note that deleting a namespace deletes its claims, with the same reclaim consequences.
14. Monitoring Claim Usage
A full volume causes application failures that look unrelated to storage. The kubelet exposes per-claim usage metrics, labelled with the namespace and claim name: kubelet_volume_stats_used_bytes, kubelet_volume_stats_capacity_bytes and kubelet_volume_stats_available_bytes. A simple alert condition for volumes with less than 15 percent free space is:
kubelet_volume_stats_available_bytes
/ kubelet_volume_stats_capacity_bytes < 0.15
Combine it with an alert on claims that stay Pending for longer than a few minutes. Not every storage driver reports these statistics, so verify that your volumes appear in the metrics.
15. Troubleshooting Claims
Start with the claim and its events, then move outwards to the Pod and the provisioner:
kubectl get pvc -n shop
kubectl describe pvc app-data -n shop
kubectl get events -n shop --field-selector involvedObject.name=app-data
kubectl get storageclass
kubectl get pv
kubectl describe pod <pod-name> -n shop
16. Best Practices
Set storageClassName explicitly in manifests rather than relying on the default, so that behaviour is the same on every cluster.
Request only the access mode you need, and prefer ReadWriteOncePod when a volume must have a single user.
Use StatefulSets with volumeClaimTemplates for replicated stateful apps, and Deployments with Recreate for single-instance apps on ReadWriteOnce claims.
Size claims with growth in mind, using classes that allow expansion, since volumes can grow but not shrink.
Apply ResourceQuota and LimitRange in every shared namespace.
Monitor claim free space and Pending claims, and alert before volumes fill up.
Know the reclaim policy behind each important claim before you delete anything, and keep backups that live outside the cluster.
Name claims after the workload and purpose, and label them with an owner, so that cleanup and cost allocation are straightforward.
Keep claims and Pods in sync in your delivery tooling, because deleting a claim by mistake is hard to undo.
17. Conclusion
The PersistentVolumeClaim is the simple, developer-facing end of Kubernetes storage. A few lines of YAML ask for size, access mode and class, and the cluster does the rest: choosing or creating a volume, binding it exclusively, and making it available to a Pod. Understanding its phases, its relationship to StorageClasses and the access-mode rules turns most storage incidents into short investigations of the claim's events.
Use explicit classes, the right workload controller for the access mode, quotas for shared clusters and monitoring for free space, and treat deletion with respect. With those habits, claims give your applications durable storage without ever tying them to a particular disk.