kubernetes

Kubernetes PersistentVolumeClaim

Kubernetes PersistentVolumeClaim Explained

By Shubhankar Tripathi • • 5 min read

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

Field

Meaning

accessModes

How the volume must be mountable: ReadWriteOnce, ReadOnlyMany, ReadWriteMany or ReadWriteOncePod. The bound PV must support them

resources.requests.storage

The minimum size needed. The bound PV may be larger

storageClassName

The class to use. Omitted means the cluster default class; an empty string means no class at all

volumeMode

Filesystem (default) or Block

volumeName

Binds the claim to one named PV (static pre-binding)

selector

Label selector for choosing among existing PVs

dataSource and dataSourceRef

Creates the volume from a snapshot, from another PVC (clone) or from a volume populator

 

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:

Phase

Meaning

Pending

The claim has not been bound to a volume yet. This is normal while provisioning is in progress or while binding is deliberately delayed

Bound

The claim is bound to a PV and ready to be mounted

Lost

The claim was bound, but its PV no longer exists or has been removed from under it. The data may be lost and needs administrator attention

 

The normal path for a dynamically provisioned claim runs like this:

  1. The claim is created and shows Pending.

  2. 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".

  3. The provisioner creates the backend volume and a PV. The claim events show the provisioning activity, for example ExternalProvisioning while a CSI driver works.

  4. The PV is bound to the claim, and the phase changes to Bound. status.capacity shows the real size of the PV.

  5. 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:

Setting

Behaviour

A class name, such as fast-ssd

Use that class. It is provisioned dynamically, or bound to an existing PV of the same class

Field omitted

Use the cluster's default StorageClass. If no default exists at creation time, recent Kubernetes versions assign the default class to the claim later, once one is set

Empty string ("")

Use no class. Dynamic provisioning is disabled and only PVs with no class can bind

 

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

Scenario

Suggested mode

Reason

Single-instance database on a cloud disk

ReadWriteOnce or ReadWriteOncePod

One writer; block storage is typically single-attach

Database that must never be mounted twice

ReadWriteOncePod

Guarantees one Pod across the whole cluster

Several web Pods sharing uploads

ReadWriteMany

Many writers need a shared file system

Many Pods reading a shared dataset

ReadOnlyMany

Read-only access from many nodes

StatefulSet replicas with their own disks

ReadWriteOnce per claim

Each replica has a separate volume

 

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.

  1. Confirm that the class allows expansion: kubectl get storageclass <name> -o yaml and look for allowVolumeExpansion.

  2. Increase the requested size on the claim.

kubectl patch pvc app-data -n shop \

  -p '{"spec":{"resources":{"requests":{"storage":"40Gi"}}}}'

  1. 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}'

  1. 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

Symptom

Likely cause and check

Pending, "waiting for first consumer"

Normal with WaitForFirstConsumer. Create or schedule a Pod that uses the claim.

Pending with no events from a provisioner

No default class and none named, a misspelt class name, or the provisioner or CSI controller is not running.

Pending with ProvisioningFailed

The driver failed to create the volume: cloud permissions, quota, invalid parameters or an unsupported access mode. Read the event text and the CSI controller logs.

Pending for a ReadWriteMany request

The class's backend does not support RWX. Use a file-based class.

Pending with an empty storageClassName

Dynamic provisioning is off and no static PV matches. Create a matching PV or remove the empty value.

Claim rejected at creation

ResourceQuota or LimitRange violation. Check the quota and limits in the namespace.

Pod Pending: unbound immediate PersistentVolumeClaims

The scheduler found a claim that is not yet bound. Fix the claim first.

Pod fails to attach: Multi-Attach error

An RWO volume is held by a Pod on another node. Use Recreate, node affinity, or wait for the old Pod to terminate.

Claim stuck in Terminating

A Pod still uses it. Find users in the "Used By" section of describe.

Phase Lost

The bound PV was deleted or is missing. Escalate to the storage administrator and check backups.

Resize not finishing

Class lacks allowVolumeExpansion, the driver does not support it, or a file system resize is waiting for a Pod restart.

 

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.