Immediate vs WaitForFirstConsumer
Why can a Pod sit in Pending in a multi-zone cluster with a healthy disk right there? With volumeBindingMode Immediate the volume is provisioned the instant the claim exists, in any zone the class allows, and the Pod is stuck if no Node then both fits it and lies in that zone. WaitForFirstConsumer inverts the order so the Scheduler chooses the Node first. The field is set when the class is created, and it prevents this common multi-zone failure.
Play the animation 5 steps, animated, best on a wide screen
Immediate vs WaitForFirstConsumer, step by step
-
With Immediate and no matching PV, the volume is provisioned the moment the claim appears, long before any Pod is scheduled. With no Pod to guide it, the provisioner may pick any zone the class allows. Here it lands in zone-a, and the claim is Bound to a PV whose node affinity names zone-a, so here only Node-1 can reach it.
Play from step 1 -
Only now is the Pod created, and it has to be placed around a disk that already lives in zone-a. This Pod fits Node-2 in zone-b on capacity and affinity, but a zone-a disk cannot attach to a Node in zone-b. Volume topology is read during scheduling, so Node-2 is rejected, while Node-1 in zone-a has no room for the Pod.
Play from step 2 -
No Node satisfies both the Pod and its zone-a disk, so the Pod is not scheduled. It stays Pending until a zone-a Node has room, and its FailedScheduling event reports one Node short of CPU and one that did not match the PersistentVolume node affinity. This is a common multi-zone failure, and the class field that prevents it is next.
Play from step 3 -
Start over with a new class set to WaitForFirstConsumer, since the mode cannot be edited. The claim waits in Pending. The Scheduler picks Node-2 first, records it on the claim as selected-node, and waits up to 600s by default for the volume to bind. A Pod with nodeName set skips the Scheduler, and its claim stays Pending.
Play from step 4 -
Now that a Node is chosen, the zone to build in is no longer a guess. The provisioner reads selected-node and creates the volume in zone-b, and the claim binds. Only then is the Pod bound to Node-2, and the disk attached there. The Kubelet mounts it and the Pod starts, because the order was reversed so the disk could follow the Pod.
Play from step 5