CSI is the standard plugin interface for exposing storage systems to Kubernetes. Before CSI, storage drivers were compiled into Kubernetes itself — adding a new storage backend meant changing K8s core code. CSI decouples storage plugins from the Kubernetes release cycle, allowing vendors to ship and update drivers independently.

1. CSI Architecture

A CSI driver consists of two components deployed in the cluster:

Controller Plugin (Deployment)

Handles cluster-level operations — things that don't need to run on a specific node:

Node Plugin (DaemonSet)

Handles node-level operations — mounting the volume into the Pod's filesystem:

2. CSI Sidecar Containers

The controller Pod runs the CSI driver alongside Kubernetes-maintained sidecar containers that bridge K8s API objects to CSI gRPC calls:

# Typical CSI controller Deployment has 4-5 containers:
spec:
  containers:
    - name: ebs-plugin             # The actual driver
      image: public.ecr.aws/ebs-csi-driver/aws-ebs-csi-driver:v1.25
    - name: csi-provisioner        # Watches PVCs
      image: registry.k8s.io/sig-storage/csi-provisioner:v3.6
    - name: csi-attacher           # Watches VolumeAttachments
      image: registry.k8s.io/sig-storage/csi-attacher:v4.4
    - name: csi-snapshotter        # Watches VolumeSnapshots
      image: registry.k8s.io/sig-storage/csi-snapshotter:v6.3
    - name: csi-resizer            # Watches PVC size changes
      image: registry.k8s.io/sig-storage/csi-resizer:v1.9

CSIDriver Object

# Registered when the driver is installed — tells K8s about driver capabilities:
apiVersion: storage.k8s.io/v1
kind: CSIDriver
metadata:
  name: ebs.csi.aws.com
spec:
  attachRequired: true          # Volume needs attach/detach (block storage: yes)
  podInfoOnMount: false         # Pass Pod info to NodePublish? (for audit)
  fsGroupPolicy: File           # How fsGroup is applied (File, ReadWriteOnceWithFSType, None)
  volumeLifecycleModes:
    - Persistent                # Supports PVCs
    - Ephemeral                 # Supports inline ephemeral volumes

3. Volume Snapshots

Snapshots capture the state of a volume at a point in time. They're managed via CRDs (not core K8s API):

VolumeSnapshotClass — "How to snapshot"

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: ebs-snapclass
driver: ebs.csi.aws.com
deletionPolicy: Delete            # Delete or Retain the snapshot when VolumeSnapshot is deleted

VolumeSnapshot — "Take a snapshot now"

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: db-snap-20240115
spec:
  volumeSnapshotClassName: ebs-snapclass
  source:
    persistentVolumeClaimName: db-data     # PVC to snapshot

# Check status:
kubectl get volumesnapshot db-snap-20240115
# NAME               READYTOUSE   SOURCEPVC   RESTORESIZE   AGE
# db-snap-20240115   true         db-data     50Gi          2m

Restore from Snapshot — Create PVC from Snapshot

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: db-data-restored
spec:
  storageClassName: gp3-encrypted
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 50Gi                   # Must be ≥ snapshot's restoreSize
  dataSource:
    name: db-snap-20240115            # ← Reference the snapshot
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io

4. Volume Cloning

Create a new PVC that's a copy of an existing PVC (without going through a snapshot):

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: db-data-clone
spec:
  storageClassName: gp3-encrypted
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 50Gi
  dataSource:
    name: db-data                     # ← Source PVC (not snapshot)
    kind: PersistentVolumeClaim       # ← Clone from PVC directly

5. Common CSI Drivers

6. Troubleshooting CSI Issues

# Check CSI driver Pods:
kubectl get pods -n kube-system -l app.kubernetes.io/name=aws-ebs-csi-driver

# Controller logs (provisioning failures):
kubectl logs -n kube-system deploy/ebs-csi-controller -c csi-provisioner --tail=50

# Node plugin logs (mount failures):
kubectl logs -n kube-system ds/ebs-csi-node -c ebs-plugin --tail=50

# Check VolumeAttachment (is volume attached to node?):
kubectl get volumeattachment
# NAME        ATTACHER            PV          NODE       ATTACHED   AGE
# csi-abc..   ebs.csi.aws.com     pvc-xyz..   worker-1   true       5m

# Check CSIDriver registration:
kubectl get csidriver
# NAME                  ATTACHREQUIRED   PODINFOONMOUNT   MODES
# ebs.csi.aws.com       true             false            Persistent

Common Issues

Summary

spec:
  dataSource:
    name: db-snap-20240115
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  resources:
    requests:
      storage: 50Gi  # ≥ snapshot's restoreSize