Azure Files CSI driver errors prevent mounting file shares in AKS clusters. Common causes include driver registration failures, storage account access issues, FIPS node pool incompatibilities, and network connectivity problems. Fixes range from checking driver installation to configuring proper network access and role-based access control.
The Azure Files Container Storage Interface (CSI) driver is a storage provisioning mechanism in AKS that manages the lifecycle of Azure file shares. CSI driver errors occur when the driver fails to initialize, register with kubelet, or mount SMB file shares to pods. These errors typically manifest as "MountVolume.SetUp failed" or "driver not found" messages during pod scheduling. The driver is critical for applications that need shared persistent storage across multiple pods in your AKS cluster.
Check if the driver is running on your nodes. Connect to your AKS cluster and list the CSI driver pods:
kubectl get pods -n kube-system | grep azure-file-csiYou should see pods like azure-file-csi-driver-xxxxx running. If none appear, the driver is not installed. Install it using:
az aks update --resource-group YOUR_RESOURCE_GROUP --name YOUR_CLUSTER --enable-file-csi-driverWait for the deployment to complete (usually 5-10 minutes).
Examine driver logs to identify specific failure reasons:
kubectl logs -n kube-system -l app=azure-file-csi-driver --tail=50Look for errors related to driver registration, kubelet communication, or initialization. Common error patterns include socket connection failures or resource conflicts. If logs show persistent errors, restart the driver pods:
kubectl rollout restart daemonset azure-file-csi-driver -n kube-systemRetrieve the secret containing your storage account credentials and verify it matches the current storage account:
kubectl get secret azure-storage-secret -n YOUR_NAMESPACE -o jsonpath='{.data.azurestorageaccountname}' | base64 --decode
kubectl get secret azure-storage-secret -n YOUR_NAMESPACE -o jsonpath='{.data.azurestorageaccountkey}' | base64 --decodeCompare these values with your actual Azure storage account name and access key. If they do not match, update the secret:
kubectl create secret generic azure-storage-secret --from-literal=azurestorageaccountname=YOUR_ACCOUNT --from-literal=azurestorageaccountkey=YOUR_KEY --dry-run=client -o yaml | kubectl apply -f -Then delete the pod using the secret to trigger a remount with updated credentials.
Azure Files uses SMB protocol on port 445. Verify your NSG rules allow this traffic:
az network nsg rule list --resource-group YOUR_RESOURCE_GROUP --nsg-name YOUR_NSG --query "[?destinationPortRange=='445'].{Direction:direction,Access:access,Priority:priority}"If no rule allows inbound on port 445, add one:
az network nsg rule create --resource-group YOUR_RESOURCE_GROUP --nsg-name YOUR_NSG --name AllowSMB --priority 100 --source-address-prefixes VirtualNetwork --destination-address-prefixes StorageAccount --destination-port-ranges 445 --protocol Tcp --access Allow --direction InboundAlternatively, in the Azure portal, navigate to NSG rules and add an inbound rule for port 445 from your AKS subnet.
For managed identity support, ensure the Kubelet identity has the necessary storage role. First, identify your cluster's kubelet identity:
az aks show --resource-group YOUR_RESOURCE_GROUP --name YOUR_CLUSTER --query identity.userAssignedIdentitiesThen assign the "Storage File Data SMB Share Contributor" role:
az role assignment create --role "Storage File Data SMB Share Contributor" --assignee-object-id KUBELET_IDENTITY_PRINCIPAL_ID --scope /subscriptions/SUBSCRIPTION_ID/resourceGroups/STORAGE_RESOURCE_GROUP/providers/Microsoft.Storage/storageAccounts/YOUR_STORAGE_ACCOUNTWait 5-10 minutes for role assignment propagation before attempting to mount again.
FIPS-enabled node pools disable certain authentication modules that SMB requires. If you are using FIPS nodes, create a custom StorageClass that uses NFS instead:
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: azure-file-nfs
provisioner: file.csi.azure.com
parameters:
protocol: nfs
allowVolumeExpansion: trueApply this StorageClass and use it in your PersistentVolumeClaim:
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-file-claim
spec:
accessModes:
- ReadWriteMany
storageClassName: azure-file-nfs
resources:
requests:
storage: 100GiNFS provides better compatibility with FIPS while maintaining file-level sharing.
Deploy a test pod to verify the mount works end-to-end:
apiVersion: v1
kind: Pod
metadata:
name: debug-mount
spec:
containers:
- name: debug
image: busybox:latest
command:
- sleep
- "3600"
volumeMounts:
- name: azure-file
mountPath: /mnt/test
volumes:
- name: azure-file
persistentVolumeClaim:
claimName: my-file-claimApply and check:
kubectl apply -f debug-mount.yaml
kubectl wait --for=condition=Ready pod/debug-mount --timeout=300s
kubectl exec -it debug-mount -- ls -la /mnt/testIf the pod enters Running state and you can list files, the mount is working. If still pending, describe the pod to see mount errors:
kubectl describe pod debug-mountFor private endpoint configurations: The Azure File CSI driver cannot dynamically allocate volumes in storage accounts that only support private endpoint access. Use a separate public-accessible storage account or manually create the file share and reference it via a static PV. For CI/CD pipelines, store storage account credentials in Azure Key Vault and use Workload Identity for automatic credential injection instead of static Kubernetes secrets. On Linux nodes, verify SMB client packages are installed (cifs-utils); on Windows nodes, ensure WinRM is properly configured. For troubleshooting timeouts, run nslookup storage-account.file.core.windows.net and nc -zv storage-account.file.core.windows.net 445 from a node pod to verify DNS resolution and network connectivity before investigating driver-level issues.
Failed to connect to server: connection refused (HTTP/2)
How to fix "HTTP/2 connection refused" error in Kubernetes
missing request for cpu in container
How to fix "missing request for cpu in container" in Kubernetes HPA
error: invalid configuration
How to fix "error: invalid configuration" in Kubernetes
etcdserver: cluster ID mismatch
How to fix "etcdserver: cluster ID mismatch" in Kubernetes
running with swap on is not supported
How to fix "running with swap on is not supported" in kubeadm