PVC lifecycle — the states and transitions of a PersistentVolumeClaim

The PersistentVolumeClaim has a simpler lifecycle than the PV: only two states, Pending and Bound. This lesson walks the states, what each means, and the production patterns for managing the lifecycle.

The two states

A PVC is in one of two states:

stateDiagram-v2
    [*] --> Pending: PVC submitted
    Pending --> Bound: matching PV found or created
    Bound --> [*]: PVC deleted (PV enters Released or is deleted)

Pending

A Pending PVC has been submitted but is not yet bound. The reasons for Pending:

• No matching PV: no existing PV matches the PVC’s criteria, and no provisioner is configured (or the provisioner is slow).
• No matching provisioner: the StorageClass references a provisioner that does not exist.
• StorageClass mismatch: the PVC asks for ssd but no ssd PVs or provisioners exist.
• Selector mismatch: the PVC has a selector that no existing PV matches.

kubectl get pvc
# NAME    STATUS    VOLUME   CAPACITY   ACCESS MODES
# data    Pending                          RWO

kubectl describe pvc data
# Events:
#   Type     Reason              Message
#   Warning  ProvisioningFailed  no persistent volumes available for this claim
#                                and no storage class is set

The events are diagnostic. kubectl describe pvc is the production starting point for “the PVC is Pending.”

Bound

A Bound PVC is matched to a PV. The PV’s claimRef points to the PVC; the PVC’s volumeName points to the PV. The Pod can mount the PVC.

kubectl get pvc
# NAME    STATUS   VOLUME                  CAPACITY   ACCESS MODES
# data    Bound    pvc-7c8f2d8e-...        100Gi      RWO

kubectl get pv pvc-7c8f2d8e-...
# NAME                  CAPACITY   STATUS   CLAIM                  RECLAIM POLICY
# pvc-7c8f2d8e-...      100Gi      Bound    production/data        Delete

A Bound PVC is the steady state. It remains Bound until the PVC is deleted or the PV fails.

The deletion sequence

When a PVC is deleted:

1. The PVC transitions to a terminating state (briefly).
2. The PV’s claimRef is cleared (with Retain) or the PV is deleted (with Delete).
3. The underlying storage is preserved (with Retain) or deleted (with Delete).

A Pod that is using the PVC blocks the PVC deletion. The kubelet does not allow the PVC to be deleted while the Pod is still mounting it. The deletion waits for the Pod to be deleted first.

# Attempting to delete a PVC that is in use
kubectl delete pvc data
# Error from server (Forbidden): error when deleting
# "data": PersistentVolumeClaim "data" is in use by Pod(s)

The fix: delete the Pod (or the workload that owns the Pod), then delete the PVC.

The access modes in lifecycle context

The PVC’s access modes affect which PVs can bind and which Pods can mount:

• RWO: single-node mount. The Pod must be on a node that can attach the volume.
• ROX: multi-node read-only. Multiple Pods can mount the same PVC read-only on different nodes.
• RWX: multi-node read-write. Multiple Pods can mount the same PVC read-write on different nodes.
• RWOP: single-Pod mount. Only one Pod can mount the PVC.

A PVC with RWX requires a backend that supports multi-node mounting (NFS, CephFS, EBS multi-attach). A PVC with RWO cannot bind to a PV that does not support RWO.

The capacity in lifecycle context

The PVC’s capacity request is the minimum:

• Submission: PVC requests 100 GB. If no PV has

  = 100 GB capacity, the PVC is Pending.

• Binding: the bound PV may have more capacity than requested (e.g., 200 GB). The PVC sees the PV’s actual capacity.
• Expansion: the PVC’s request can be increased (with allowVolumeExpansion: true on the StorageClass). The CSI driver handles the expansion.

Quiz

Production discipline

• kubectl describe pvc is the diagnostic starting point. Events show why a PVC is Pending.
• Pending PVCs block Pod scheduling. Monitor Pending state with alerts.
• PVC deletion is blocked by Pod mount. Delete the Pod first, then the PVC.
• Finalizers prevent accidental deletion. Understand the finalizer before bypassing it.
• Capacity is a minimum. The PV can be larger; the PVC sees the actual capacity.