Topology = the PV spec.nodeAffinity. Terms are ORed, expressions in a term ANDed.
CSINode topologyKeys are key names. The values are Node labels.
Immediate is the default. The mode is immutable.
Mode
Immediate
WFFC
Volume made
PVC created
Pod scheduled
Zone from
provisioner
scheduler's node
Capacity
never
if storageCapacity
Pod, unbound
Pending
normal
Risk
full zone
stale selected-node
2.VolumeBinding in the framework
A missing class or a pre-bound claim counts as immediate.
bindTimeoutSeconds: 0 fails at once, not "no wait". The waiting node shows as NOMINATED NODE.
UnschedulableAndUnresolvable : evicting cannot help, so no preemption (Advanced Scheduling).
3.The handshake, end to end
PVC events : WaitForFirstConsumer, WaitForPodScheduled, ExternalProvisioning. Basics : Volumes and Storage. A nodeName pin skips the scheduler : a bound PV fails MountVolume.NodeAffinity check failed, a WFFC claim never binds.
4.What CreateVolume receives
Plain WFFC : requisite is the aggregated topology, every Node with the key labels, driver or not.
allowedTopologies keys must be driver keys, or ... is not in requisite.
Node-local storage : --strict-topology.
Node in zone b
requisite
preferred
WFFC, plain
a, b, c
b, c, a
WFFC, strict
b
b
WFFC, allowed a, b
a, b
b, a
Immediate
a, b, c
hash(set) + ordinal
Immediate, topology off
none
none
5.Provisioning fails on the node
Only RESOURCE_EXHAUSTED (or an uncached CSINode NotFound) frees the Pod.
v6.0.0 and v6.1.0 could retry in the wrong zone : use v6.0.1, v6.1.1, v6.2.0+.
CreateVolume
Provisioner
Pod
RESOURCE_EXHAUSTED
drops the annotation
rescheduled
INVALID_ARGUMENT
5m slow retry
pinned
anything else
same node, backoff
pinned, 600s
6.Commands
Command
Shows
kubectl get pvc <pvc> -o jsonpath='{.metadata.annotations.volume\.kubernetes\.io/selected-node}'
Node picked (empty if static)
kubectl get pod <pod> -o jsonpath='{.status.conditions[?(@.type=="PodScheduled")].message}'
Current verdict (events lag)
kubectl get events --field-selector involvedObject.name=<pvc>
PVC events, ProvisioningFailed
kubectl describe pv <pv>
Node Affinity, Term 0
In short : With WaitForFirstConsumer the scheduler picks the node and the driver's answer becomes the PV's nodeAffinity. With Immediate the volume picks first and the Pod must follow.
1.Storage capacity tracking
Opt in : CSIDriver storageCapacity: true and provisioner --enable-capacity. Objects land in the provisioner's namespace.
Only new volumes of WFFC classes are checked. No match : did not have enough free storage.
Each claim checked alone, new volumes not subtracted, data up to 1m old.
Flag true before any object exists blocks every node : ship false, then flip.
Matched by class name only : write access to csistoragecapacities steers scheduling (RBAC).
Field
Rule
Used by
nodeTopology
nil = none, {} = all
Filter
storageClassName
name only
Filter
capacity
available_capacity
Filter, Score
maximumVolumeSize
optional
Filter first
The first two are immutable. Flag turned off : PVC Pods wait for the 5 min flush.
3.Storage scoring in v1.37
StorageCapacityScoring : beta and on.
Dynamic : most free space wins. Static : the node whose smallest fitting PV is largest wins.
Weight 1. Gate off with a shape set : kube-scheduler will not start.
Claim, space
%
Def.
Inv.
10Gi, 100Gi
10
90
10
10Gi, 50Gi
20
80
20
50Gi, fit 200Gi
25
75
-
50Gi, fit 100Gi
50
50
-
50Gi, PVs 60 + 500Gi
83
17
-
4.Attach slots per node
NodeVolumeLimits checks unique volumes against CSINode allocatable.count (in-tree EBSLimits and co : removed v1.32). Over : exceed max volume count, preemption may run.
nodeAllocatableUpdatePeriodSeconds (>= 10, GA v1.36) and external-attacher v4.10.0+ : a code 8 attach fails the Pod for a new one.
5.Nodes without the driver
VolumeLimitScaling (beta, on) : the flag rejects driverless nodes : <driver> CSI driver is not installed on the node.
Only with CA --enable-csi-node-aware-scheduling=true (1.35.0+, default false) or no autoscaler. Karpenter : out of scope.
kind: CSIDriver # name: ebs.csi.aws.com
spec:
attachRequired: true
nodeAllocatableUpdatePeriodSeconds: 60
preventPodSchedulingIfMissing: true
# CA flag first, or no autoscaler
6.Commands
Command
Shows
kubectl describe csinode <node>
Node ID, count, topology keys
kubectl get csidriver <d> -o jsonpath='{.spec.preventPodSchedulingIfMissing} {.spec.nodeAllocatableUpdatePeriodSeconds}'
The two fields get hides
kubectl get csistoragecapacities -A -o custom-columns='SC:.storageClassName,CAP:.capacity,MAX:.maximumVolumeSize,TOPO:.nodeTopology.matchLabels'
What the scheduler matches
kubectl get volumeattachments -o custom-columns='NODE:.spec.nodeName,CODE:.status.attachError.errorCode'
Code 8 = RESOURCE_EXHAUSTED
In short : The scheduler counts two scarce things per node : free space, from CSIStorageCapacity hints, and attach slots, from CSINode counts. v1.37 scores space by default.
1.Who says no, and can preemption help ?
Each node reports only its first failing filter, so one reason can hide another. Alerts on had volume node affinity conflict (renamed v1.33) are silent.
Plugin
Reason, node(s) ...
Status
Preempt ?
VolumeBinding
didn't match PersistentVolume's node affinity, didn't find available persistent volumes to bind, did not have enough free storage. PreFilter : pod has unbound immediate PersistentVolumeClaims
...Unresolvable
never
VolumeZone
had no available volume zone (legacy PV zone labels only)
...Unresolvable
never
NodeVolumeLimits
exceed max volume count, <driver> CSI driver is not installed
Unschedulable
possible
VolumeRestrictions
RWOP claim already in-use by another pod
Unschedulable
possible
...Unresolvable = UnschedulableAndUnresolvable, also given by the last two for a missing PVC.
2.Reading one FailedScheduling message
Format : Advanced Scheduling. A PreFilter failure gives one reason. A trailing . not found in v1.37 is DRA noise.
3.Node-local storage
local-static-provisioner v2.9.0 : one PV per disk, can drop a startup taint once disks are found.
Node-local CSI (TopoLVM, host-path) : strict topology, provisioner central or per node.
Node deleted : PV stays, Pod Pending. Same name reused : wrong disk.
local-static
Node-local CSI
Volumes
pre-made disks
carved per claim
Key
kubernetes.io/hostname
driver key
Class
no-provisioner + WFFC
driver + WFFC
Scheduler sees
PV sizes
CSIStorageCapacity
v1.37 score
largest best fit
most free space
Node loss
node-cleanup (opt-in)
force-delete PV
4.A zone dies under a StatefulSet
A bound replica fails PV affinity everywhere, spare PVs or not. Dropping its PVC still hits zone spread unless nodeTaintsPolicy: Honor (GA v1.33) skips tainted nodes. Old Pod gone first : Volume Operations.
In short : Binding and zone rejections never preempt, attach-limit and RWOP ones can. Plan for node and zone loss : nodeTaintsPolicy: Honor, a node group per zone, a restore path.