Study guide
5.5 Container Storage Interface (CSI) Architecture & Drivers
Certified Kubernetes Administrator CKA
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: CKA Exam Environment & Cluster Architecture
1.1 CKA Exam Mechanics, Scoring & Remote Terminal Environment 1.2 Kubernetes Control Plane & Worker Node Components 1.3 etcd Architecture, Clustering & Raft Consensus 1.4 Initializing Clusters with Kubeadm 1.5 Highly Available (HA) Control Plane Topologies 1.6 Cluster Lifecycle & Step-by-Step Upgrades 1.7 etcd Snapshot Backup and Restore Procedures
2 Chapter 2: Cluster Extensions, Packaging & RBAC
2.1 Kubernetes TLS Certificates & PKI Infrastructure 2.2 Managing Kubeconfig Files, Users, & Contexts 2.3 Installing Cluster Components with Helm & Kustomize 2.4 Role-Based Access Control (RBAC): Roles & RoleBindings 2.5 ClusterRoles & ClusterRoleBindings 2.6 Custom Resource Definitions (CRDs) & Operators 2.7 Pod Security Standards (PSS) & Admission Controllers
3 Chapter 3: Workloads, Lifecycle & Pod Scheduling
3.1 Pod Lifecycle, Multi-Container Patterns & Init Containers 3.2 Deployments: Rolling Updates, Rollouts & Rollbacks 3.3 DaemonSets & StatefulSets Architecture 3.4 Batch Workloads: Jobs & CronJobs 3.5 Managing ConfigMaps & Sensitive Data with Secrets 3.6 Resource Requests, Limits & Namespace ResourceQuotas 3.7 NodeSelectors, Node Affinity & Anti-Affinity 3.8 Node Taints & Pod Tolerations 3.9 Autoscaling: Horizontal Pod Autoscaler (HPA) & Custom Metrics
4 Chapter 4: Services, Networking & Ingress Architecture
4.1 Kubernetes IP-per-Pod Model & CNI Plugins (Flannel, Calico, Cilium) 4.2 Services Deep Dive: ClusterIP, NodePort, LoadBalancer & EndpointSlices 4.3 Kube-Proxy Service Dataplane: iptables, nftables, IPVS & eBPF 4.4 CoreDNS Configuration, Resolution & Custom Forwarding 4.5 NetworkPolicies: Ingress, Egress & Default-Deny Isolation 4.6 Ingress Architecture, Controllers & Path-Based Routing 4.7 Gateway API: GatewayClass, Gateway, HTTPRoute & Traffic Splitting 4.8 External Traffic Ingress: NodePort, Cloud LoadBalancers & MetalLB
5 Chapter 5: Storage Architecture & Persistent Volumes
5.1 Ephemeral Volumes, EmptyDir, HostPath & Config Volumes 5.2 PersistentVolumes (PV) & PersistentVolumeClaims (PVC) Lifecycle 5.3 StorageClasses, Dynamic Provisioning & VolumeBindingModes 5.4 Storage Access Modes, Reclaim Policies & Volume Expansion 5.5 Container Storage Interface (CSI) Architecture & Drivers 5.6 StatefulSet VolumeClaimTemplates & Persistent Storage Workflows
6 Chapter 6: Advanced Troubleshooting, Monitoring & Maintenance
6.1 Systematic Kubernetes Troubleshooting Methodology 6.2 Node Failure, Kubelet Diagnostics & Systemd Services 6.3 Control Plane Failures, Static Pods & Component Logs 6.4 etcd Troubleshooting, Quorum Loss & Database Defragmentation 6.5 Pod Startup Failures, CrashLoopBackOff & OOMKilled Diagnostics 6.6 Workload Scheduling Failures & Resource Constraint Resolution 6.7 Container & Node Logging Architecture, Journalctl & Fluentd 6.8 Metrics Server, Resource Utilization & Kubectl Top 6.9 Service, Endpoint & Ingress Connectivity Troubleshooting 6.10 Storage Failures: PVC Pending, Mount Failures & Multi-Attach Errors 6.11 NetworkPolicy Isolation & CoreDNS Resolution Diagnostics
5.5 Container Storage Interface (CSI) Architecture & Drivers
Key Takeaways Explain This Topic AI
The Container Storage Interface (CSI) replaces legacy in-tree volume plugins with an out-of-tree, gRPC-based standard that decouples storage vendor drivers from core Kubernetes release cycles.
CSI architecture splits into Control Plane Controller Sidecars (csi-provisioner, csi-attacher, csi-resizer, csi-snapshotter, livenessprobe) and a Node Plugin DaemonSet.
The CSI Node Plugin executes a two-phase mounting process: NodeStageVolume formats and mounts the volume to a global node staging directory, and NodePublishVolume bind-mounts it into the Pod container directory.
CSIDriver and CSINode API objects register storage driver capabilities (fsGroupPolicy, attachRequired) and track node-specific topology and volume attachment limits.
VolumeSnapshots enable point-in-time volume backups via VolumeSnapshotClass, VolumeSnapshot, and VolumeSnapshotContent resources, restorable into new PVCs via spec.dataSource.
Last updated: August 2026
5.5 Container Storage Interface (CSI) Architecture & Drivers
In early Kubernetes releases, all storage volume plugins (including AWS EBS, GCE Persistent Disk, Azure Disk, Cinder, Ceph, and GlusterFS) were in-tree . This meant that storage vendor driver code was compiled directly into the core Kubernetes binaries— kube-apiserver , kube-controller-manager , and kubelet . This monolithic architecture introduced severe operational liabilities:
Release Coupling: A bug fix or feature enhancement in a third-party storage driver required upgrading the entire Kubernetes cluster.
Security & Stability Risks: Vendor code executed with full cluster-level and host root privileges inside kubelet and kube-controller-manager .
Code Bloat: Core Kubernetes maintenance was weighed down by dozens of proprietary storage SDKs.
To solve these challenges, the Kubernetes community co-developed the Container Storage Interface (CSI) —an industry-standard specification that establishes an out-of-tree, modular storage interface. Under CSI, storage plugins run as standard containerized workloads communicating with Kubernetes via gRPC over UNIX domain sockets .
1. The CSI Architectural Split: Controller vs. Node Plugin
A production CSI driver deployment is decoupled into two distinct operational planes: +-----------------------------------------------------------------------------------------+
- | CSI CONTROLLER PLUGIN (CLUSTER SCOPE) |
- | Deployed as a Deployment / StatefulSet in kube-system with leader election |
- | |
- | +--------------------+ +--------------------+ +------------------+ +-------------+ |
- | | csi-provisioner | | csi-attacher | | csi-resizer | |csi-snapshot | |
- | | Watches PVCs -> | | Watches | | Watches PVC | |Watches Snap | |
- | | CreateVolume / | | VolumeAttachment | | Expansion -> | |CreateSnap / | |
- | | DeleteVolume | | -> Attach/Detach | | ExpandVolume | |DeleteSnap | |
- | +---------+----------+ +---------+----------+ +--------+---------+ +------+------+ |
- | | | | | |
- | +-----------------------+----------------------+-------------------+ |
- | | gRPC over UNIX domain socket |
- | v |
- | +--------------------------+ |
- | | Vendor CSI Controller | |
- | +-------------+------------+ |
- +-------------------------------------|---------------------------------------------------+
- | Cloud Storage API (AWS / GCP / Ceph)
- +-------------------------------------|---------------------------------------------------+
- | v Attaches physical disk to node VM |
- | CSI NODE PLUGIN (NODE SCOPE) |
- | Deployed as a DaemonSet on every worker node (Privileged SecurityContext) |
- | |
- | +--------------------+ gRPC +--------------------------+ |
- | | kubelet | <--------> | Vendor CSI Node Plugin | |
- | | Directs Volume | | - NodeStageVolume | |
- | | Mount Operations | | - NodePublishVolume | |
- | +--------------------+ +------------+-------------+ |
- | | Formats & Bind-Mounts |
- | v |
- | +--------------------------+ |
- | | Host Filesystem & PodDir | |
- | +--------------------------+ |
- +-----------------------------------------------------------------------------------------+
- 1. Control Plane Controller Sidecars
Maintained by the CNCF Kubernetes Storage SIG, these helper sidecars run alongside the vendor driver container:
csi-provisioner : Watches PersistentVolumeClaim objects. Calls CreateVolume and DeleteVolume on the storage provider.
csi-attacher : Watches VolumeAttachment API objects created by Kubernetes. Calls ControllerPublishVolume and ControllerUnpublishVolume to physically attach/detach cloud disks to/from worker node virtual machines.
csi-resizer : Watches PVC storage request increases. Calls ControllerExpandVolume to resize underlying cloud block storage.
csi-snapshotter : Watches VolumeSnapshot CRDs. Calls CreateSnapshot and DeleteSnapshot .
livenessprobe : Monitors the health of the CSI plugin and exposes standard /healthz endpoints for Kubernetes probes.
2. CSI Node Plugin (DaemonSet)
Runs directly on each worker node with privileged: true and bidirectional mount propagation. The node's kubelet directly invokes the local node plugin over a UNIX domain socket (e.g., /var/lib/kubelet/plugins/ebs.csi.aws.com/csi.sock ).
2. Two-Phase Node Mounting: NodeStageVolume vs. NodePublishVolume
When a scheduled Pod requires a persistent volume, the local kubelet orchestrates a two-phase mounting protocol via the CSI Node Plugin: [ Attached Block Device on Node: /dev/xvdf ]
- |
- v
- +-------------------------------------------------------------+
- | STEP 1: NodeStageVolume |
- | - Formats raw block device with ext4/xfs (if unformatted) |
- | - Mounts device to global node staging directory: |
- | /var/lib/kubelet/plugins/kubernetes.io/csi/pv-name/globalmount
- +-------------------------------------------------------------+
- |
- v
- +-------------------------------------------------------------+
- | STEP 2: NodePublishVolume |
- | - Executes a Linux bind-mount from global staging directory |
- | into the target container's volume directory: |
- | /var/lib/kubelet/pods/<pod-uid>/volumes/kubernetes.io~csi/|
- +-------------------------------------------------------------+
Mounting and Teardown Sequences Compared:
Operational Phase gRPC Method Technical Action
Phase 1: Stage NodeStageVolume Formats raw block device with specified filesystem ( ext4 , xfs ) and mounts it to a global staging path on the node. Executed once per node for a given volume.
Phase 2: Publish NodePublishVolume Bind-mounts the staged filesystem into the specific Pod's volume directory. Executed for every Pod referencing the volume.
Phase 3: Unpublish NodeUnpublishVolume Unmounts the bind-mount from the Pod directory when the Pod terminates.
Phase 4: Unstage NodeUnstageVolume Unmounts the global node staging mount when no more pods on that node consume the volume.
3. Kubernetes CSI API Objects: CSIDriver , CSINode & VolumeAttachment
Kubernetes introduces dedicated API resources to register drivers and monitor attachment state:
1. CSIDriver (Driver Capabilities)
A cluster-scoped object that informs Kubernetes how to interact with the CSI plugin: apiVersion: storage.k8s.io/v1
kind: CSIDriver
metadata:
name: ebs.csi.aws.com
spec:
- attachRequired: true
- podInfoOnMount: false
volumeLifecycleModes:
- Persistent
- fsGroupPolicy: File
- 2. CSINode (Node-Specific Driver Registration)
Created automatically for every worker node to record the node's storage identity and volume topology: apiVersion: storage.k8s.io/v1
kind: CSINode
metadata:
name: worker-node-01
spec:
drivers:
- name: ebs.csi.aws.com
- nodeID: i-0a1b2c3d4e5f6g7h8
topologyKeys:
- topology.ebs.csi.aws.com/zone
allocatable:
- count: 28
- 3. VolumeAttachment (Attachment Lifecycle Debugging)
Represents the intent to attach a PV to a specific node. When a Pod is scheduled, the attachdetach-controller creates a VolumeAttachment object, which csi-attacher processes: # Inspect active volume attachments across the cluster
kubectl get volumeattachments
- # Describe attachment to diagnose why a volume is failing to attach to a node
- kubectl describe volumeattachment csi-9a8b7c6d5e4f3a2b1
- 4. VolumeSnapshot Architecture & Restoration Workflows
Kubernetes provides a standardized Custom Resource Definition (CRD) framework ( snapshot.storage.k8s.io/v1 ) to capture point-in-time copies of storage volumes. +-----------------------------------------------------------------------------------------+
- | VOLUMESNAPSHOT ARCHITECTURE |
- | |
- | [CLUSTER SCOPE] |
- | +-------------------------------------+ +-----------------------------------------+ |
- | | VolumeSnapshotClass | | VolumeSnapshotContent | |
- | | - driver: ebs.csi.aws.com | | - snapshotHandle: snap-0123456789abcdef| |
- | | - deletionPolicy: Delete / Retain | | - volumeSnapshotRef: prod/db-snap | |
- | +------------------+------------------+ +--------------------+--------------------+ |
- | | | (Bound 1-to-1) |
- |=====================|===========================================|=======================|
- | [NAMESPACE SCOPE] v v |
- | +--------------------------------------------------------------+ |
- | | VolumeSnapshot (e.g., db-snapshot) |
- | | - spec.source.persistentVolumeClaimName: production-db-pvc |
- | | - status.readyToUse: true |
- | +--------------------------------------------------------------+ |
- +-----------------------------------------------------------------------------------------+
- Declarative Snapshot Manifests
- 1. Define VolumeSnapshotClass apiVersion: snapshot.storage.k8s.io/v1
- kind: VolumeSnapshotClass
metadata:
- name: ebs-snapshot-class
- driver: ebs.csi.aws.com
- deletionPolicy: Delete
- 2. Create VolumeSnapshot from Existing PVC apiVersion: snapshot.storage.k8s.io/v1
- kind: VolumeSnapshot
metadata:
- name: postgres-backup-snapshot
- namespace: production
spec:
volumeSnapshotClassName: ebs-snapshot-class
source:
- persistentVolumeClaimName: postgres-data-pvc
- 3. Restore Snapshot into a New PVC via spec.dataSource apiVersion: v1
- kind: PersistentVolumeClaim
metadata:
- name: postgres-restored-pvc
- namespace: production
spec:
accessModes:
- ReadWriteOnce
- storageClassName: high-performance-ebs
resources:
requests:
storage: 50Gi
dataSource:
- name: postgres-backup-snapshot
- kind: VolumeSnapshot
- apiGroup: snapshot.storage.k8s.io
- 5. CSI Troubleshooting & Diagnostic Playbook # 1. Check health of CSI driver pods in kube-system
- kubectl get pods -n kube-system -l app.kubernetes.io/name=aws-ebs-csi-driver
- # 2. Inspect logs of csi-attacher sidecar when pods hang in ContainerCreating
- kubectl logs -n kube-system deployment/ebs-csi-controller -c csi-attacher
- # 3. Inspect logs of csi-provisioner sidecar when PVC stays Pending
- kubectl logs -n kube-system deployment/ebs-csi-controller -c csi-provisioner
- # 4. Check CSINode registration on worker nodes
- kubectl get csinodes -o wide
- # 5. Verify snapshot creation status
- kubectl get volumesnapshot -n production