Configure Azure file share as a volume

In this guide we would like to showcase the different ways one could mount Azure file shares as a volume into a pod.

• AzureFile
• PersistentVolumeClaim

Prerequisites

• Access to Azure Storage account with a file share
• Storage Account name and access key should be available in a key vault

Learn more about Azure Files

"What is Azure Files"

Create a secret

Create a Kubernetes secret which holds both the account name (azurestorageaccountname) and key (azurestorageaccountkey). Secrets from Key Vault can be mounted to a pod using Secrets Store CSI Driver.

Example:

my-sa-secretproviderclass.yaml

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  namespace: "<my-team-namespace>"
  name: "<my-sa-spc>"
  labels:
    app: "<my-sa>"
spec:
  provider: azure
  secretObjects:
    - secretName: "<my-sa-credentials>"
      type: Opaque
      data:
      - objectName: "<my-sa-name-kv-secret>"
        key: "azurestorageaccountname"
      - objectName: "<my-sa-access-key-kv-secret>"
        key: "azurestorageaccountkey"
  parameters:
    usePodIdentity: "true"
    keyvaultName: "<my-team-keyvault-name>"
    objects: |
      array:
        - |
          objectName: "<my-sa-name-kv-secret>"
          objectType: secret
        - |
          objectName: "<my-sa-access-key-kv-secret>"
          objectType: secret
    tenantId: "<azure-tenant-id>"

info

See Accessing Key Vault with Secrets Store CSI Driver for detailed instructions.

Simple mounting of Azure Files into a pod

This solution is preferred if you only want to read something off your file share.

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  ...
spec:
  ...
  template:
    ...
    spec:
      containers:
        ...
          volumeMounts:
            - name: "azure-files" # [1]
              mountPath: "/mnt/azurefiles" # [2]
      volumes:
        - name: "azure-files" # [1]
          azureFile:
            secretName: <my-sa-credentials> # [3]
            shareName: <myazurefileshare> # [4]

1. Give a name to volumeMounts and the same to volumes. Both names have to match.
2. Decide where in the container you want to mount your file share.
3. The name of the Kubernetes secret holding the credentials for your Azure file share (see Create a secret).
4. The file share name which you would like to mount. The file share has to be created beforehand in your Azure Storage account.

Advanced mounting of Azure Files into a pod

This solution is preferred if you need to do write changes. In Gjensidige we do not allow containers running as root for security reasons. Its recommended that a running container has an UID of 10001 or higher. When not running at UID 0(root), some applications may break when writing to Azure files if the directory permissions are not set correctly. With this solution we have the ability to change the directory permission to whatever we want.

Prerequisites

• ArgoCD must be allowed to create PersistentVolumes in your project. See example for details.

PersistentVolume (PV)

Define a PersistentVolume resource

azurefilevolume.yml

apiVersion: v1
kind: PersistentVolume
metadata:
  name: "team-a-app-1-azurefiles" # [1]
  labels:
    pv: "app-1-azurefiles" # [2]
    team: "team-a" # [2]
spec:
  capacity:
    storage: 100Gi
  accessModes:
    - ReadWriteMany
  azureFile:
    secretName: <my-sa-credentials> # [3]
    secretNamespace: <my-team-namespace> # [4]
    shareName: blob # [5]
    readOnly: false
  mountOptions:
    - dir_mode=0755 # [6]
    - file_mode=0755 # [7]
    - uid=10001 # [8]
    - gid=10001 # [9]
    - mfsymlinks
    - nobrl

1. Be aware that the resource persistentVolume (PV) is cluster wide, meaning the names have to be unique in the cluster
2. Labels are an important way of connecting resources in Kubernetes. Have at least 2 labels that when combined give a unique key. This key is needed for the PersistentVolumeClaim resource.
3. The name of the Kubernetes secret holding the credentials for your Azure file share (see Create a secret).
4. The namespace in which your above secret mentioned secret[3] is located
5. The file share name which you would like to mount. The file share has to be created beforehand in your Azure Storage account.
6. The default directory permissions to be set
7. The default file permissions to be set
8. The default UID to set on directories and files. Use your application UID
9. The default GID to set on directories and files. Use your application GID

PersistentVolumeClaim (PVC)

azurefilevolumeclaim.yml

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  namespace: "<my-team-namespace>" # [1]
  name: "team-a-app-1-azurefiles" # [2]
  labels:
    app: "your-app-name"
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: ""
  selector:
    matchLabels:
      pv: "app-1-azurefiles" # [3]
      team: "team-a" # [3]
  resources:
    requests:
      storage: 100Gi

1. The namespace where you will be running your pod.
2. PersistentVolumeClaim (PVC) are namespaced resources, as such PVC names have to be unique in a namespace
3. These labels have to match the labels defined in your PersistentVolume resource.

Tying it all together

Now that you have defined a PersistentVolumeClaim that hooks onto a PersistentVolume, one can then reference the PVC in a deployment.

AdvDeployment.yml

apiVersion: apps/v1
kind: Deployment
metadata:
  ...
spec:
  ...
  template:
    ...
    spec:
      containers:
        ...
          volumeMounts:
            - name: "azure-files" # [1]
              mountPath: "/mnt/azurefiles" # [2]
      volumes:
        - name: "azure-files" # [1]
          persistentVolumeClaim:
            claimName: team-a-app-1-azurefiles # [3]

1. Give a name to volumeMounts and the same to volumes. Both names have to match.
2. Decide where in the container you want to mount your file share.
3. The name of the persistentVolumeClaim you created earlier.

Be aware

Deleting a deployment does not delete the PVC or the PV. These are separate resources and has to be handled accordingly.

Next steps

• Deploying with Argo CD 🚀