Create and use a volume with Azure Files in Azure Kubernetes Service (AKS)

A persistent volume represents a piece of storage that has been provisioned for use with Kubernetes pods. You can use a persistent volume with one or many pods, and it can be dynamically or statically provisioned. If multiple pods need concurrent access to the same storage volume, you can use Azure Files to connect using the Server Message Block (SMB) protocol. This article shows you how to dynamically create an Azure file share for use by multiple pods in an Azure Kubernetes Service (AKS) cluster.

This article shows you how to:

• Work with a dynamic persistent volume (PV) by installing the Container Storage Interface (CSI) driver and dynamically creating one or more Azure file shares to attach to a pod.
• Work with a static PV by creating one or more Azure file shares, or use an existing one and attach it to a pod.

For more information on Kubernetes volumes, see Storage options for applications in AKS.

Before you begin

• You need an Azure storage account.
• Make sure you have Azure CLI version 2.0.59 or later installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.
• When choosing between standard and premium file shares, it's important you understand the provisioning model and requirements of the expected usage pattern you plan to run on Azure Files. For more information, see Choosing an Azure Files performance tier based on usage patterns.

Dynamically provision a volume

This section provides guidance for cluster administrators who want to provision one or more persistent volumes that include details of one or more shares on Azure Files. A persistent volume claim (PVC) uses the storage class object to dynamically provision an Azure Files file share.

Storage class parameters for dynamic PersistentVolumes

The following table includes parameters you can use to define a custom storage class for your PersistentVolumeClaim.

Create a storage class

Storage classes define how to create an Azure file share. A storage account is automatically created in the node resource group for use with the storage class to hold the Azure Files file share. Choose of the following Azure storage redundancy SKUs for skuName:

• Standard_LRS: Standard locally redundant storage (LRS)
• Standard_GRS: Standard geo-redundant storage (GRS)
• Standard_ZRS: Standard zone redundant storage (ZRS)
• Standard_RAGRS: Standard read-access geo-redundant storage (RA-GRS)
• Premium_LRS: Premium locally redundant storage (LRS)
• Premium_ZRS: Premium zone redundant storage (ZRS)

For more information on Kubernetes storage classes for Azure Files, see Kubernetes Storage Classes.

1. Create a file named azure-file-sc.yaml and copy in the following example manifest. For more information on mountOptions, see the Mount options section.

   kind: StorageClass
   apiVersion: storage.k8s.io/v1
   metadata:
     name: my-azurefile
   provisioner: file.csi.azure.com # replace with "kubernetes.io/azure-file" if aks version is less than 1.21
   allowVolumeExpansion: true
   mountOptions:
    - dir_mode=0777
    - file_mode=0777
    - uid=0
    - gid=0
    - mfsymlinks
    - cache=strict
    - actimeo=30
    - nobrl  # disable sending byte range lock requests to the server and for applications which have challenges with posix locks
   parameters:
     skuName: Premium_LRS
   

2. Create the storage class using the kubectl apply command.

   kubectl apply -f azure-file-sc.yaml
   

Create a persistent volume claim

A persistent volume claim (PVC) uses the storage class object to dynamically provision an Azure file share. You can use the following YAML to create a persistent volume claim 100 GB in size with ReadWriteMany access. For more information on access modes, see Kubernetes persistent volume.

1. Create a file named azure-file-pvc.yaml and copy in the following YAML. Make sure the storageClassName matches the storage class you created in the previous step.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: my-azurefile
   spec:
     accessModes:
       - ReadWriteMany
     storageClassName: my-azurefile
     resources:
       requests:
         storage: 100Gi
   

   Note

   If using the Premium_LRS SKU for your storage class, the minimum value for storage must be 100Gi.

2. Create the persistent volume claim using the kubectl apply command.

   kubectl apply -f azure-file-pvc.yaml
   

   Once completed, the file share is created. A Kubernetes secret is also created that includes connection information and credentials. You can use the kubectl get command to view the status of the PVC:

   kubectl get pvc my-azurefile
   

   The output of the command resembles the following example:

   NAME           STATUS    VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS      AGE
   my-azurefile   Bound     pvc-8436e62e-a0d9-11e5-8521-5a8664dc0477   100Gi       RWX            my-azurefile      5m
   

Use the persistent volume

The following YAML creates a pod that uses the persistent volume claim my-azurefile to mount the Azure Files file share at the /mnt/azure path. For Windows Server containers, specify a mountPath using the Windows path convention, such as 'D:'.

1. Create a file named azure-pvc-files.yaml, and copy in the following YAML. Make sure the claimName matches the PVC you created in the previous step.

   kind: Pod
   apiVersion: v1
   metadata:
     name: mypod
   spec:
     containers:
       - name: mypod
         image: mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
         resources:
           requests:
             cpu: 100m
             memory: 128Mi
           limits:
             cpu: 250m
             memory: 256Mi
         volumeMounts:
           - mountPath: /mnt/azure
             name: volume
             readOnly: false
     volumes:
      - name: volume
        persistentVolumeClaim:
          claimName: my-azurefile
   

2. Create the pod using the kubectl apply command.

   kubectl apply -f azure-pvc-files.yaml
   

   You now have a running pod with your Azure Files file share mounted in the /mnt/azure directory. This configuration can be seen when inspecting your pod using the kubectl describe command. The following condensed example output shows the volume mounted in the container.

   Containers:
     mypod:
       Container ID:   docker://053bc9c0df72232d755aa040bfba8b533fa696b123876108dec400e364d2523e
       Image:          mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
       Image ID:       docker-pullable://nginx@sha256:d85914d547a6c92faa39ce7058bd7529baacab7e0cd4255442b04577c4d1f424
       State:          Running
         Started:      Fri, 01 Mar 2019 23:56:16 +0000
       Ready:          True
       Mounts:
         /mnt/azure from volume (rw)
         /var/run/secrets/kubernetes.io/serviceaccount from default-token-8rv4z (ro)
   [...]
   Volumes:
     volume:
       Type:       PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
       ClaimName:  my-azurefile
       ReadOnly:   false
   [...]
   

Mount options

The default value for fileMode and dirMode is 0777 for Kubernetes versions 1.13.0 and above. If you're dynamically creating the persistent volume with a storage class, you can specify mount options on the storage class object. For more information, see Mount options. The following example sets 0777:

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: my-azurefile
provisioner: file.csi.azure.com # replace with "kubernetes.io/azure-file" if aks version is less than 1.21
allowVolumeExpansion: true
mountOptions:
  - dir_mode=0777
  - file_mode=0777
  - uid=0
  - gid=0
  - mfsymlinks
  - cache=strict
  - actimeo=30
  - nobrl  # disable sending byte range lock requests to the server and for applications which have challenges with posix locks
parameters:
  skuName: Premium_LRS

Using Azure tags

For more information on using Azure tags, see Use Azure tags in Azure Kubernetes Service (AKS).

Statically provision a volume

This section provides guidance for cluster administrators who want to create one or more persistent volumes that include details of an existing Azure Files share to use with a workload.

Static provisioning parameters for PersistentVolume

The following table includes parameters you can use to define a PersistentVolume.

Create an Azure file share

Before you can use an Azure Files file share as a Kubernetes volume, you must create an Azure Storage account and the file share.

1. Get the resource group name using the az aks show command with the --query nodeResourceGroup parameter.

   az aks show --resource-group myResourceGroup --name myAKSCluster --query nodeResourceGroup -o tsv
   

   The output of the command resembles the following example:

   MC_myResourceGroup_myAKSCluster_eastus
   

2. Create a storage account using the az storage account create command with the --sku parameter. The following command creates a storage account using the Standard_LRS SKU. Make sure to replace the following placeholders:

   • myAKSStorageAccount with the name of the storage account
   • nodeResourceGroupName with the name of the resource group that the AKS cluster nodes are hosted in
   • location with the name of the region to create the resource in. It should be the same region as the AKS cluster nodes.

   az storage account create -n myAKSStorageAccount -g nodeResourceGroupName -l location --sku Standard_LRS
   

3. Export the connection string as an environment variable using the following command, which you use to create the file share.

   export AZURE_STORAGE_CONNECTION_STRING=$(az storage account show-connection-string -n storageAccountName -g resourceGroupName -o tsv)
   

4. Create the file share using the az storage share create command. Make sure to replace shareName with your share name.

   az storage share create -n shareName --connection-string $AZURE_STORAGE_CONNECTION_STRING
   

5. Export the storage account key as an environment variable using the following command.

   STORAGE_KEY=$(az storage account keys list --resource-group nodeResourceGroupName --account-name myAKSStorageAccount --query "[0].value" -o tsv)
   

6. Echo the storage account name and key using the following command. Copy this information, as you need these values when creating the Kubernetes volume.

   echo Storage account key: $STORAGE_KEY
   

Create a Kubernetes secret

Kubernetes needs credentials to access the file share created in the previous step. These credentials are stored in a Kubernetes secret, which is referenced when you create a Kubernetes pod.

1. Create the secret using the kubectl create secret command. The following example creates a secret named azure-secret and populates the azurestorageaccountname and azurestorageaccountkey from the previous step. To use an existing Azure storage account, provide the account name and key.

   kubectl create secret generic azure-secret --from-literal=azurestorageaccountname=myAKSStorageAccount --from-literal=azurestorageaccountkey=$STORAGE_KEY
   

Mount file share as a persistent volume

1. Create a new file named azurefiles-pv.yaml and copy in the following contents. Under csi, update resourceGroup, volumeHandle, and shareName. For mount options, the default value for fileMode and dirMode is 0777.

   apiVersion: v1
   kind: PersistentVolume
   metadata:
     annotations:
       pv.kubernetes.io/provisioned-by: file.csi.azure.com
     name: azurefile
   spec:
     capacity:
       storage: 5Gi
     accessModes:
       - ReadWriteMany
     persistentVolumeReclaimPolicy: Retain
     storageClassName: azurefile-csi
     csi:
       driver: file.csi.azure.com
       volumeHandle: "{resource-group-name}#{account-name}#{file-share-name}"  # make sure this volumeid is unique for every identical share in the cluster
       volumeAttributes:
         shareName: aksshare
       nodeStageSecretRef:
         name: azure-secret
         namespace: default
     mountOptions:
       - dir_mode=0777
       - file_mode=0777
       - uid=0
       - gid=0
       - mfsymlinks
       - cache=strict
       - nosharesock
       - nobrl  # disable sending byte range lock requests to the server and for applications which have challenges with posix locks
   

2. Create the persistent volume using the kubectl create command.

   kubectl create -f azurefiles-pv.yaml
   

3. Create a new file named azurefiles-mount-options-pvc.yaml and copy the following contents.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: azurefile
   spec:
     accessModes:
       - ReadWriteMany
     storageClassName: azurefile-csi
     volumeName: azurefile
     resources:
       requests:
         storage: 5Gi
   

4. Create the PersistentVolumeClaim using the kubectl apply command.

   kubectl apply -f azurefiles-mount-options-pvc.yaml
   

5. Verify your PersistentVolumeClaim is created and bound to the PersistentVolume using the kubectl get command.

   kubectl get pvc azurefile
   

   The output from the command resembles the following example:

   NAME        STATUS   VOLUME      CAPACITY   ACCESS MODES   STORAGECLASS   AGE
   azurefile   Bound    azurefile   5Gi        RWX            azurefile      5s
   

6. Update your container spec to reference your PersistentVolumeClaim and your pod in the YAML file. For example:

   ...
     volumes:
     - name: azure
       persistentVolumeClaim:
         claimName: azurefile
   

7. A pod spec can't be updated in place, so delete the pod using the kubectl delete command and recreate it using the kubectl apply command.

   kubectl delete pod mypod
   
   kubectl apply -f azure-files-pod.yaml
   

Mount file share as an inline volume

To mount the Azure Files file share into your pod, you configure the volume in the container spec.

1. Create a new file named azure-files-pod.yaml and copy in the following contents. If you changed the name of the file share or secret name, update the shareName and secretName. You can also update the mountPath, which is the path where the Files share is mounted in the pod. For Windows Server containers, specify a mountPath using the Windows path convention, such as 'D:'.

apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  nodeSelector:
    kubernetes.io/os: linux
  containers:
    - image: 'mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine'
      name: mypod
      resources:
        requests:
          cpu: 100m
          memory: 128Mi
        limits:
          cpu: 250m
          memory: 256Mi
      volumeMounts:
        - name: azure
          mountPath: /mnt/azure
          readOnly: false
  volumes:
    - name: azure
      csi:
        driver: file.csi.azure.com
        volumeAttributes:
          secretName: azure-secret  # required
          shareName: aksshare  # required
          mountOptions: 'dir_mode=0777,file_mode=0777,cache=strict,actimeo=30,nosharesock,nobrl'  # optional

2. Create the pod using the kubectl apply command.

   kubectl apply -f azure-files-pod.yaml
   

   You now have a running pod with an Azure Files file share mounted at /mnt/azure. You can verify the share is mounted successfully using the kubectl describe command.

   kubectl describe pod mypod
   

Next steps

For Azure Files CSI driver parameters, see CSI driver parameters.

For associated best practices, see Best practices for storage and backups in AKS.