Understanding a Kubernetes Persistent Volume Claim
A PersistentVolumeClaim (PVC) is a namespaced request for storage made by a user or a Pod’s spec.volumes, specifying how much capacity is needed, which access modes are required, and optionally which StorageClass should provision it. Where a PersistentVolume represents actual storage, a PVC represents a request for storage – the two are matched (bound) by Kubernetes, either by finding an existing PersistentVolume that satisfies the claim or by dynamically provisioning a new one through a StorageClass.
How Binding Works
When a PVC is created, the control plane looks for a PersistentVolume that meets its requested size, access modes, and StorageClass. If dynamic provisioning is configured (the default in most managed Kubernetes offerings), the StorageClass’s provisioner creates a brand-new volume on demand and a matching PersistentVolume object, then binds it to the PVC. Once bound, the relationship is exclusive – a PersistentVolume can only be bound to one PVC at a time. Pods reference the PVC by name in spec.volumes, and the PVC’s underlying storage gets mounted into the container’s filesystem at the path defined by volumeMounts.
Simple Example
A team deploys PostgreSQL via a StatefulSet with a volumeClaimTemplate requesting 50Gi with accessModes ReadWriteOnce and storageClassName gp3. For each replica, Kubernetes automatically creates a uniquely named PVC (postgres-data-postgres-0, postgres-data-postgres-1, and so on), each dynamically provisioning its own EBS volume. If the postgres-0 Pod is deleted and recreated, the StatefulSet ensures it reattaches to the same PVC – and therefore the same data – rather than getting a fresh empty volume.
Common Use Cases
StatefulSet Storage
volumeClaimTemplates in a StatefulSet automatically create one PVC per replica, giving each Pod its own stable, independent storage.
Shared Application Data
A single PVC backed by ReadWriteMany-capable storage lets multiple Pods in a Deployment share the same files, such as a shared upload directory.
Manual Storage Requests
Developers create standalone PVCs for a single Pod that needs persistent scratch space or a dataset that must survive restarts.
Benefits
- Lets application developers request storage declaratively without needing to know the underlying cloud storage API.
- Works with dynamic provisioning so storage is created on demand rather than requiring manual pre-provisioning.
- Integrates cleanly with StatefulSets to give each replica of a stateful application its own dedicated, stable volume.
Limitations and Risks
- PVCs are namespace-scoped, so a Pod in one namespace cannot directly reference a PVC created in another.
- Shrinking a PVC is generally not supported – only expansion is allowed, and only if the StorageClass has allowVolumeExpansion set to true.
- Deleting a StatefulSet does not automatically delete its PVCs by default, which protects data but can leave orphaned volumes silently accumulating cost if not cleaned up deliberately.
- A PVC stuck in Pending status usually means no PersistentVolume or provisioner can satisfy its request – a common cause is requesting an access mode the StorageClass’s backend doesn’t support.
Best Practices
- Use volumeClaimTemplates in StatefulSets rather than manually managing individual PVCs for each replica.
- Set resource requests on PVCs conservatively but plan for growth, since expansion is supported but shrinking generally isn’t.
- Explicitly clean up orphaned PVCs left behind after deleting a StatefulSet or Deployment, since they continue to incur storage cost.
- Check kubectl describe pvc for binding errors when a PVC is stuck Pending – it usually points directly at the misconfiguration.
- Apply resource quotas on PVC counts and total storage requests per namespace to prevent runaway storage costs in multi-tenant clusters.
Frequently Asked Questions
What is Kubernetes Persistent Volume Claim?
A PersistentVolumeClaim is a namespaced request for storage that Kubernetes binds to a matching PersistentVolume, letting Pods consume storage without managing the underlying backend directly.
How does Kubernetes Persistent Volume Claim work?
Kubernetes Persistent Volume Claim works by combining the components described in the sections above. The main page walks through the architecture, the typical use cases, and the trade-offs to weigh before adopting it.
Why does Kubernetes Persistent Volume Claim matter?
Teams adopt Kubernetes Persistent Volume Claim to ship faster, run more reliably, and reduce the cognitive load on engineers. The benefits, limits, and adjacent tools are covered in the body above.
When should you use Kubernetes Persistent Volume Claim?
Use Kubernetes Persistent Volume Claim when the problems it solves match what your team is hitting today. The page above outlines the signals that mean you should adopt it now, and the cases where a simpler approach is fine.
