The Azure Key Vault provider for Secrets Store CSI Driver enables retrieving secrets, keys, and certificates stored in Azure Key Vault and accessing them as files from mounted volumes in an AKS cluster. This method eliminates the need for Azure-specific libraries to access the secrets.
This Secret Store CSI Driver for Key Vault offers the following features:
- Mounts secrets, keys, and certificates to a pod using a CSI volume.
- Supports CSI inline volumes.
- Allows the mounting of multiple secrets store objects as a single volume.
- Offers pod portability with the SecretProviderClass CRD.
- Compatible with Windows containers.
- Keeps in sync with Kubernetes secrets.
- Supports auto-rotation of mounted contents and synced Kubernetes secrets.
When auto-rotation is enabled for the Azure Key Vault Secrets Provider, it automatically updates both the pod mount and the corresponding Kubernetes secret defined in the secretObjects field of SecretProviderClass. It continuously polls for changes based on the rotation poll interval (default is two minutes).
If a secret in an external secrets store is updated after the initial deployment of the pod, both the Kubernetes Secret and the pod mount will periodically update, depending on how the application consumes the secret data. Here are the recommended approaches for different scenarios:
- Mount the Kubernetes Secret as a volume: Utilize the auto-rotation and sync K8s secrets features of Secrets Store CSI Driver. The application should monitor changes from the mounted Kubernetes Secret volume. When the CSI Driver updates the Kubernetes Secret, the volume contents will be automatically updated.
- Application reads data from the container filesystem: Take advantage of the rotation feature of Secrets Store CSI Driver. The application should monitor file changes from the volume mounted by the CSI driver.
- Use the Kubernetes Secret for an environment variable: Restart the pod to acquire the latest secret as an environment variable. You can use tools like Reloader to watch for changes on the synced Kubernetes Secret and perform rolling upgrades on pods.
- Secrets, keys, and certificates can be accessed as files from mounted volumes.
- Optionally, Kubernetes secrets can be created to store keys, secrets, and certificates from Key Vault.
- No need for Azure-specific libraries to access secrets.
- Simplifies secret management with transparent integration.
- Still requires accessing managed services such as Azure Service Bus or Azure Storage using their own connection strings from Azure Key Vault.
- Cannot utilize Microsoft Entra ID integrated security and managed identities for accessing managed services.
Running on LocalStack? Install the lstk CLI and run
lstk az start-interceptionto route Azure CLI calls to the emulator. See Run against LocalStack for the full setup.
The add-on installs one CSI driver and one Azure provider in kube-system, and both samples mount the same two secrets from the same key vault. Only the identity the provider authenticates with differs:
%%{init: {'themeVariables': {'clusterBkg': 'transparent', 'clusterBorder': '#8c8c8c'}}}%%
flowchart LR
subgraph aks["Azure Kubernetes Service cluster"]
subgraph kubesystem["kube-system: Azure Key Vault Secrets Provider add-on"]
driver["secrets-store-csi-driver"]
provider["secrets-store-provider-azure"]
end
subgraph wins["namespace wi-secret-store-test"]
wisa["secret-store-sa<br/>ServiceAccount, annotated with the client id"]
wispc["demo-secret-provider-class<br/>SecretProviderClass, clientID"]
wipod["demo-pod<br/>nginx, label azure.workload.identity/use"]
end
subgraph mins["namespace mi-secret-store-test"]
mispc["demo-secret-provider-class<br/>SecretProviderClass, useVMManagedIdentity"]
mipod["demo-pod<br/>nginx, no service account"]
end
end
subgraph azure["Azure"]
uami["local-identity-test<br/>user-assigned managed identity, customer-created"]
addonid["azureKeyvaultSecretsProvider<br/>add-on identity, node resource group"]
kv[("local-kv-test<br/>key vault: username, password")]
end
wisa -.->|"federated credential<br/>system:serviceaccount:wi-secret-store-test:secret-store-sa"| uami
wisa -.->|"identity used by"| wipod
wispc -.->|"read by"| provider
mispc -.->|"read by"| provider
driver -->|"mounts /mnt/secrets read-only"| wipod
driver -->|"mounts /mnt/secrets read-only"| mipod
driver -.->|"delegates each mount to"| provider
provider -.->|"workload-identity sample: exchanges the pod's projected token for"| uami
provider -.->|"user-assigned-managed-identity sample: authenticates as"| addonid
uami -->|"workload-identity sample: Key Vault Administrator<br/>reads username and password"| kv
addonid -->|"user-assigned-managed-identity sample: Key Vault Administrator<br/>reads username and password"| kv
The Azure Key Vault provider for Secrets Store CSI Driver supports more than one way to authenticate to Azure Key Vault. This folder contains two samples, each demonstrating a different identity access mode. Both samples mount the same username and password secrets into a demo nginx pod, but they differ in how the CSI driver obtains the credentials used to read the secrets from Key Vault.
| Sample | Identity Access Mode | Identity Used |
|---|---|---|
workload-identity |
Microsoft Entra Workload ID | A customer-created user-assigned managed identity federated with the pod's Kubernetes service account |
user-assigned-managed-identity |
User-assigned managed identity | The user-assigned managed identity created by the resource provider in the node resource group when enabling the addon |
The workload-identity sample uses a customer-created user-assigned managed identity that is consumed by the pod through Microsoft Entra Workload ID with Azure Kubernetes Service (AKS), as described in Configure Workload Identity to access Key Vault.
With this approach, a managed identity is created and a federated identity credential establishes trust between the AKS OIDC issuer and a Kubernetes service account. The service account is annotated with the managed identity client ID and labeled to use workload identity, and the demo pod references this service account. At runtime, the pod exchanges its projected service account token for an Entra ID token, which the CSI driver uses to read the secrets from Key Vault. This is the recommended, more secure, and portable approach.
The user-assigned-managed-identity sample uses the user-assigned managed identity that the resource provider automatically creates in the node resource group when the Azure Key Vault Secrets Provider addon is enabled on the cluster, as described in Configure User-assigned Managed Identity to access Key Vault.
With this approach, no additional managed identity or federated credential is created. Instead, the addon's built-in azureKeyvaultSecretsProvider identity is granted access to the Key Vault, and the SecretProviderClass references it via useVMManagedIdentity and userAssignedIdentityID. The demo pod does not require a workload identity service account or labels.
00-variables.sh: Sources parent variables and defines Kubernetes namespace, SecretProviderClass name, and pod name for this authentication approach.01-enable-addon.sh: Enables the Azure Key Vault Secrets Provider addon on the AKS cluster with secret rotation enabled (if not already active).02-create-key-vault-and-secrets.sh: Creates the resource group and Azure Key Vault, then populates it with test secrets (username and password).03-create-role-assignment.sh: Creates RBAC role assignments to grant the Key Vault Secrets Provider system-managed identity permission to read secrets from the Key Vault.04-create-secret-provider-class.sh: Creates the SecretProviderClass resource that configures the CSI driver to retrieve secrets from Key Vault using the system-managed identity.05-create-demo-pod.sh: Creates a demo nginx pod that mounts the secrets as a volume using the CSI driver.06-list-secrets.sh: Lists and displays the contents of secrets that were successfully mounted in the pod.
00-variables.sh: Sources parent variables and defines Kubernetes namespace, service account, SecretProviderClass name, and pod name for this authentication approach.01-enable-addon.sh: Enables the Azure Key Vault Secrets Provider addon on the AKS cluster with secret rotation enabled (if not already active).02-create-key-vault-and-secrets.sh: Creates the resource group and Azure Key Vault, then populates it with test secrets (username and password).03-create-managed-identity.sh: Creates the resource group and an Azure managed identity configured for Workload Identity Federation with the AKS cluster.04-create-secret-provider-class.sh: Creates the SecretProviderClass resource that configures the CSI driver to retrieve secrets using Workload Identity Federation.05-create-demo-pod.sh: Creates a demo nginx pod with workload identity labels and service account that mounts secrets via the CSI driver volume.06-list-secrets.sh: Lists and displays the contents of secrets that were successfully mounted in the pod.