Container Storage Interface (CSI)

Decoupling storage providers from Kubernetes — the plugin architecture

Why CSI Exists

CSI Architecture

A CSI driver deploys two components in the cluster:

Topology Diagram

Sidecar Containers

CSI drivers don't talk to the K8s API directly. Instead, sidecar containers (maintained by the K8s storage SIG) bridge the gap between K8s API objects and CSI gRPC calls:

Full Volume Lifecycle Through CSI

1. Provision (Dynamic)
   User creates PVC → external-provisioner watches PVC → calls CreateVolume on CSI controller → storage backend creates volume → external-provisioner creates PV → PVC binds to PV.
2. Attach
   Pod is scheduled to a node → kubelet creates VolumeAttachment object → external-attacher watches → calls ControllerPublishVolume on CSI controller → storage backend makes volume accessible to node (e.g., iSCSI login, EBS attach API call).
3. Stage (Node)
   kubelet calls NodeStageVolume on CSI node plugin → format filesystem if needed (mkfs.ext4) → mount to a global staging path on the node (e.g., /var/lib/kubelet/plugins/kubernetes.io/csi/...).
4. Mount (Node)
   kubelet calls NodePublishVolume on CSI node plugin → bind mount from the staging path to the pod's volume directory (e.g., /var/lib/kubelet/pods/<uid>/volumes/...).
5. Unmount
   Pod terminates → kubelet calls NodeUnpublishVolume → removes the bind mount from the pod's directory.
6. Unstage
   No more pods using the volume on this node → kubelet calls NodeUnstageVolume → unmount from the global staging path.
7. Detach
   kubelet deletes VolumeAttachment → external-attacher calls ControllerUnpublishVolume → storage backend detaches volume from node (e.g., EBS detach API call).
8. Delete
   PVC deleted + Delete reclaim policy → external-provisioner calls DeleteVolume → storage backend deletes volume → PV deleted.

Visual Flow: Mount Path

1. CreateVolume

   Storage backend creates volume

2. ControllerPublish

   Volume attached to node

3. NodeStage

   Format + mount to staging path

4. NodePublish

   Bind mount into pod

1. NodeUnpublish

   Unmount from pod

2. NodeUnstage

   Unmount from staging

3. ControllerUnpublish

   Detach from node

4. DeleteVolume

   Backend deletes volume

Volume Snapshots

VolumeSnapshotClass defines the snapshot provider — analogous to StorageClass for provisioning.

Creating a Snapshot

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: my-snapshot
spec:
  volumeSnapshotClassName: csi-snapclass
  source:
    persistentVolumeClaimName: my-data   # PVC to snapshot

Restoring from a Snapshot

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: restored-data
spec:
  storageClassName: fast-ssd
  dataSource:                           # restore from snapshot
    kind: VolumeSnapshot
    name: my-snapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

Ephemeral CSI Volumes

Short-lived volumes created and deleted with the pod (like emptyDir, but via CSI). The pod spec includes the CSI volume definition inline — no PVC needed.

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app
      image: my-app:latest
      volumeMounts:
        - name: secrets
          mountPath: /mnt/secrets
          readOnly: true
  volumes:
    - name: secrets
      csi:
        driver: secrets-store.csi.k8s.io
        readOnly: true
        volumeAttributes:
          secretProviderClass: vault-secrets

CSI Driver Examples

CSI vs In-tree: Summary