StatefulSet volumeClaimTemplates
Why does every replica of a StatefulSet get its own disk, when Deployment replicas that name a claim all share that one? Each volumeClaimTemplate stamps out one PersistentVolumeClaim per ordinal with a deterministic name like data-web-0. Because that name comes from the Pod identity, a recreated Pod, even on another Node that can reach the volume, mounts the same claim and data. Scaling down leaves the claims behind, as the default retention policy is Retain.
Play the animation 5 steps, animated, best on a wide screen
StatefulSet volumeClaimTemplates, step by step
-
For each ordinal the StatefulSet creates the claim, or reuses one of that name, and then its Pod. The claim name is the template name joined to the Pod name: data-web-0, data-web-1, data-web-2. Drawn as one pass, but under the default OrderedReady policy web-1 waits until web-0 is Running and Ready.
Play from step 1 -
Each claim is bound to its own PersistentVolume, ordinal 0 to PV web-0 and never to PV web-1. Drawn as one phase, but by default each ordinal binds and mounts before the next is created, so a claim stuck Pending stalls every later one. The claim is the durable name, the disk holds the bytes.
Play from step 2 -
Each Pod mounts the volume behind its own claim before its app starts. Replica web-0 reads and writes data-web-0, web-1 data-web-1, and so on. Each replica names a different claim and a claim binds exactly one PV, so no two replicas share a disk.
Play from step 3 -
Delete web-1 and the StatefulSet recreates it, possibly on another Node that can reach PV web-1. The claim data-web-1 is not deleted with the Pod and stays Bound to PV web-1. The new Pod derives the same claim name from its ordinal, so it mounts the very same disk and data.
Play from step 4 -
Scale web down to two and Pod web-2 is removed, but claim data-web-2 stays Bound with its data. That is the default whenScaled policy, Retain, which the StatefulSet PVC Retention card covers. Scale back up and web-2 reuses the same claim, but a scale-down nobody cleans up leaves disks behind.
Play from step 5