Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 78 ยท Storage

StorageClasses and Dynamic Provisioning

Use StorageClasses so Kubernetes creates disks on demand: provisioners, volume binding modes, volume expansion, CSI drivers, snapshots and the default class.

Creating a PersistentVolume by hand for every claim does not scale. In a real cluster nobody waits for an administrator to carve out a disk; you write a claim, and a disk appears. That is dynamic provisioning, and the object that makes it work is the StorageClass: a named recipe that says which driver creates the storage and with which settings ("fast SSD, encrypted, delete when done").

This lesson covers the fields of a StorageClass, the difference between Immediate and WaitForFirstConsumer binding, volume expansion, the default class, the CSI architecture behind it all, and snapshots. It follows PersistentVolumes and claims. Cloud disks and CSI drivers are not available on this site, so the manifests are read-only and a Python stand-in simulates the provisioner.

From claim to disk

Claim A PVC names a StorageClass.
Class The class picks the driver and settings.
Provisioner The driver creates the real disk.
Bind A PV is created and bound to the claim.

No administrator has to be involved.

1 / 2

A StorageClass

Here is a typical class for an AWS cluster with the EBS CSI driver:

YAML
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  encrypted: "true"
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
mountOptions:
  - noatime

The fields mean:

  • provisioner: the driver that creates volumes (ebs.csi.aws.com, pd.csi.storage.gke.io, disk.csi.azure.com, rancher.io/local-path on k3s and many local setups, and so on). Classes with kubernetes.io/no-provisioner create nothing and only describe pre-made PVs, as used for local disks.
  • parameters: opaque, driver-specific settings such as disk type, IOPS, filesystem type or encryption. Kubernetes passes them through untouched.
  • reclaimPolicy: copied onto each PV the class creates. The default is Delete.
  • volumeBindingMode: Immediate or WaitForFirstConsumer (below).
  • allowVolumeExpansion: lets users grow claims later.
  • mountOptions: passed to mount when the volume is attached.
  • allowedTopologies: restrict the zones where volumes may be created.

A StorageClass cannot be edited after creation for most fields (provisioner, parameters and others are immutable), so to change one you create a new class and move workloads over.

Using a class

A claim just names the class:

YAML
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: db-data
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: fast-ssd
  resources:
    requests:
      storage: 50Gi

If storageClassName is omitted, the cluster's default class is filled in (the one carrying the is-default-class: "true" annotation). If it is set to "", dynamic provisioning is disabled for that claim, and it only binds to classless pre-made PVs. Keep exactly one default class; with several, the newest one wins, which is a confusing way to find out. On a cluster with no default class, claims without a class stay Pending.

Terminal
kubectl get storageclass
kubectl patch storageclass fast-ssd -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'

Immediate versus WaitForFirstConsumer

Cloud disks live in one availability zone and can only be attached to nodes in that zone. Consider what Immediate does: the claim appears, the provisioner picks a zone (say, zone-a) and creates the disk right away. The scheduler later places the pod on a node in zone-b, because that node has more free CPU. The pod can never start: its disk is in the wrong zone. The scheduler would have to choose again, but the volume is already bound.

WaitForFirstConsumer avoids that. The claim stays Pending ("waiting for first consumer") until a pod that uses it is scheduled. The scheduler considers the volume's constraints while picking a node, and the provisioner then creates the disk in that node's zone. This is the right mode for any zonal or local storage, and most managed clusters now default to it.

sequenceDiagram
    participant U as User
    participant C as PVC
    participant S as Scheduler
    participant P as Provisioner
    U->>C: Create claim (WaitForFirstConsumer)
    Note over C: Pending, no disk yet
    U->>S: Create pod using the claim
    S->>S: Pick node in zone-b
    S->>P: Provision in zone-b
    P->>C: Disk created, PV bound

The disk is created only after the scheduler has chosen a node, so it lands in the right zone.

Simulating a provisioner

The stand-in below models a tiny cluster with two zones and a provisioner that creates a "disk" per claim. The pods can only run on nodes in the same zone as their disk, and the scheduler favors the node with the most free CPU, so the zone is chosen by CPU, not by the disk.

Python Dynamic provisioning: Immediate vs WaitForFirstConsumer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In this tiny model both modes end well, but look at the difference. With Immediate the pod is squeezed onto node-1, whose CPU is nearly exhausted, because the disk was already fixed to zone-a. With WaitForFirstConsumer the pod goes to the best node, and the disk follows. In real clusters the Immediate case is worse: when the only node in the disk's zone is full or tainted, the pod stays Pending forever, even while other zones have room.

Expanding volumes

If the class has allowVolumeExpansion: true, you grow a claim by editing its request:

Terminal
kubectl patch pvc db-data -p '{"spec":{"resources":{"requests":{"storage":"100Gi"}}}}'
kubectl get pvc db-data -w

The driver resizes the disk, and the filesystem is grown either immediately (online expansion, supported by most CSI drivers) or the next time the pod restarts. You can only grow; asking for a smaller size is rejected by the API server. Plan sizes with some headroom, and if the class forbids expansion, the only route is to create a new claim and copy the data.

Python Default class and expansion rules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

CSI: the driver interface

Storage vendors plug into Kubernetes through the Container Storage Interface (CSI), a standard gRPC API shared with other orchestrators. A CSI driver is deployed in the cluster as two parts:

  • A controller component (a Deployment) with sidecars such as external-provisioner, external-attacher, external-resizer and external-snapshotter. These watch Kubernetes objects and call the driver to create, attach, resize and snapshot disks.
  • A node component (a DaemonSet) on every node, which formats and mounts volumes for the kubelet.

When you install a managed cluster, the CSI driver for the cloud is usually preinstalled; on self-managed clusters you install it yourself (Helm charts exist for most drivers). The provisioner: in a StorageClass is the driver name. Old in-tree plugins such as kubernetes.io/aws-ebs have been migrated to CSI.

Snapshots and clones

CSI drivers that support it can take point-in-time snapshots of a claim, using three objects from the snapshot.storage.k8s.io API group (installed as add-ons; the CRDs and the snapshot controller are not part of every cluster):

YAML
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: ebs-snapshots
driver: ebs.csi.aws.com
deletionPolicy: Delete
---
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: db-before-upgrade
spec:
  volumeSnapshotClassName: ebs-snapshots
  source:
    persistentVolumeClaimName: db-data

To restore, create a new claim whose dataSource points at the snapshot:

YAML
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: db-data-restored
spec:
  storageClassName: fast-ssd
  dataSource:
    name: db-before-upgrade
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 50Gi

The same dataSource field accepts another PVC (kind PersistentVolumeClaim) for a clone, if the driver supports it. A snapshot of a running database is only crash-consistent unless the application is quiesced first, a point we return to in databases and backups.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a StorageClass describe?

    A StorageClass is a recipe for dynamic provisioning, naming a provisioner plus parameters, reclaim policy, binding mode and expansion setting.
  2. 2. Why is WaitForFirstConsumer recommended for zonal cloud disks?

    With Immediate, the disk may be created in a zone where the pod cannot run. WaitForFirstConsumer lets scheduling decide first.
  3. 3. A PVC sets storageClassName to an empty string. What does that mean?

    An omitted field gets the default class, while an explicit empty string means no class at all, so only pre-created classless PVs can match.
  4. 4. You try to change a 100Gi claim to 40Gi. What happens?

    Kubernetes supports growing volumes (when the class allows expansion) but never shrinking.
  5. 5. How do you restore data from a VolumeSnapshot?

    A new claim with dataSource kind VolumeSnapshot makes the driver create a fresh volume from the snapshot contents.

Summary

  • A StorageClass names a provisioner, its parameters, a reclaim policy, a binding mode and whether expansion is allowed.
  • A claim without storageClassName gets the default class; an empty string disables dynamic provisioning.
  • Use WaitForFirstConsumer for zonal or local storage so the disk is created where the pod is scheduled.
  • Volumes can grow if allowVolumeExpansion is true, never shrink.
  • CSI drivers run as a controller Deployment plus a node DaemonSet and enable provisioning, resizing and snapshots.
  • Snapshots and clones are restored through a PVC dataSource; test restores, do not just take snapshots.

Next: Running Databases and Backups