
The demand is real. CNCF's 2025 cloud native survey found 66% of organizations that host AI workloads use Kubernetes for generative AI (n=213, AI-hosting respondents only). Those workloads need storage that provisions itself and behaves predictably.
When a pod sits in Pending, teams often can't say how a PVC becomes an Azure Disk, how that disk reaches a node, or where to look first. This guide walks the full path on AKS, from claim to mounted filesystem.
Key Takeaways
- A CSI driver lets Kubernetes use external storage without provider-specific code in its core.
- On AKS, the Azure Disk CSI driver handles provisioning, attachment, formatting, and mounting.
- Provision, attach, stage, and publish are four separate operations.
- StorageClass settings, access modes, reclaim policy, and zones shape volume behavior.
What Is a Kubernetes CSI Driver?
The Container Storage Interface (CSI) is a gRPC-based specification between a container orchestrator and a storage plugin. It defines Identity, Controller, and Node services. A CSI driver is a concrete implementation for one backend. On AKS, the Azure Disk driver is disk.csi.azure.com.
Why CSI exists
Older in-tree plugins lived inside Kubernetes itself. Moving storage out-of-tree gives drivers independent release cycles, lowers core maintenance, and reduces vulnerability exposure.
Microsoft marks the in-tree Azure Disk and File plugins unsupported on AKS from Kubernetes 1.26, and CSI has been the AKS default since 1.21.
The terms you'll meet
- PersistentVolumeClaim (PVC): an application's request for storage.
- PersistentVolume (PV): the provisioned storage as Kubernetes sees it.
- StorageClass: the policy for how storage is created and which provisioner handles it.
- Azure managed disk: the actual cloud resource.
The driver is the integration layer that maps Kubernetes requests onto Azure operations. It is not the disk, not a filesystem, not a replacement for the kubelet, and not a StorageClass or PVC.
Controller and node components
The controller plugin handles cluster-wide operations: creating, deleting, attaching, and detaching volumes. The node plugin runs on each node and handles staging, formatting, mounting, and unmounting. Sidecars translate Kubernetes object changes into driver calls:
external-provisionerwatches PVCs and callsCreateVolumeexternal-attacherwatchesVolumeAttachmentand callsControllerPublishVolumeexternal-resizerhandles expansionexternal-snapshotterhandles snapshotsnode-driver-registrarregisters the driver with the kubeletlivenessprobereports driver health
Capabilities vary by driver and version, so don't generalize from another CSI driver. Azure Disk supports snapshots, cloning, expansion, raw block volumes, and both Linux and Windows. Check current AKS documentation for your version.
How Does a Kubernetes CSI Driver Work on AKS?
The flow starts with a storage request and ends with a filesystem inside a pod. The controller side and node side use different CSI services and different Kubernetes integration points.
Initiation: StorageClass, PVC, and pod
An application creates a PVC that names a StorageClass. AKS ships built-in classes, all using the disk.csi.azure.com provisioner:
| Class | Backing SKU | Reclaim | Binding mode |
|---|---|---|---|
managed-csi (also default) |
Standard SSD | Delete | WaitForFirstConsumer |
managed-csi-premium |
Premium SSD | Delete | WaitForFirstConsumer |
managed-csi-premium-v2 |
Premium SSD v2 (Kubernetes 1.35+) | Delete | WaitForFirstConsumer |
Here is a compact example modeled on Microsoft's samples:
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: azure-managed-disk
spec:
accessModes:
- ReadWriteOnce
storageClassName: managed-csi
resources:
requests:
storage: 5Gi
---
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
containers:
- name: app
image: mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
volumeMounts:
- mountPath: /mnt/azure
name: volume
volumes:
- name: volume
persistentVolumeClaim:
claimName: azure-managed-disk
Verify the manifests against Microsoft's current AKS pages before use.
A custom StorageClass controls the behavior that matters:
skuName(defaultStandardSSD_LRS)fsType(ext4on Linux,ntfson Windows)cachingMode(Premium SSD v2 and Ultra requireNone)reclaimPolicyandallowVolumeExpansionvolumeBindingMode
WaitForFirstConsumer delays provisioning until a pod is scheduled. The disk then lands in a zone compatible with the chosen node. Don't set nodeName on the pod in this mode. It bypasses the scheduler and can leave the PVC pending.
On zone-aware clusters, Microsoft states that from Kubernetes 1.29 the built-in classes use ZRS (except managed-csi-premium-v2, which stays LRS). Don't assume managed-csi means LRS.
Core operation: from claim to attached disk
Dynamic provisioning runs in four steps:
- Provision.
external-provisionersees the PVC and callsCreateVolume. The Azure Disk driver calls the Azure Compute API, creates the managed disk, and a PV binds to the claim. - Attach. After scheduling, a
VolumeAttachmentrecords the intent.external-attachercallsControllerPublishVolume, and the controller attaches the disk to the node. - Stage. The kubelet calls
NodeStageVolume. - Publish. The kubelet calls
NodePublishVolume.

Attachment makes the disk available to the VM. Staging and publishing expose a filesystem to the pod. Don't confuse attachment with mounting.
When debugging, inspect these in order:
- the PVC and its events
- the PV
VolumeAttachmentobjects- pod scheduling events
- logs from the
azurediskcontainer in the leadercsi-azuredisk-controllerpod
Registration: node plugin, kubelet, and retries
The node-driver-registrar registers the driver with the kubelet. The kubelet then issues CSI calls over a local Unix socket. The registration socket and the driver's own CSI socket are different files, and --kubelet-registration-path points to the CSI socket.
During staging, the driver finds the device by its LUN, formats it only if needed, and mounts it at a staging path. During publishing, it bind-mounts that path into the pod's target path. CSI requires staging to succeed before publishing.
Retries are safe by design. Repeated CreateVolume calls with the same name must not create duplicate storage, and a retry can fetch the existing volume ID after an uncertain result.
Use this troubleshooting path:
| Symptom | Where to look |
|---|---|
PVC Pending |
Delayed binding may be waiting for a pod; check for nodeName |
| Create, attach, or delete failure | Controller pod azuredisk logs |
| Zone mismatch | Align disk and node zones, or use ZRS |
AuthorizationFailed |
AKS control plane identity permissions on the disk resource group |
| Multi-attach or capacity error | Existing attachment and the VM's data disk limit |
| Slow mount or permissions | csi-azuredisk-node logs; try fsGroupChangePolicy: OnRootMismatch |
| Leftover disk in Azure | Review ownership, then use Microsoft's unattached-disk script |
One real-world example: a user report in driver issue #1815 described disks stuck unattached on AKS 1.24 and 1.25. A maintainer suspected a race tied to enableAsyncAttach=true. Treat that report as historical context rather than evidence of a current defect. It still shows why attachment state deserves inspection.
Output: the result and the reverse lifecycle
The pod reads and writes a persistent filesystem at its mount path. The data lives on the managed disk and outlasts any single container.
Teardown runs in reverse: unmount and unpublish on the node, detach from the VM, then delete or retain the disk. Delete removes the backend disk with the PVC. Retain leaves a released PV and its data for manual cleanup.

Optional operations depend on driver version and prerequisites:
- Expansion: raise the PVC request on an expandable class. AKS resizes the existing volume without downtime. Shrinking isn't supported.
- Snapshots: need snapshot CRDs, the snapshot controller, and a
VolumeSnapshotClass. Stop writes first. - Cloning: supported, with the source idle during the clone.
- Raw block: use
volumeMode: BlockwithvolumeDevicesanddevicePath.
Where Kubernetes CSI Drivers Are Used on AKS
Azure Disk CSI volumes suit workloads that need block storage rather than ephemeral pod storage:
- databases and StatefulSets
- message queues
- persistent application data
- analytics and AI or machine-learning workloads
Design conditions that matter
Microsoft recommends Azure Disk CSI for block storage when databases run inside the cluster. Several conditions shape the design:
- Access mode: ordinary Azure Disk is
ReadWriteOnce, which means one node, not necessarily one pod. Multiple pods on the same node can use it. - Node disk limits: a
Standard_D4s_v5node supports 8 remote data disks, and aStandard_D16s_v5supports 32. Plan with your actual node SKU. - Performance ceilings: per-disk caps run from 6,000 IOPS (Standard SSD) to 20,000 (Premium SSD) and 80,000 (Premium SSD v2), per Microsoft's disk type docs. These are limits, not benchmarks.
- Zones: zonal disks must match the node's zone.
- Replication: application replication and storage replication are different protections.
- Backup: snapshots help, but plan backup deliberately.

Multi-node shared disks are a separate case. They use maxShares and need cluster-aware coordination such as WSFC or Pacemaker. They aren't a shared filesystem, so don't assume maxShares > 1 gives you multi-node ext4.
Azure Disk, Azure Files, and other clouds
Azure Files CSI provides a shared filesystem over SMB or NFS for data many pods read together. Azure Disk provides block volumes.
The AWS EBS CSI driver follows the same CSI model but manages Amazon EBS volumes, whose Multi-Attach is limited to io1 and io2 in a single zone. CSI standardizes the interface, not backend capabilities.
Managing block storage at scale
For enterprises running Azure block storage across many clusters or clouds, Lucidity can complement the CSI layer. Its AutoScaler expands and shrinks disks with zero downtime, and its monitoring gives real-time visibility into volumes across AWS, Azure, and Google Cloud. It doesn't replace the AKS CSI driver or the Azure Disk lifecycle.
Conclusion
Kubernetes expresses storage intent through a PVC and StorageClass. The CSI driver's controller side provisions and attaches the Azure Disk, while the node side formats and mounts it for the pod.
Before deploying stateful workloads on AKS, validate:
- zone topology and binding mode
- access modes
- driver capabilities for your version
- reclaim behavior
- expansion support
- observability and scale limits
Frequently Asked Questions
What is a Kubernetes CSI driver?
CSI is the standard interface between Kubernetes and storage systems. A CSI driver implements it for a particular backend, such as Azure Disk.
What is an AWS CSI driver?
It is a driver such as the EBS CSI driver, which connects Kubernetes to Amazon EBS through the same CSI model. It is separate from the Azure Disk driver used on AKS.
Does AKS use a CSI driver for Azure Disk?
Yes. AKS uses CSI drivers by default from Kubernetes 1.21, and the Azure Disk driver is disk.csi.azure.com. Verify installation and defaults for your AKS version.
How does a CSI driver mount a volume to a Kubernetes pod?
The disk is attached to the node, then staged (formatted if needed and mounted at a staging path). Finally, it is published to the pod's target path with a bind mount.
What is the difference between a CSI driver and a StorageClass?
The driver performs storage operations. The StorageClass sets provisioning policy and names which driver handles a PVC.
Can Azure Disk CSI volumes be shared across multiple pods?
Standard ReadWriteOnce disks can serve multiple pods on the same node. Multi-node sharing depends on disk type, driver version, and configuration, and requires coordination. Check current AKS and Azure documentation rather than assuming multi-writer support.