Dynamic provisioning and CSI
Follow delayed binding through StorageClass selection, provisioner reconciliation, attachment and mount.
What you will understand
- Explain StorageClass parameters and provisioner ownership
- Trace WaitForFirstConsumer through scheduler topology decisions
- Separate CSI provisioning, attachment and node mounting failures
Builds on: Volumes and persistent claims
Mental model: the claim describes demand, the class selects a supply mechanism
A StorageClass describes a storage offering: which provisioner should create volumes, provider-specific parameters, binding mode, reclaim policy and expansion policy. It is cluster-scoped, while PVCs are namespaced. A PVC can explicitly name a class or use the applicable default. An explicit empty storageClassName asks for no class, which is different from omitting the field and allowing defaulting. Inspect the admitted claim to see which class is actually selected.
Dynamic provisioning turns a claim into storage through a controller and storage backend. The API server does not allocate a disk itself. A provisioner observes the claim, creates a backend volume, and arranges the PV that will bind to it. A missing driver, exhausted backend quota or invalid class parameter can leave the claim Pending even though the YAML is valid. Events often name the provisioner being awaited, giving a better starting point than repeatedly deleting and recreating the claim.
Wait for placement before choosing a storage zone
Follow a delayed-binding PVC through scheduler topology selection and dynamic provisioning.
The PVC names a real StorageClass whose provisioner and parameters define the storage mechanism.
- PVC report-data to StorageClassclass reference
Read the complete visual sequence
- Select a storage offering
The PVC names a real StorageClass whose provisioner and parameters define the storage mechanism.
- Wait for a consumer
The class delays binding so the workload zone can influence storage allocation. Pending is expected at this step.
- Coordinate placement
The consumer requires west, so scheduler and volume binding coordination select a compatible node and storage topology.
- Provision and bind
The provisioner creates compatible storage and its PV, which binds to the PVC before mounting can finish.
Immediate binding picks the wrong zone
Storage exists in east before a west-only consumer appears.
- Early allocation
Immediate provisioning creates an east volume without the future consumer constraints.
- Workload cannot use it
The west-only Pod has no node compatible with both its affinity and the bound volume topology.
- Repair without discarding data
Review class binding mode for future claims; migrate existing data deliberately rather than deleting the bound volume impulsively.
About this model
A topology-aware provisioner supports WaitForFirstConsumer; no spec.nodeName bypass.
Walkthrough: delay a decision until workload topology is known
Storage can have locality constraints: a cloud disk may exist in one zone, and a local volume may exist on one worker. Immediate binding can choose storage before the consuming Pod’s placement constraints are known. WaitForFirstConsumer delays binding or provisioning until scheduling can account for a consumer’s topology. This avoids allocating a volume in a zone that the consuming Pod cannot use.
# Inspect the existing class; do not substitute an invented driver name.
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: report-data
spec:
storageClassName: standard # Replace with an actual lab class.
accessModes: [ReadWriteOnce]
resources:
requests:
storage: 2Gi
kubectl get storageclass
kubectl get storageclass standard -o yaml
kubectl apply -f report-data.yaml
kubectl describe pvc report-data
# After creating the lab consumer Pod:
kubectl get pvc report-data -w
kubectl describe pod report-writer
If the chosen class uses WaitForFirstConsumer, a Pending claim with a message about waiting for a first consumer can be healthy. Create the workload that uses it, then follow the scheduler-selected topology and provisioning events. Do not set spec.nodeName to bypass scheduling during this experiment: that can bypass the scheduler coordination needed for delayed binding. Use node affinity or a node selector when the workload legitimately requires a placement restriction.
The Container Storage Interface, or CSI, separates Kubernetes storage integration from individual provider implementations. A driver can provide controller operations such as creating and attaching storage and node operations such as staging or publishing a volume into a Pod. Kubernetes integrations commonly use external sidecar controllers around the driver. Exact components and supported operations vary. A PV being Bound says claim matching finished; it does not prove controller attachment, node mount or filesystem ownership succeeded.
Bound, attached and mounted are separate checkpoints
Trace CSI controller and node responsibilities and explain driver-dependent expansion.
The claim binds to a PV naming the CSI driver and provider volume identity. Binding does not mount the filesystem.
- PVC + PV to CSI controllervolume identity
Read the complete visual sequence
- Bind the resource
The claim binds to a PV naming the CSI driver and provider volume identity. Binding does not mount the filesystem.
- Prepare controller-side access
For an attachment-based driver, controller operations authorize or attach the backend volume to the selected worker.
- Publish on the node
The node plugin stages and publishes the volume into the Pod path; errors here can produce FailedMount even with a Bound PVC.
- Expand with supported operations
An increased PVC request can trigger controller and filesystem expansion if the class and driver support it. Bound status alone says nothing about resize completion.
Attach succeeds but mount fails
Storage reaches the node, but filesystem publication fails.
- Controller attachment completes
The backend can be attached to the intended worker, so provisioning and binding are already past their checkpoints.
- Node mount is blocked
The node plugin cannot publish the filesystem, so the application container waits before starting.
- Inspect the node-side cause
Read Pod events and driver evidence for mount options, filesystem or permission problems; changing Service networking will not help.
About this model
A CSI driver supporting controller attachment and node staging; drivers without those capabilities skip the corresponding checkpoints.
Practice: read the lifecycle in order
Compare the PVC status, PV source and Pod events. A Pending PVC points toward class selection, binding or provisioning. FailedAttachVolume points toward attachment or topology/access limitations. FailedMount points toward node-side publication, filesystem, credentials or other mount setup. Names alone do not identify the complete cause; read the event message and relevant driver logs with an administrator when required. Do not delete a PV to clear an attachment error before understanding the data lifecycle.
Volume expansion requires support from the class and driver. With allowVolumeExpansion: true, increase the PVC’s requested size rather than editing the PV capacity as a shortcut. Controller and filesystem expansion can occur at different points, and support for online expansion depends on the driver and filesystem. Kubernetes does not support shrinking a PVC by simply lowering its requested storage. Test resizing with disposable data and watch conditions until the filesystem exposes the expected capacity.
Pitfalls: local storage is still local
A host-local provisioner can make PVCs convenient on a laptop while retaining node affinity to one worker’s directory. That is valuable for lifecycle practice but does not promise node replacement recovery. Multi-attach failures can arise when a replacement Pod tries to use a single-node-access disk while the old attachment is still active elsewhere. Resolve ownership and detach state carefully; force removal without fencing the old writer can threaten application data.
Check your understanding
A WaitForFirstConsumer PVC is Pending before any consuming Pod exists. Is provisioning necessarily broken?
No. Waiting can be the class’s intended behavior because the scheduler needs a consumer’s placement constraints before selecting a storage topology. Read the claim events and create the intended consumer. If it remains Pending afterward, investigate the workload’s scheduling constraints and provisioner events together rather than treating the PVC as an isolated object.
Use the storage lab to observe class, claim, PV and mount events in sequence. Next, recover data into a new claim instead of assuming persistence alone provides a recovery point.
Primary documentation
Go to the source
Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise