This is a cache of https://docs.okd.io/4.14/storage/container_storage_interface/persistent-storage-csi-azure-file.html. It is a snapshot of the page at 2025-07-04T05:05:16.223+0000.
Azure File CSI Driver Operator - Using Container Storage Interface (CSI) | Storage | OKD 4.14
×

Overview

OKD is capable of provisioning persistent volumes (PVs) by using the Container Storage Interface (CSI) driver for Microsoft Azure File Storage.

Familiarity with persistent storage and configuring CSI volumes is recommended when working with a CSI Operator and driver.

To create CSI-provisioned PVs that mount to Azure File storage assets, OKD installs the Azure File CSI Driver Operator and the Azure File CSI driver by default in the openshift-cluster-csi-drivers namespace.

  • The Azure File CSI Driver Operator provides a storage class that is named azurefile-csi that you can use to create persistent volume claims (PVCs). You can disable this default storage class if desired (see Managing the default storage class).

  • The Azure File CSI driver enables you to create and mount Azure File PVs. The Azure File CSI driver supports dynamic volume provisioning by allowing storage volumes to be created on-demand, eliminating the need for cluster administrators to pre-provision storage.

Azure File CSI Driver Operator does not support:

  • Virtual hard disks (VHD)

  • Running on nodes with Federal Information Processing Standard (FIPS) mode enabled for Server Message Block (SMB) file share. However, Network File System (NFS) does support FIPS mode.

For more information about supported features, see Supported CSI drivers and features.

NFS support

OKD 4.14, and later, supports Azure File Container Storage Interface (CSI) Driver Operator with Network File System (NFS) with the following caveats:

  • Creating pods with Azure File NFS volumes that are scheduled to the control plane node causes the mount to be denied.

    To work around this issue: If your control plane nodes are schedulable, and the pods can run on worker nodes, use nodeSelector or Affinity to schedule the pod in worker nodes.

  • FS Group policy behavior:

    Azure File CSI with NFS does not honor the fsGroupChangePolicy requested by pods. Azure File CSI with NFS applies a default OnRootMismatch FS Group policy regardless of the policy requested by the pod.

  • The Azure File CSI Operator does not automatically create a storage class for NFS. You must create it manually. Use a file similar to the following:

    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: <storage-class-name> (1)
    provisioner: file.csi.azure.com (2)
    parameters:
      protocol: nfs (3)
      skuName: Premium_LRS  # available values: Premium_LRS, Premium_ZRS
    mountOptions:
      - nconnect=4
    1 Storage class name.
    2 Specifies the Azure File CSI provider.
    3 Specifies NFS as the storage backend protocol.

About CSI

Storage vendors have traditionally provided storage drivers as part of Kubernetes. With the implementation of the Container Storage Interface (CSI), third-party providers can instead deliver storage plugins using a standard interface without ever having to change the core Kubernetes code.

CSI Operators give OKD users storage options, such as volume snapshots, that are not possible with in-tree volume plugins.

Static provisioning for Azure File

For static provisioning, cluster administrators create persistent volumes (PVs) that define the details of the real storage. Cluster users can then create persistent volume claims (PVCs) that consume these PVs.

Prerequisites
  • Access to an OKD cluster with administrator rights

Procedure

To use static provisioning for Azure File:

  1. If you have not yet created a secret for the Azure storage account, create it now:

    This secret must contain the Azure Storage Account name and key with the following very specific format with two key-value pairs:

    • azurestorageaccountname: <storage_account_name>

    • azurestorageaccountkey: <account_key>

      To create a secret named azure-secret, run the following command:

      oc create secret generic azure-secret  -n <namespace_name> --type=Opaque --from-literal=azurestorageaccountname="<storage_account_name>" --from-literal=azurestorageaccountkey="<account_key>"  (1) (2)
      1 Set <namespace_name> to the namespace where the PV is consumed.
      2 Provide your values for <storage_account_name> and <account_key>.
  2. Create a PV by using the following example YAML file:

    Example PV YAML file
    apiVersion: v1
    kind: PersistentVolume
    metadata:
      annotations:
        pv.kubernetes.io/provisioned-by: file.csi.azure.com
      name: pv-azurefile
    spec:
      capacity:
        storage: 5Gi (1)
      accessModes:
        - ReadWriteMany (2)
      persistentVolumeReclaimPolicy: Retain (3)
      storageClassName: <sc-name> (4)
      mountOptions:
        - dir_mode=0777  (5)
        - file_mode=0777
        - uid=0
        - gid=0
        - cache=strict  (6)
        - nosharesock  (7)
        - actimeo=30  (8)
        - nobrl  (9)
      csi:
        driver: file.csi.azure.com
        volumeHandle: "{resource-group-name}#{account-name}#{file-share-name}" (10)
        volumeAttributes:
          shareName: EXISTING_FILE_SHARE_NAME  (11)
        nodeStageSecretRef:
          name: azure-secret (12)
          namespace: <my-namespace> (13)
    1 Volume size.
    2 Access mode. Defines the read-write and mount permissions. For more information, under Additional Resources, see Access modes.
    3 Reclaim policy. Tells the cluster what to do with the volume after it is released. Accepted values are Retain, Recycle, or Delete.
    4 Storage class name. This name is used by the PVC to bind to this specific PV. For static provisioning, a StorageClass object does not need to exist, but the name in the PV and PVC must match.
    5 Modify this permission if you want to enhance the security.
    6 Cache mode. Accepted values are none, strict, and loose. The default is strict.
    7 Use to reduce the probability of a reconnect race.
    8 The time (in seconds) that the CIFS client caches attributes of a file or directory before it requests attribute information from a server.
    9 Disables sending byte range lock requests to the server, and for applications which have challenges with POSIX locks.
    10 Ensure that volumeHandle is unique across the cluster. The resource-group-name is the Azure resource group where the storage account resides.
    11 File share name. Use only the file share name; do not use full path.
    12 Provide the name of the secret created in step 1 of this procedure. In this example, it is azure-secret.
    13 The namespace that the secret was created in. This must be the namespace where the PV is consumed.
  3. Create a PVC that references the PV using the following example file:

    Example PVC YAML file
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: <pvc-name> (1)
      namespace: <my-namespace> (2)
    spec:
      volumeName: pv-azurefile (3)
      storageClassName: <sc-name> (4)
      accessModes:
        - ReadWriteMany (5)
      resources:
        requests:
          storage: 5Gi (6)
    1 PVC name.
    2 Namespace for the PVC.
    3 The name of the PV that you created in the previous step.
    4 Storage class name. This name is used by the PVC to bind to this specific PV. For static provisioning, a StorageClass object does not need to exist, but the name in the PV and PVC must match.
    5 Access mode. Defines the requested read-write access for the PVC. Claims use the same conventions as volumes when requesting storage with specific access modes. For more information, under Additional Resources, see Access modes.
    6 PVC size.
  4. Ensure that the PVC is created and in Bound status after a while by running the following command:

    $ oc get pvc <pvc-name> (1)
    1 The name of your PVC.
    Example output
    NAME       STATUS    VOLUME         CAPACITY   ACCESS MODES   STORAGECLASS   AGE
    pvc-name   Bound     pv-azurefile   5Gi        ReadWriteMany  my-sc          7m2s