parameter names are case-insensitive
required permissions for CSI driver controller
# To grant permissions for following actions, you need to assign both "Storage Account Contributor" # and "Storage Blob Data Contributor" roles to the CSI driver controller. Microsoft.Storage/storageAccounts/write Microsoft.Storage/storageAccounts/read Microsoft.Storage/storageAccounts/listKeys/action Microsoft.Storage/storageAccounts/*/delete Microsoft.Storage/storageAccounts/blobServices/containers/write Microsoft.Storage/storageAccounts/blobServices/containers/read Microsoft.Storage/storageAccounts/blobServices/containers/delete Microsoft.Storage/operations/read # this is only necessary if the driver creates the storage account with a private endpoint: Microsoft.Network/virtualNetworks/subnets/write Microsoft.Network/virtualNetworks/subnets/read Microsoft.Network/privateEndpoints/write Microsoft.Network/privateEndpoints/read Microsoft.Network/privateEndpoints/privateDnsZoneGroups/write Microsoft.Network/privateDnsZones/write Microsoft.Network/privateDnsZones/virtualNetworkLinks/write Microsoft.Network/privateDnsZones/virtualNetworkLinks/read Microsoft.Network/privateDnsZones/read Microsoft.Network/privateDnsOperationStatuses/read Microsoft.Network/locations/operations/read
| Name | Meaning | Example | Mandatory | Default value |
|---|---|---|---|---|
| skuName | Azure storage account type (alias: storageAccountType) |
Standard_LRS, Premium_LRS, Standard_GRS, Standard_RAGRS, Standard_ZRS, Premium_ZRS |
No | Standard_LRS |
| location | Azure location | eastus, westus, etc. |
No | if empty, driver will use the same location name as current k8s cluster |
| resourceGroup | Azure resource group name | existing resource group name | No | if empty, driver will use the same resource group name as current k8s cluster |
| storageAccount | specify Azure storage account name | STORAGE_ACCOUNT_NAME | No | When a specific storage account name is not provided, the driver will look for a suitable storage account that matches the account settings within the same resource group. If it fails to find a matching storage account, it will create a new one. However, if a storage account name is specified, the storage account must already exist. |
| protocol | specify blobfuse, blobfuse2 or NFSv3 mount | fuse, fuse2, nfs |
No | fuse |
| networkEndpointType | specify network endpoint type for the storage account created by driver. If privateEndpoint is specified, a private endpoint will be created for the storage account. For other cases, a service endpoint will be created for nfs protocol by default. |
"",privateEndpoint |
No | `` for AKS cluster, make sure cluster Control plane identity (that is, your AKS cluster name) is added to the Contributor role in the resource group hosting the VNet |
| storageEndpointSuffix | specify Azure storage endpoint suffix | core.windows.net, core.chinacloudapi.cn, etc |
No | if empty, driver will use default storage endpoint suffix according to cloud environment, e.g. core.windows.net |
| containerName | specify the existing container(directory) name | existing container name | No | if empty, driver will create a new container name, starting with pvc-fuse for blobfuse or pvc-nfs for NFSv3 |
| containerNamePrefix | specify Azure storage directory prefix created by driver | can only contain lowercase letters, numbers, hyphens, and length should be less than 21 | No | |
| server | specify Azure storage account server address | existing server address, e.g. accountname.blob.core.chinacloudapi.cn |
No | if empty, driver will use the default Azure storage account server address based on cloud provider config |
| accessTier | Access tier for storage account | Standard account can choose Hot or Cool, and Premium account can only choose Premium |
No | empty(use default setting for different storage account types) |
| allowBlobPublicAccess | Allow or disallow public access to all blobs or containers for storage account created by driver | true,false |
No | false |
| allowSharedKeyAccess | Allow or disallow shared key access for storage account created by driver (only applicable for NFS mount or blobfuse mount with managed identity) | true,false |
No | true |
| requireInfraEncryption | specify whether or not the service applies a secondary layer of encryption with platform managed keys for data at rest for storage account created by driver | true,false |
No | false |
| storageEndpointSuffix | specify Azure storage endpoint suffix | core.windows.net, core.chinacloudapi.cn, etc |
No | if empty, driver will use default storage endpoint suffix according to cloud environment |
| tags | tags would be created in newly created storage account | tag format: 'foo=aaa,bar=bbb' | No | "" |
| matchTags | whether matching tags when driver tries to find a suitable storage account | true,false |
No | false |
| useDataPlaneAPI | specify whether use data plane API for blob container create/delete, this could solve the SRP API throttling issue since data plane API has almost no limit, while it would fail when there is firewall or vnet setting on storage account | true,false |
No | false |
| --- | Following parameters are only for blobfuse | --- | --- | |
| subscriptionID | specify Azure subscription ID in which blob storage directory will be created | Azure subscription ID | No | if not empty, resourceGroup must be provided |
| storeAccountKey | Should the storage account key be stored in a Kubernetes secret (Note: if set to false, the driver will use the kubelet identity to obtain the account key) |
true,false |
No | true |
| getLatestAccountKey | whether getting the latest account key based on the creation time, this driver would get the first key by default | true,false |
No | false |
| secretName | specify secret name to store account key | No | ||
| secretNamespace | specify the namespace of secret to store account key | default,kube-system, etc |
No | pvc namespace |
| isHnsEnabled | enable Hierarchical namespace for Azure DataLake storage account |
true,false |
No | false |
| --- | Following parameters are only for NFS protocol | --- | --- | |
| mountPermissions | mounted folder permissions. The default is 0777, if set as 0, driver will not perform chmod after mount |
0777 |
No | |
| vnetResourceGroup | specify vnet resource group where virtual network is | existing resource group name | No | if empty, driver will use the vnetResourceGroup value in azure cloud config file |
| vnetName | virtual network name | existing virtual network name | No | if empty, driver will use the vnetName value in azure cloud config file |
| subnetName | subnet name | existing subnet name(s) of the agent node, if you want to update service endpoints on multiple subnets, separate them using a comma (,) |
No | if empty, driver will use the subnetName value in azure cloud config file |
| softDeleteBlobs | Enable soft delete for blobs, specify the days to retain deleted blobs | "7" | No | Soft Delete Blobs is disabled if empty |
| softDeleteContainers | Enable soft delete for containers, specify the days to retain deleted containers | "7" | No | Soft Delete Containers is disabled if empty |
| enableBlobVersioning | Enable blob versioning, can't enabled when protocol is nfs or isHnsEnabled is true |
true,false |
No | versioning for blobs is disabled if empty |
fsGroupsecurityContext setting
Blobfuse driver does not honor fsGroup securityContext setting, instead user could use -o gid=1000 in mountOptions to set ownership, check here for more mountoptions.
-
To support an Azure DataLake storage account when using blobfuse mount, you'll need to do the following:
- To create an ADLS account using the driver in dynamic provisioning, specify
isHnsEnabled: "true"in the storage class parameters. - To enable blobfuse access to an ADLS account in static provisioning, specify the mount option
--use-adls=truein the persistent volume.
- To create an ADLS account using the driver in dynamic provisioning, specify
-
account tags format created by dynamic provisioning
k8s-azure-created-by: azure
- file share name format created by dynamic provisioning(example)
pvc-92a4d7f2-f23b-4904-bad4-2cbfcff6e388
- VolumeID(
volumeHandle) is the identifier for the volume handled by the driver, format of VolumeID:rg#accountName#containerName#uuid#secretNamespace#subscriptionID
uuid,secretNamespace,subscriptionIDare optional
blobfuse read account key or SAS token from key vault example
blobfuse Managed Identity and Service Principal Name auth example
| Name | Meaning | Available Value | Mandatory | Default value |
|---|---|---|---|---|
| volumeHandle | Specify a value the driver can use to uniquely identify the storage blob container in the cluster. | A recommended way to produce a unique value is to combine the globally unique storage account name and container name: {account-name}_{container-name}. | Yes | |
| volumeAttributes.subscriptionID | specify Azure subscription ID where blob storage directory is located | Azure subscription ID | No | if not empty, resourceGroup must be provided |
| volumeAttributes.resourceGroup | Azure resource group name | existing resource group name | No | if empty, driver will use the same resource group name as current k8s cluster |
| volumeAttributes.storageAccount | existing storage account name | existing storage account name | Yes | |
| volumeAttributes.containerName | existing container name | existing container name | Yes | |
| volumeAttributes.protocol | specify blobfuse, blobfuse2 or NFSv3 mount (blobfuse2 is still in Preview) | fuse, fuse2, nfs |
No | fuse |
| volumeAttributes.server | specify Azure storage account server address | existing server address, e.g. accountname.privatelink.blob.core.windows.net |
No | if empty, driver will use default accountname.blob.core.windows.net or other sovereign cloud account address |
| volumeAttributes.storageEndpointSuffix | specify Azure storage endpoint suffix | core.windows.net, core.chinacloudapi.cn, etc |
No | if empty, driver will use default storage endpoint suffix according to cloud environment |
| --- | Following parameters are only for blobfuse | --- | --- | |
| volumeAttributes.secretName | secret name that stores storage account name and key(only applies for SMB) | No | ||
| volumeAttributes.secretNamespace | secret namespace | default,kube-system, etc |
No | pvc namespace |
| volumeAttributes.getLatestAccountKey | whether getting the latest account key based on the creation time, this driver would get the first key by default | true,false |
No | false |
| nodeStageSecretRef.name | secret name that stores(check below examples):azurestorageaccountkeyazurestorageaccountsastokenmsisecretazurestoragespnclientsecret |
existing Kubernetes secret name | No | |
| nodeStageSecretRef.namespace | secret namespace | k8s namespace | Yes | |
| --- | Following parameters are only for NFS protocol | --- | --- | |
| volumeAttributes.mountPermissions | mounted folder permissions | 0777 |
No | |
| volumeAttributes.fsGroupChangePolicy | indicates how volume's ownership will be changed by the driver, pod securityContext.fsGroupChangePolicy is ignored |
OnRootMismatch(by default), Always, None |
No | OnRootMismatch |
| --- | Following parameters are only for feature: blobfuse Managed Identity and Service Principal Name auth | --- | --- | |
| volumeAttributes.AzureStorageAuthType | Authentication Type | Key, SAS, MSI, SPN |
No | Key |
| volumeAttributes.AzureStorageIdentityClientID | Identity Client ID | No | ||
| volumeAttributes.AzureStorageIdentityObjectID | Identity Object ID (deprecated) | No | ||
| volumeAttributes.AzureStorageIdentityResourceID | Identity Resource ID | No | ||
| volumeAttributes.MSIEndpoint | MSI Endpoint | No | ||
| volumeAttributes.AzureStorageSPNClientID | SPN Client ID | No | ||
| volumeAttributes.AzureStorageSPNTenantID | SPN Tenant ID | No | ||
| volumeAttributes.AzureStorageAADEndpoint | AADEndpoint | No | ||
| --- | Following parameters are only for feature: blobfuse read account key or SAS token from key vault | --- | --- | |
| volumeAttributes.keyVaultURL | Azure Key Vault DNS name | existing Azure Key Vault DNS name | No | |
| volumeAttributes.keyVaultSecretName | Azure Key Vault secret name | existing Azure Key Vault secret name | No | |
| volumeAttributes.keyVaultSecretVersion | Azure Key Vault secret version | existing version | No | if empty, driver will use current version |
- create a Kubernetes secret for
nodeStageSecretRef.name
kubectl create secret generic azure-secret --from-literal=azurestorageaccountname="xxx" --from-literal azurestorageaccountkey="xxx" --type=Opaque
kubectl create secret generic azure-secret --from-literal=azurestorageaccountname="xxx" --from-literal azurestorageaccountsastoken="xxx" --type=Opaque
kubectl create secret generic azure-secret --from-literal msisecret="xxx" --type=Opaque
# azurestoragespnclientid, azurestoragespntenantid field setting in secret is only supported from v1.21.3
kubectl create secret generic azure-secret --from-literal azurestoragespnclientsecret="xxx" azurestoragespnclientid="xxx" azurestoragespntenantid="xxx" --type=Opaque- mounting blobfuse requires account key, if
nodeStageSecretReffield is not provided in PV config, azure file driver would try to getazure-storage-account-{accountname}-secretin the pod namespace first, if that secret does not exist, it would get account key by Azure storage account API directly using kubelet identity (make sure kubelet identity has reader access to the storage account). - mounting blob storage NFSv3 does not need account key, NFS mount access is configured by following setting:
Firewalls and virtual networks: selectEnabled from selected virtual networks and IP addresseswith same vnet as agent node
- blobfuse cache(
--tmp-pathmount option)- By default, the blobfuse cache is located in the
/mntdirectory. If the VM SKU provides a temporary disk, the/mntdirectory is mounted on the temporary disk. However, if the VM SKU does not provide a temporary disk, the/mntdirectory is mounted on the OS disk. - with blobfuse-proxy deployment (default on AKS), user could set
--tmp-path=mount option to specify a different cache directory
- By default, the blobfuse cache is located in the
- Mount Azure blob storage with managed identity
- Blobfuse Performance and caching
--disable-writeback-cache=true: disallow libfuse to buffer write requests if you must strictly open files in O_WRONLY or O_APPEND mode
- Blobfuse CLI Flag Options v1 & v2
if
containerNamevalue contains following strings, it would be converted into corresponding pv/pvc name or namespace
${pvc.metadata.name}${pvc.metadata.namespace}${pv.metadata.name}