Create a CSI StorageClass and Trace the Provisioned Volume

Original Prepium guide · Written for Kubernetes v1.35 and checked against the official documentation on 6 October 2026. Use a disposable practice cluster. You need at least one CSI driver installed; kubectl get csidrivers must list something before the steps below can provision anything.

From StorageClass to CSI driver: how dynamic provisioning picks its storage

A CSI driver is storage code that runs outside Kubernetes and plugs in through the Container Storage Interface. Kubernetes never talks to it directly from your claim: the claim names a StorageClass, the class names the driver in its provisioner field, and the driver creates a volume that comes back as a PersistentVolume carrying spec.csi.driver. Knowing that chain lets you build a class quickly and prove which backend actually holds the data.

PVC (storageClassName) ──→ StorageClass (provisioner, reclaimPolicy, volumeBindingMode)
                                   │ asks the CSI driver for a volume
PV  (spec.csi.driver, spec.csi.volumeHandle, persistentVolumeReclaimPolicy) ──→ bound to the PVC

1. Find the installed driver names

kubectl get csidrivers
kubectl get storageclass
DRIVER=$(kubectl get csidrivers -o jsonpath='{.items[0].metadata.name}'); echo "$DRIVER"

CSIDriver objects are cluster-scoped and named after the driver's own reported name. Registering one is optional, so if the list is empty, read the driver's documentation instead. That exact string is what a StorageClass needs as its provisioner, so copy it rather than typing it from memory. If several drivers are listed, pick one deliberately instead of trusting items[0].

2. Create a class and a claim

kubectl create namespace prepium-tutorial
cat <<EOF | kubectl apply -f -
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: tutorial-csi
provisioner: $DRIVER
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: notes
  namespace: prepium-tutorial
spec:
  storageClassName: tutorial-csi
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 64Mi
EOF
kubectl -n prepium-tutorial get pvc notes

The claim sits in Pending, which is expected here. WaitForFirstConsumer delays binding and provisioning until a Pod that uses the claim exists, so the volume can be placed where that Pod is scheduled. With Immediate (the default when the field is omitted) the volume is created as soon as the claim is. Some drivers also expect parameters; check your driver's documentation if provisioning stalls.

3. Give it a consumer, then trace the volume

kubectl -n prepium-tutorial run notes-writer --image=busybox:1.36 --restart=Never \
  --overrides='{"spec":{"containers":[{"name":"w","image":"busybox:1.36","command":["sh","-c","echo kept > /notes/a.txt; sleep 3600"],"volumeMounts":[{"name":"v","mountPath":"/notes"}]}],"volumes":[{"name":"v","persistentVolumeClaim":{"claimName":"notes"}}]}}'
kubectl -n prepium-tutorial wait --for=jsonpath='{.status.phase}'=Bound pvc/notes --timeout=120s
PV=$(kubectl -n prepium-tutorial get pvc notes -o jsonpath='{.spec.volumeName}')
kubectl get pv "$PV" -o jsonpath='{.spec.csi.driver}{"\n"}{.spec.csi.volumeHandle}{"\n"}{.spec.persistentVolumeReclaimPolicy}{"\n"}'
kubectl -n prepium-tutorial exec notes-writer -- cat /notes/a.txt

The claim's spec.volumeName is the authoritative link to its PV. On that PV, spec.csi.driver names the driver that created it and volumeHandle is the backend's own identifier. The reclaim policy was copied from the class when the PV was created.

4. Watch the reclaim policy act

kubectl -n prepium-tutorial delete pod notes-writer
kubectl -n prepium-tutorial delete pvc notes
kubectl get pv "$PV"

With Delete the PV and its backing storage are removed, so the last command soon reports NotFound. Had the class used Retain, the PV would move to Released, keep its data and refuse new claims until an administrator cleans it up by hand. That is the trade: Retain protects data from an accidental claim deletion at the cost of manual housekeeping.

Common mistakes

• Typing the provisioner by hand. A misspelt driver name is accepted in the class, but no provisioner acts on it, so claims never bind.
• Treating Pending as a fault under WaitForFirstConsumer. Creating a Pod that mounts the claim is the fix, not a static PV.
• Expecting a class change to reach existing PVs. Each PV holds its own persistentVolumeReclaimPolicy; change it on the PV with kubectl patch.
• Deleting a claim while a Pod still uses it. Storage object in use protection postpones its removal until no Pod uses it.

Cleanup: kubectl delete namespace prepium-tutorial and kubectl delete storageclass tutorial-csi. References: Storage Classes, Persistent Volumes, CSI volumes. Next, try default StorageClass handling or binding a claim to a specific PV.