Appearance

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.

Storage viewStep 1 of 4
Select a storage offeringThe PVC names a real StorageClass whose provisioner and parameters define the storage mechanism.. PVC report-data, Requests 2Gi; class selected, active. StorageClass, WaitForFirstConsumer, active. Consumer Pod, Requires zone west, idle. Scheduler, Chooses compatible topology, idle. Provisioner, Creates west volume and PV, idle. PV west, Bound to claim, idlePVC report-data: Requests 2Gi; class selected
PVC report-dataRequests 2Gi; class selectedIn focus
StorageClass: WaitForFirstConsumer
StorageClassWaitForFirstConsumerIn focus
Consumer Pod: Requires zone west
Consumer PodRequires zone westContext
Scheduler: Chooses compatible topology
SchedulerChooses compatible topologyContext
Provisioner: Creates west volume and PV
ProvisionerCreates west volume and PVContext
PV west: Bound to claim
PV westBound to claimContext
PVC report-dataRequests 2Gi; class selectedIn focus
StorageClassWaitForFirstConsumerIn focus
Consumer PodRequires zone westContext
SchedulerChooses compatible topologyContext
ProvisionerCreates west volume and PVContext
PV westBound to claimContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Immediate binding picks the wrong zone
Select a storage offering

The PVC names a real StorageClass whose provisioner and parameters define the storage mechanism.

Read the complete visual sequence
  1. Select a storage offering

    The PVC names a real StorageClass whose provisioner and parameters define the storage mechanism.

  2. Wait for a consumer

    The class delays binding so the workload zone can influence storage allocation. Pending is expected at this step.

  3. Coordinate placement

    The consumer requires west, so scheduler and volume binding coordination select a compatible node and storage topology.

  4. 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.

  1. Early allocation

    Immediate provisioning creates an east volume without the future consumer constraints.

  2. Workload cannot use it

    The west-only Pod has no node compatible with both its affinity and the bound volume topology.

  3. 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.

Storage viewStep 1 of 4
Bind the resourceThe claim binds to a PV naming the CSI driver and provider volume identity. Binding does not mount the filesystem.. PVC + PV, Bound storage identity, ready. CSI controller, Provision / attach operations, active. Storage backend, Disk or filesystem service, idle. CSI node plugin, Stage / publish on worker, idle. Application, /data mount visible, idlePVC + PV: Bound storage identity
PVC + PVBound storage identityReady
CSI controller: Provision / attach operations
CSI controllerProvision / attach operationsIn focus
Storage backend: Disk or filesystem service
Storage backendDisk or filesystem serviceContext
CSI node plugin: Stage / publish on worker
CSI node pluginStage / publish on workerContext
Application: /data mount visible
Application/data mount visibleContext
PVC + PVBound storage identityReady
CSI controllerProvision / attach operationsIn focus
Storage backendDisk or filesystem serviceContext
CSI node pluginStage / publish on workerContext
Application/data mount visibleContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Attach succeeds but mount fails
Bind the resource

The claim binds to a PV naming the CSI driver and provider volume identity. Binding does not mount the filesystem.

Read the complete visual sequence
  1. Bind the resource

    The claim binds to a PV naming the CSI driver and provider volume identity. Binding does not mount the filesystem.

  2. Prepare controller-side access

    For an attachment-based driver, controller operations authorize or attach the backend volume to the selected worker.

  3. 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.

  4. 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.

  1. Controller attachment completes

    The backend can be attached to the intended worker, so provisioning and binding are already past their checkpoints.

  2. Node mount is blocked

    The node plugin cannot publish the filesystem, so the application container waits before starting.

  3. 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

Search the book

Search loads when you open it.