All diagrams
Storage: Volumes & Claimsk8s 1.36

Reclaim Policy

You delete a PVC, so does the disk full of data go with it? One field on the PV decides, copied from the StorageClass when a provisioner makes the volume, Delete unless the class says otherwise, and patchable on a live PV. Delete destroys the backing disk and then the PV object, while Retain touches nothing and leaves an orphan: a new claim of the same class gets a fresh empty disk, and even deleting the PV by hand leaves the old disk in the backend.

Play the animation 7 steps, animated, best on a wide screen

Reclaim Policy diagram: Reclaim policy decides whether deleting a claim also destroys the real disk behind its

Reclaim Policy, step by step

  1. Every PV carries a reclaim policy, set when the volume is made, and a PV written by hand that names none gets Retain. The external-provisioner copied it from StorageClass gp3 onto both volumes here, and gp3 says Delete, which is also what a class gets when it names no policy. As things stand both disks die with their claims.

    Play from step 1

  2. The field is not frozen. An administrator runs kubectl patch pv on the right volume and sets its persistentVolumeReclaimPolicy to Retain. Only that one PV changes: the class and every other volume it made keep Delete. This is how you protect the data on a volume before you delete its claim.

    Play from step 2

  3. Both claims are deleted with kubectl delete pvc. The Bound links break and both volumes move to the Released phase, which means only that the claim they belonged to is gone. Nothing has touched the disks yet. What happens next is decided by the policy each volume now carries.

    Play from step 3

  4. The external-provisioner reads Delete on the left volume and calls DeleteVolume on the CSI driver. The backend destroys the real disk, and only then is the PV object removed. Convenient for scratch data and unforgiving for anything you meant to keep, because the disk is gone and Kubernetes keeps no copy of it.

    Play from step 4

  5. The same provisioner reads Retain on the right volume and makes no call at all, so the disk and every byte on it survive. The volume stays Released, still carrying the claimRef of a claim that no longer exists, and nothing in the cluster will touch it again on its own.

    Play from step 5

  6. A fresh claim data-c of the same class arrives, and it does not get the old disk. A Released volume is not offered to a new claim, so the provisioner reads gp3 again and makes a brand new, empty vol-ccc. The old data sits one column away, out of reach and still billed.

    Play from step 6

  7. Clean up by hand: deleting PV ret removes the object, and vol-bbb stays. Under Retain even deleting the PV leaves the disk, while under Delete a PV deleted before its claim still takes its disk once the claim goes. This one has to be deleted in the storage backend, or kept and given a new PV by hand before a claim can use it.

    Play from step 7

Sources

Commands for this