A gRPC server on a UNIX socket (CSI_ENDPOINT, ends in .sock).
Identity (always), Controller (provision, attach, expand, snapshot), Node (stage, publish, stats). Also GroupController and alpha SnapshotMetadata.
Capabilities switch steps off, down to NodePublish and NodeUnpublish only. No capability says "block".
Capability
Without it
CREATE_DELETE_VOLUME
provisioner refuses
PUBLISH_UNPUBLISH_VOLUME
"trivial handler"
STAGE_UNSTAGE_VOLUME
kubelet skips NodeStage
VOLUME_MOUNT_GROUP
kubelet applies fsGroup
EXPAND, MODIFY, CLONE ...
no resize, VAC, copies
Plus plugin CONTROLLER_SERVICE to provision. v1.37 vendors a commit just before spec v1.13.0.
2.Two halves, two callers
Controller plugin : Deployment or StatefulSet, leader election. More replicas add availability, not throughput. Sidecars share the socket in an emptyDir.
Node plugin : privileged DaemonSet, Bidirectional propagation on /var/lib/kubelet/pods and .../plugins (staging). Privileged Pod Security level.
3.The sidecars
Sidecar
Calls
Newest
external-provisioner
Create / Delete
v6.3.0
external-attacher
Publish / Unpublish
v4.13.0
external-resizer
Expand / Modify
v2.3.0
csi-snapshotter
CreateSnapshot
v8.6.0
external-health-monitor
VolumeHealth
v0.19.0
node-driver-registrar
GetPluginInfo only
v2.18.0
livenessprobe
Probe
v2.20.0
Each controller sidecar is a reconcile loop with leader election. Checked 2026-10-07 : provisioner --timeout is 10s in code (README : 15s), set it for slow backends. Resizer image tops out at v2.2.1. The health monitor exits unless the driver advertises health.
4.Registration on a node
Registrar : GetPluginInfo only, then a socket in plugins_registry/. Kubelet (inotify) : GetInfo, NodeGetInfo (2m), then the csi.volume.kubernetes.io/nodeid annotation.
--kubelet-registration-path = host path of the driver socket. Wrong : not found in the list of registered....
Same watcher as DRA, no maxSurge upgrades (all send "1.0.0").
5.Three API objects
CSIDriver : 11 fields in v1.37, two immutable (path misspelled spec.attachedRequired). No object is not neutral : attach stays on, no Pod info, tokens or inline.
CSINode : by the kubelet, never the driver. nodeID, topologyKeys (keys only), allocatable.count.
VolumeAttachment : csi-<sha256(handle+driver+node)>. spec immutable, status only by the attacher.
In short : Sidecars turn PVCs, VolumeAttachments and snapshots into calls on the controller half; the kubelet calls the node half itself once the registrar announces its socket.
1.Provision : PVC to PV
PV controller : ExternalProvisioning. WaitForFirstConsumer waits for selected-node.
external-provisioner : CreateVolume pvc-<UID>, minus reserved keys; writes the PV, finalizer.
No secret : provisioning fails, deletion does not.
Reserved key
Becomes
Read by
fstype
PV fsType
kubelet
provisioner-secret-*
Create, Delete
provisioner
*-publish-, node-stage-*
PV *SecretRef
attacher, kubelet
*-expand-, *-modify-*
refs, annotation
resizer, kubelet
Prefix csi.storage.k8s.io/. Secrets : -name / -namespace, templates like ${pvc.namespace}.
2.Attach : the VA handshake
The attach-detach controller (ADC) creates VA csi-<sha256>, waits 2m for status.attached.
external-attacher : finalizer, node ID from CSINode, ControllerPublishVolume, attachmentMetadata.
Immutable. v1.36+ : flipping to false cleans old VAs.
Reconcile every 100ms. Only the first access mode is sent (RWO as 7 if advertised). Before v1.24 : .../csi/pv/<pv>/globalmount.
5.Teardown and kubelet restart
Unpublish, Unstage (last Pod on the node), volumesInUse cleared (0 to 10s), VA deleted, ControllerUnpublish (observed : 34.327, 34.428, 35.118). Why : Volume Operations.
DeleteVolume is retried : idempotent. A VA left : VolumeFailedDelete ... still attached. Reconstruction (GA v1.30) : a restarted kubelet rebuilds from vol_data.json and re-issues Stage and Publish.
In short : Provision makes the PV, attach is a VolumeAttachment the attacher answers, stage mounts once per node, publish once per Pod, and teardown runs backwards, gated by volumesInUse.
1.Volumes that skip steps
Raw block : volumeMode: Block, devicePath, no fsType; paths under .../csi/volumeDevices/, held by a loop device.
Pod authors set volumeAttributes; restricted Pod Security allows csi. Guard with admission.
Generic : PVC <pod>-<volume>, no PVC create right needed. Names collide : pod is not owner.
3.Credentials into drivers
tokenRequests : Pod-bound token per audience, 600s minimum. Refresh : RBAC; vs projected.
Node audience restriction (beta, on) : only audiences used on that node.
requiresRepublish : republish on pod syncs (1m to 1.5m, labs 17s to 80s), not 0.1s. Contents only.
Tokens in
volume_context
secrets
When
default
field true
Logs
printed
stripped
API warning
yes, if unset
no
Real leaks
CVE-2023-2878, CVE-2024-3744
serviceAccountTokenInSecrets (GA v1.36) without tokenRequests, even false : rejected. Real drivers : SPIFFE CSI, Secrets Store CSI (ESO).
4.Migration and what comes next
Ten in-tree plugins were removed (1.26 to 1.36). Seven types need their CSI driver (Volumes). CephFS, RBD, GlusterFS have no translator : move by hand first. FlexVolume : deprecated, still there.
Horizon : all-in-one sidecars (KEP-4958, alpha target v1.38); COSI v1alpha2 only on main (tag v0.2.2).
5.Debugging and commands
Attach and mount symptoms : Volume Operations. -v=5 driver logs are sanitized (not hostpath's gRPCCall).
Symptom
Look at
Cause and fix
PVC Pending, only ExternalProvisioning
provisioner, leader
provisioner down, or another driver named
does not support snapshot restore
dataSource
no CREATE_DELETE_SNAPSHOT (clones: CLONE_VOLUME), no RPC
timed out waiting for external-attacher
VAs, attacher pods
deploy one, or recreate with attachRequired false
not found in the list of registered
registrar logs
no node plugin, wrong path
VA CSINode ... does not contain driver
kubectl get csinode
not registered on that node
volume mode "Ephemeral" not supported
volumeLifecycleModes
inline volume, Persistent-only driver
Command
Shows
kubectl logs <controller-pod> -c csi-attacher
Trivial sync started
kubectl logs <node-pod> -c node-driver-registrar
GetInfo, NotifyRegistrationStatus
ls -l /var/lib/kubelet/plugins_registry/ /var/lib/kubelet/plugins/
In short : Variants skip or swap lifecycle steps, tokens belong in the secrets field, and a stuck volume's message names the part to read : provisioner, attacher or registrar.