Use the Azure Key Vault provider for Secrets Store CSI Driver in an Azure Kubernetes Service (AKS) cluster

The Azure Key Vault provider for Secrets Store CSI Driver allows for the integration of an Azure Key Vault as a secret store with an Azure Kubernetes Service (AKS) cluster via a CSI volume.

Features

  • Mounts secrets, keys, and certificates to a pod using a CSI volume.
  • Supports CSI inline volumes.
  • Supports mounting multiple secrets store objects as a single volume.
  • Supports pod portability with the SecretProviderClass CRD.
  • Supports Windows containers.
  • Syncs with Kubernetes secrets.
  • Supports autorotation of mounted contents and synced Kubernetes secrets.

Limitations

A container using subPath volume mount doesn't receive secret updates when it's rotated. For more information, see Secrets Store CSI Driver known limitations.

Prerequisites

  • If you don't have an Azure subscription, create a free account before you begin.
  • Check that your version of the Azure CLI is 2.30.0 or later. If it's an earlier version, install the latest version.
  • If you're restricting Ingress to the cluster, make sure ports 9808 and 8095 are open.
  • The minimum recommended Kubernetes version is based on the rolling Kubernetes version support window. Make sure you're running version N-2 or later.

Create an AKS cluster with Azure Key Vault provider for Secrets Store CSI Driver support

  1. Create an Azure resource group using the az group create command.

    az group create --name myResourceGroup --location eastus2
    
  2. Create an AKS cluster with Azure Key Vault provider for Secrets Store CSI Driver capability using the az aks create command with the --enable-addons azure-keyvault-secrets-provider parameter. The add-on creates a user-assigned managed identity you can use to authenticate to your key vault. The following example creates an AKS cluster with the Azure Key Vault provider for Secrets Store CSI Driver enabled.

    Note

    If you want to use Microsoft Entra Workload ID, you must also use the --enable-oidc-issuer and --enable-workload-identity parameters, such as in the following example:

    az aks create --name myAKSCluster --resource-group myResourceGroup --enable-addons azure-keyvault-secrets-provider --enable-oidc-issuer --enable-workload-identity --generate-ssh-keys
    
    az aks create \
        --name myAKSCluster \
        --resource-group myResourceGroup \
        --enable-addons azure-keyvault-secrets-provider \
        --generate-ssh-keys
    
  3. The previous command creates a user-assigned managed identity, azureKeyvaultSecretsProvider, to access Azure resources. The following example uses this identity to connect to the key vault that stores the secrets, but you can also use other identity access methods. Take note of the identity's clientId in the output.

    ...,
     "addonProfiles": {
        "azureKeyvaultSecretsProvider": {
          ...,
          "identity": {
            "clientId": "<client-id>",
            ...
          }
        }
    

Note

After you enable this feature, AKS creates a managed identity named azurekeyvaultsecretsprovider-xxx in the node resource group and assigns it to the Virtual Machine Scale Sets (VMSS) automatically. You can use this managed identity or your own managed identity to access the key vault. It's not supported to prevent creation of the identity.

Upgrade an existing AKS cluster with Azure Key Vault provider for Secrets Store CSI Driver support

  • Upgrade an existing AKS cluster with Azure Key Vault provider for Secrets Store CSI Driver capability using the az aks enable-addons command and enable the azure-keyvault-secrets-provider add-on. The add-on creates a user-assigned managed identity you can use to authenticate to your key vault.

    az aks enable-addons --addons azure-keyvault-secrets-provider --name myAKSCluster --resource-group myResourceGroup
    

Note

After you enable this feature, AKS creates a managed identity named azurekeyvaultsecretsprovider-xxx in the node resource group and assigns it to the Virtual Machine Scale Sets (VMSS) automatically. You can use this managed identity or your own managed identity to access the key vault. It's not supported to prevent creation of the identity.

Verify the Azure Key Vault provider for Secrets Store CSI Driver installation

  1. Get the AKS cluster credentials using the [az aks get-credentials][az-aks-get-credentials] command.

    az aks get-credentials --name myAKSCluster --resource-group myResourceGroup
    
  2. Verify the installation is finished using the kubectl get pods command, which lists all pods with the secrets-store-csi-driver and secrets-store-provider-azure labels in the kube-system namespace.

    kubectl get pods -n kube-system -l 'app in (secrets-store-csi-driver,secrets-store-provider-azure)'
    

    Your output should look similar to the following example output:

    NAME                                     READY   STATUS    RESTARTS   AGE
    aks-secrets-store-csi-driver-4vpkj       3/3     Running   2          4m25s
    aks-secrets-store-csi-driver-ctjq6       3/3     Running   2          4m21s
    aks-secrets-store-csi-driver-tlvlq       3/3     Running   2          4m24s
    aks-secrets-store-provider-azure-5p4nb   1/1     Running   0          4m21s
    aks-secrets-store-provider-azure-6pqmv   1/1     Running   0          4m24s
    aks-secrets-store-provider-azure-f5qlm   1/1     Running   0          4m25s
    
  3. Verify that each node in your cluster's node pool has a Secrets Store CSI Driver pod and a Secrets Store Provider Azure pod running.

Create or use an existing Azure Key Vault

  1. Create or update a key vault with Azure role-based access control (Azure RBAC) enabled using the az keyvault create command or the az keyvault update command with the --enable-rbac-authorization flag. The name of the key vault must be globally unique. For more details on key vault permission models and Azure RBAC, see Provide access to Key Vault keys, certificates, and secrets with an Azure role-based access control

    ## Create a new Azure key vault
    az keyvault create --name <keyvault-name> --resource-group myResourceGroup --location eastus2 --enable-rbac-authorization
    
    ## Update an existing Azure key vault
    az keyvault update --name <keyvault-name> --resource-group myResourceGroup --location eastus2 --enable-rbac-authorization
    
  2. Your key vault can store keys, secrets, and certificates. In this example, use the az keyvault secret set command to set a plain-text secret called ExampleSecret.

    az keyvault secret set --vault-name <keyvault-name> --name ExampleSecret --value MyAKSExampleSecret
    
  3. Take note of the following properties for future use:

    • The name of the secret object in the key vault
    • The object type (secret, key, or certificate)
    • The name of your key vault resource
    • The Azure tenant ID of the subscription

Next steps

In this article, you learned how to use the Azure Key Vault provider for Secrets Store CSI Driver in an AKS cluster. You now need to provide an identity to access the Azure Key Vault. To learn how, continue to the next article.