How to fix Azure File CSI driver error in Kubernetes

KubernetesINTERMEDIATEHIGH

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.

What this error means

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.

How to fix "Azure File CSI driver error"

1Verify the Azure Files CSI driver is installed

Check if the driver is running on your nodes. Connect to your AKS cluster and list the CSI driver pods:

bash

kubectl get pods -n kube-system | grep azure-file-csi

You should see pods like azure-file-csi-driver-xxxxx running. If none appear, the driver is not installed. Install it using:

bash

az aks update --resource-group YOUR_RESOURCE_GROUP --name YOUR_CLUSTER --enable-file-csi-driver

Wait for the deployment to complete (usually 5-10 minutes).

2Check CSI driver logs for registration errors

Examine driver logs to identify specific failure reasons:

bash

kubectl logs -n kube-system -l app=azure-file-csi-driver --tail=50

Look 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:

bash

kubectl rollout restart daemonset azure-file-csi-driver -n kube-system

3Validate storage account credentials in the secret

Retrieve the secret containing your storage account credentials and verify it matches the current storage account:

bash

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 --decode

Compare these values with your actual Azure storage account name and access key. If they do not match, update the secret:

bash

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.

4Ensure Network Security Group allows SMB traffic

Azure Files uses SMB protocol on port 445. Verify your NSG rules allow this traffic:

bash

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:

bash

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 Inbound

Alternatively, in the Azure portal, navigate to NSG rules and add an inbound rule for port 445 from your AKS subnet.

5Assign proper role-based access control (RBAC)

For managed identity support, ensure the Kubelet identity has the necessary storage role. First, identify your cluster's kubelet identity:

bash

az aks show --resource-group YOUR_RESOURCE_GROUP --name YOUR_CLUSTER --query identity.userAssignedIdentities

Then assign the "Storage File Data SMB Share Contributor" role:

bash

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_ACCOUNT

Wait 5-10 minutes for role assignment propagation before attempting to mount again.

6For FIPS-enabled nodes, use NFS instead of SMB

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:

yaml

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: azure-file-nfs
provisioner: file.csi.azure.com
parameters:
  protocol: nfs
allowVolumeExpansion: true

Apply this StorageClass and use it in your PersistentVolumeClaim:

yaml

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-file-claim
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: azure-file-nfs
  resources:
    requests:
      storage: 100Gi

NFS provides better compatibility with FIPS while maintaining file-level sharing.

7Test the mount with a debug pod

Deploy a test pod to verify the mount works end-to-end:

yaml

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-claim

Apply and check:

bash

kubectl apply -f debug-mount.yaml
kubectl wait --for=condition=Ready pod/debug-mount --timeout=300s
kubectl exec -it debug-mount -- ls -la /mnt/test

If the pod enters Running state and you can list files, the mount is working. If still pending, describe the pod to see mount errors:

bash

kubectl describe pod debug-mount

How to fix Azure File CSI driver error in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "Azure File CSI driver error"

Advanced notes

Related errors

Official resources & further reading