Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 78 ยท Storage

PersistentVolumes and Claims

Learn how PersistentVolumes and PersistentVolumeClaims separate storage supply from demand, with access modes, reclaim policies, binding rules and volume phases.

Pod-level volumes such as emptyDir disappear with the pod. Databases, uploads and queues need storage that outlives any single pod, node or deployment. Kubernetes splits this into two objects with two different owners. A PersistentVolume (PV) is a piece of storage that exists in the cluster, usually created by an administrator or a provisioner. A PersistentVolumeClaim (PVC) is an application's request for storage: "I need 10 Gi that one node can write to".

This split is the key idea. Developers write claims and never need to know whether the disk is an NFS export, a cloud disk or a local SSD. The control plane matches claims with volumes. This lesson explains the objects, access modes, reclaim policies and the matching rules, then shows them in a stand-in binder. Automatic creation of volumes is the next lesson, StorageClasses. Everything here is read-only YAML plus Python, since the site has no cluster. Start with volumes if you have not.

Supply and demand

PersistentVolume A real disk, offered to the cluster.
PersistentVolumeClaim An app asks for size and access.
Binding One claim gets exactly one volume.

PVs are cluster-wide; PVCs live in a namespace.

1 / 2

A PersistentVolume

An administrator might register an NFS export like this:

YAML
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-archive
spec:
  capacity:
    storage: 20Gi
  accessModes:
    - ReadWriteMany
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  nfs:
    server: 10.0.0.20
    path: /exports/archive

The important fields are the capacity, the access modes, the reclaim policy, an optional storageClassName, and the volume source (nfs, csi, local, ...). PVs are not namespaced: any namespace can claim them, though only one at a time. In practice most PVs are created for you by a provisioner and you rarely write them by hand.

A PersistentVolumeClaim

An application then asks for storage:

YAML
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: archive-data
  namespace: shop
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: manual
  resources:
    requests:
      storage: 5Gi

And a pod mounts the claim, by name, as a volume:

YAML
spec:
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: archive-data
  containers:
    - name: app
      image: example/app:2.1
      volumeMounts:
        - name: data
          mountPath: /var/lib/app

Notice what the pod does not say: no server address, no disk ID. The claim is the abstraction. Deleting the pod leaves the claim, and the data, in place; a new pod mounting the same claim sees the same files.

Access modes

The access mode describes how many nodes may use the volume at once, not how many pods:

Mode Short Meaning
ReadWriteOnce RWO Read-write by a single node (several pods on that node can share 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

What you can ask for depends on the storage technology. A block device such as a cloud disk is usually RWO only; shared file systems (NFS, CephFS, EFS, Azure Files) offer RWX. Asking for RWX from a block disk class leaves the claim Pending forever. Use RWOP for single-writer databases when you want the cluster to refuse a second writer even on the same node.

A PV can list several modes, but it is used in only one mode at a time.

Reclaim policies

When a claim is deleted, the PV's persistentVolumeReclaimPolicy decides what happens to the volume and its data:

  • Retain: the PV becomes Released and keeps the data. It is not reusable until an administrator removes the old claimRef (or recreates the PV). Best for precious data.
  • Delete: the PV object and the underlying storage asset (cloud disk) are deleted. This is the default for dynamically provisioned volumes, which surprises people who delete a namespace and lose a database.
  • Recycle: an old rm -rf scrub, deprecated and removed from most volume types. Do not use it.

You can change the policy of an existing PV with kubectl patch, a sensible precaution before deleting any claim whose data you care about:

Terminal
kubectl patch pv pv-archive -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

How binding works

A controller in the control plane watches for unbound claims and looks for a PV that satisfies all of these:

  1. The storageClassName is identical. An empty string "" means "no class" and only matches PVs without a class; leaving the field out lets the cluster fill in the default class.
  2. The PV has at least the requested capacity.
  3. The PV's access modes include every requested mode.
  4. The volumeMode (Filesystem or Block) matches.
  5. If the claim has a selector, the PV's labels match it. If the claim sets volumeName, only that PV qualifies.
  6. The PV is not already claimed by someone else.

Among the candidates, the smallest that fits is chosen, so a 5 Gi claim takes a 10 Gi volume before a 100 Gi one. The claim then reports the volume's capacity (all 10 Gi), not what it asked for. If nothing matches, the claim stays Pending and is retried; when a suitable PV appears, it binds. Binding is one-to-one and exclusive: a 100 Gi PV serving a 1 Gi claim wastes the rest.

An administrator can also pre-bind a volume to one particular claim by setting claimRef on the PV, which reserves it.

Python A PVC-to-PV binder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The db claim takes pv-mid (10 Gi, the smallest that fits 8 Gi), cache then takes pv-small, logs finds no 100 Gi volume and stays pending, and legacy, with class "", matches nothing because every PV has a class. In a real cluster that last claim would wait for an administrator to create a classless PV.

Claim and volume phases

A PV moves through Available, Bound, Released and Failed. A PVC is Pending, Bound or Lost (its PV vanished). Check them with:

Terminal
kubectl get pv
kubectl get pvc -n shop
kubectl describe pvc archive-data -n shop

The Events section of describe tells you why a claim is stuck: no matching PV, a wrong class name, or an access mode the storage cannot offer. A pod that references a Pending claim stays Pending too, with an event such as "pod has unbound immediate PersistentVolumeClaims".

What happens when a claim is deleted

The reclaim policy decides the outcome. This stand-in runs the same claim deletion against two volumes with different policies.

Python Deleting a claim: Retain versus Delete

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The Retain volume ends up Released with its disk intact but not claimable, just like the real thing, until an administrator clears its claimRef. That deliberate extra step protects you from handing old data to a new, unrelated claim.

Practical advice

  • Prefer dynamic provisioning (next lesson) over hand-made PVs.
  • Switch important volumes to Retain before deleting claims or namespaces, and back them up (databases and backups).
  • Remember that RWO means one node: a Deployment with replicas: 3 and a single RWO claim works only if all pods land on the same node. For one volume per replica, use a StatefulSet with volumeClaimTemplates.
  • Namespaces are not a storage boundary for PVs, but claims are namespaced: a claim in dev cannot be mounted by a pod in prod.
  • Growing a claim is possible only if its StorageClass allows expansion; shrinking is not.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Who normally creates PersistentVolumeClaims?

    Claims express an application's needs (size, access mode, class). PVs are the supply side, usually provisioned automatically or by an administrator.
  2. 2. A claim asks for 5Gi. Available volumes are 4Gi, 10Gi and 100Gi, all compatible. Which one does it bind to, and what capacity does the claim show?

    The binder picks the smallest volume that satisfies the request, and the claim then reports the full capacity of the bound volume.
  3. 3. What does ReadWriteOnce actually limit?

    RWO is per node, so several pods on the same node can share the volume. ReadWriteOncePod is the mode that limits access to a single pod.
  4. 4. A PV with reclaim policy Retain has its claim deleted. What is its state?

    Retain keeps the data and marks the PV Released. It stays reserved until someone removes the old claimRef, to avoid leaking data to a new claim.

Summary

  • A PV is cluster-level storage; a PVC is a namespaced request. Pods mount PVCs, never PVs directly.
  • Access modes (RWO, ROX, RWX, RWOP) describe nodes or pods that may mount a volume, and depend on the storage type.
  • Binding matches class, capacity, access modes, volume mode and selectors, then picks the smallest fitting PV; unmatched claims stay Pending.
  • Retain keeps data and releases the PV for manual cleanup; Delete removes the PV and the disk.
  • Check kubectl describe pvc events first when a claim or pod is stuck.

Next: StorageClasses and Dynamic Provisioning