PersistentVolumes and PersistentVolumeClaims

PersistentVolumes and claims: the fields that decide whether a claim binds, access modes, reclaim policies, and how to reuse a Released volume.

Your database needs a disk that survives restarts, and even the deletion of its Pod. A PersistentVolume is that disk, and a PersistentVolumeClaim is how a Pod asks for it. This lesson shows both, and the few fields that must match between them.

The exam asks about them in three ways, and the three tasks at the end practice each one:

• Create a PV, a claim and a Pod that uses the claim.
• Make a waiting (Pending) claim bind.
• Reuse a volume after its claim was deleted.

PV, PVC and StorageClass: three names, three jobs

These three names look alike and are easy to mix up:

The PersistentVolume

A PersistentVolume (PV) describes one piece of storage: its size, how it may be used, and where it lives. An admin can create PVs by hand, which is called static provisioning. Or a StorageClass creates them on demand, which is dynamic provisioning (next lesson).

apiVersion: v1
kind: PersistentVolume
metadata:
  name: st-data-pv
  labels:
    tier: data                  # lets a claim select this PV by label
spec:
  capacity:
    storage: 1Gi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: st-manual
  hostPath:
    path: /opt/st-data
    type: DirectoryOrCreate

The fields to know:

• capacity.storage: the size. Claims are compared against it.
• storageClassName: on a PV you make by hand, this is just a name to match. No StorageClass with that name has to exist, but the claim must use the same string.
• The source, here hostPath: where the data really is. Other sources are local, nfs and csi.

A local PV is the stricter cousin of hostPath. It names the one node that has the disk, in nodeAffinity. So every Pod that uses it runs on that node.

The PersistentVolumeClaim

A PersistentVolumeClaim (PVC) is a request for storage: a size and an access mode. The app team writes it in the app's namespace. Kubernetes then binds the claim to one PV.

Why the extra step? The Pod names the claim, never the PV. So the same Pod YAML works with a folder on a lab node or a disk in a cloud. Only the PV changes.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-claim
  namespace: st-pv
spec:
  accessModes:
    - ReadWriteOnce
  volumeMode: Filesystem
  storageClassName: st-manual
  resources:
    requests:
      storage: 1Gi
  selector:
    matchLabels:
      tier: data

apiVersion: v1
kind: Pod
metadata:
  name: data-pod
  namespace: st-pv
spec:
  containers:
    - name: web
      image: nginx:1.27
      volumeMounts:
        - name: data
          mountPath: /usr/share/nginx/html
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: data-claim

Access modes

An access mode says how many nodes may mount the volume at once, and whether they may write to it.

• A PV lists every mode it supports. A claim lists the modes it needs, and each one must be on the PV.
• Modes are a matching rule, not a lock. A hostPath PV may say ReadWriteMany, yet nothing makes two nodes see the same folder.
• On the exam, translate the words: "one node" means ReadWriteOnce, and "many nodes" means ReadWriteMany.

Reclaim policies

The reclaim policy, persistentVolumeReclaimPolicy, decides what happens to a PV when its claim is deleted:

• A PV you create by hand gets Retain if you leave the field out. A PV made by a StorageClass gets the class's policy, as the next lesson shows.
• You can change the policy on a live PV. To keep the data if the claim is deleted: kubectl patch pv <name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'.

How a claim finds its PV

Kubernetes binds a claim to a PV only when every check below passes. If one fails, the claim stays Pending.

• Size: the PV's capacity.storage is at least the claim's requests.storage. Kubernetes picks the smallest PV that fits. So a 1Gi claim may get a 5Gi PV, and then it shows 5Gi.
• Access modes: every mode the claim asks for is on the PV.
• Class: storageClassName is the same string on both. A claim that leaves it out gets the default class filled in. On this lab that is standard, which makes a brand-new volume instead of using yours. A claim with storageClassName: "" binds only to PVs that have no class.
• Selector: if the claim has one, the PV's labels must match it. A claim with a selector never gets a new volume from a StorageClass.
• Free: the PV is Available, not bound to another claim. A claim can also ask for one PV by name, with spec.volumeName.

Once bound, the pair stays bound until the claim is deleted. When a claim stays Pending, run kubectl describe pvc <name>. Its events say why. The fix is almost always a PV with the right class, size and access modes.

PV phases and reusing a Released volume

The STATUS column of kubectl get pv shows a PV's phase:

A Released PV still remembers its old claim in spec.claimRef, so no new claim can bind to it. Remove that reference and the PV is free again. The data on it is not touched.

kubectl get pv st-keep-pv                      # STATUS Released, CLAIM still shows the old claim
kubectl get pv st-keep-pv -o jsonpath='{.spec.claimRef}'

# Drop the reference to the deleted claim. The data on the volume is untouched.
kubectl patch pv st-keep-pv -p '{"spec":{"claimRef":null}}'
# Interactive alternative: kubectl edit pv st-keep-pv and delete the whole claimRef: block.

kubectl get pv st-keep-pv                      # Available
# A Pending claim that matches is picked up on the controller's next pass (within ~15s).
kubectl -n st-pv wait --for=jsonpath='{.status.phase}'=Bound pvc/keep-claim-v2 --timeout=90s