All diagrams
Storage: Stateful Datak8s 1.36

StatefulSet PVC Retention

When a StatefulSet scales down or is deleted, which of its claims survive? The persistentVolumeClaimRetentionPolicy answers with two independent fields, whenScaled and whenDeleted, each Retain, the default, or Delete, and Delete gives the claim an ownerReference, to the removed Pod or to the StatefulSet, so the garbage collector deletes it after its owner. Deleting a claim only releases its PV, whose own reclaimPolicy decides whether the disk goes too.

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

StatefulSet PVC Retention diagram: StatefulSet persistentVolumeClaimRetentionPolicy as a two by two matrix

StatefulSet PVC Retention, step by step

  1. Each row flips one field of the policy on StatefulSet web while the other stays at the default, Retain. A field at Retain adds no ownerReference, so its event deletes no claim. Under whenDeleted Delete, the controller writes an ownerReference to web on the claims of every current Pod, existing or new.

    Play from step 1

  2. Scale web to two and the controller deletes the highest ordinal, Pod web-2. Retain leaves data-web-2 Bound with its data. Delete first makes Pod web-2 its owner, so once the Pod is gone the garbage collector deletes the claim, and its PV, set to Delete, takes the disk.

    Play from step 2

  3. Scale back to three and the controller creates web-2 again. Under Retain the new Pod mounts the same data-web-2, data intact. Under Delete the controller waits out the old claim, creates a fresh one of that name before the Pod, and with WaitForFirstConsumer its empty volume comes after the Pod.

    Play from step 3

  4. Delete web with the default background cascade and its Pods go too. Under Retain all three claims stay Bound with no owner. Under Delete the garbage collector deletes the claims web owns along with its Pods, PVC protection holds each until its Pod is gone, and each PV set to Delete takes its disk.

    Play from step 4

  5. Delete removes claims, never disks directly. Had the PVs said Retain, the same garbage collection would delete the three claims and leave every volume Released with its data. The reclaimPolicy on each PV decides the disk, not this policy.

    Play from step 5

Sources

Commands for this