Enable KMS data encryption in Azure Kubernetes Service (AKS) clusters (Preview)

This article shows you how to enable Key Management Service (KMS) data encryption for Kubernetes secrets in Azure Kubernetes Service (AKS). KMS encryption encrypts Kubernetes secrets stored in etcd using Azure Key Vault keys.

AKS supports two key management options:

Platform-managed keys (PMK): AKS automatically creates and manages the encryption keys. This option provides the simplest setup with automatic key rotation.
Customer-managed keys (CMK): You create and manage your own Azure Key Vault and encryption keys. This option provides full control over key lifecycle and meets compliance requirements that mandate customer-managed keys.

For more information about encryption concepts and key options, see Data encryption at rest concepts for AKS.

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

Prerequisites

Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
- If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.
- When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.
- Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

This article requires version 2.73.0 or later of the Azure CLI. If you're using Azure Cloud Shell, the latest version is already installed there.
You need the aks-preview Azure CLI extension version 19.0.0b13 or later.
- If you don't already have the aks-preview extension, install it using the az extension add command.
```
az extension add --name aks-preview
```
- If you already have the aks-preview extension, update it to make sure you have the latest version using the az extension update command.
```
az extension update --name aks-preview
```
kubectl CLI tool installed.

Register the feature flag

To use KMS data encryption with platform-managed keys, register the KMSPMKPreview feature flag in your subscription.

az feature register --namespace Microsoft.ContainerService --name KMSPMKPreview

Verify the registration status using the az feature show command. It takes a few minutes for the status to show Registered.
```
az feature show --namespace Microsoft.ContainerService --name KMSPMKPreview
```
When the status shows Registered, refresh the registration of the Microsoft.ContainerService resource provider using the az provider register command.
```
az provider register --namespace Microsoft.ContainerService
```

Set up environment variables

Set up environment variables for your deployment. Replace the placeholder values with your own.

# Set environment variables
export SUBSCRIPTION_ID="<your-subscription-id>"
export RESOURCE_GROUP="<your-resource-group>"
export LOCATION="<your-location>"
export CLUSTER_NAME="<your-cluster-name>"

# Set subscription
az account set --subscription $SUBSCRIPTION_ID

# Create resource group if it doesn't exist
az group create --name $RESOURCE_GROUP --location $LOCATION

Enable platform-managed key encryption

With platform-managed keys, AKS automatically creates and manages the Azure Key Vault and encryption keys. Key rotation is handled automatically by the platform.

Create a new AKS cluster with platform-managed keys

Create a new AKS cluster with KMS encryption using platform-managed keys.

az aks create \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --kubernetes-version 1.33.0 \
    --kms-infrastructure-encryption Enabled \
    --generate-ssh-keys

Enable platform-managed keys on an existing cluster

Enable KMS encryption with platform-managed keys on an existing AKS cluster.

Note

The cluster must be running Kubernetes version 1.33 or later.

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --kms-infrastructure-encryption Enabled

Enable customer-managed key encryption with a private key vault

For enhanced security, you can use a private key vault that has public network access disabled. AKS accesses the private key vault through the trusted services firewall exception. This section shows how to configure customer-managed keys with a private key vault.

Create a key vault and key with trusted services access

Note

This section illustrates creating a key vault with public network access initially, then enabling the firewall with trusted services bypass. This approach is for illustrative purposes only. In production environments, you should create and manage your key vault as private from the start. For guidance on managing private key vaults, see Azure Key Vault network security.

Create a key vault with Azure RBAC enabled.

export KEY_VAULT_NAME="<your-key-vault-name>"

az keyvault create \
    --name $KEY_VAULT_NAME \
    --resource-group $RESOURCE_GROUP \
    --enable-rbac-authorization true \
    --public-network-access Enabled

# Get the key vault resource ID
export KEY_VAULT_RESOURCE_ID=$(az keyvault show --name $KEY_VAULT_NAME --resource-group $RESOURCE_GROUP --query id -o tsv)

Assign yourself the Key Vault Crypto Officer role to create a key.

az role assignment create \
    --role "Key Vault Crypto Officer" \
    --assignee-object-id $(az ad signed-in-user show --query id -o tsv) \
    --assignee-principal-type "User" \
    --scope $KEY_VAULT_RESOURCE_ID

Create a key in the key vault.

export KEY_NAME="<your-key-name>"

az keyvault key create --name $KEY_NAME --vault-name $KEY_VAULT_NAME

# Get the key ID (without version for automatic rotation)
export KEY_ID=$(az keyvault key show --name $KEY_NAME --vault-name $KEY_VAULT_NAME --query 'key.kid' -o tsv)
export KEY_ID_NO_VERSION=$(echo $KEY_ID | sed 's|/[^/]*$||')

Enable the key vault firewall with trusted services bypass.
```
az keyvault update \
    --name $KEY_VAULT_NAME \
    --resource-group $RESOURCE_GROUP \
    --default-action Deny \
    --bypass AzureServices
```
The --default-action Deny parameter blocks public network access, and the --bypass AzureServices parameter allows trusted Azure services (including AKS) to access the key vault.

Create a user-assigned managed identity

Create a user-assigned managed identity for the cluster.

export IDENTITY_NAME="<your-identity-name>"

az identity create --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP

# Get the identity details
export IDENTITY_OBJECT_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'principalId' -o tsv)
export IDENTITY_RESOURCE_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'id' -o tsv)

Assign the required roles to the managed identity.

# Assign Key Vault Crypto User role for encrypt/decrypt operations
az role assignment create \
    --role "Key Vault Crypto User" \
    --assignee-object-id $IDENTITY_OBJECT_ID \
    --assignee-principal-type "ServicePrincipal" \
    --scope $KEY_VAULT_RESOURCE_ID

# Assign Key Vault Contributor role for key management
az role assignment create \
    --role "Key Vault Contributor" \
    --assignee-object-id $IDENTITY_OBJECT_ID \
    --assignee-principal-type "ServicePrincipal" \
    --scope $KEY_VAULT_RESOURCE_ID

Create a new AKS cluster with customer-managed keys (private)

Create a new AKS cluster with KMS encryption using customer-managed keys with a private key vault.

az aks create \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --kubernetes-version 1.33.0 \
    --kms-infrastructure-encryption Enabled \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID_NO_VERSION \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID \
    --azure-keyvault-kms-key-vault-network-access Private \
    --assign-identity $IDENTITY_RESOURCE_ID \
    --generate-ssh-keys

Enable customer-managed keys on an existing cluster (private)

Enable KMS encryption with customer-managed keys using a private key vault on an existing AKS cluster.

Note

The cluster must be running Kubernetes version 1.33 or later.

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --kms-infrastructure-encryption Enabled \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID_NO_VERSION \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID \
    --azure-keyvault-kms-key-vault-network-access Private \
    --assign-identity $IDENTITY_RESOURCE_ID

Enable customer-managed key encryption with a public key vault

With customer-managed keys, you create and manage your own Azure Key Vault and encryption keys. This section shows how to configure customer-managed keys with a public key vault.

Create a key vault and key

Create a key vault with Azure RBAC enabled.

export KEY_VAULT_NAME="<your-key-vault-name>"

az keyvault create \
    --name $KEY_VAULT_NAME \
    --resource-group $RESOURCE_GROUP \
    --enable-rbac-authorization true \
    --public-network-access Enabled

# Get the key vault resource ID
export KEY_VAULT_RESOURCE_ID=$(az keyvault show --name $KEY_VAULT_NAME --resource-group $RESOURCE_GROUP --query id -o tsv)

Assign yourself the Key Vault Crypto Officer role to create a key.

az role assignment create \
    --role "Key Vault Crypto Officer" \
    --assignee-object-id $(az ad signed-in-user show --query id -o tsv) \
    --assignee-principal-type "User" \
    --scope $KEY_VAULT_RESOURCE_ID

Create a key in the key vault.

export KEY_NAME="<your-key-name>"

az keyvault key create --name $KEY_NAME --vault-name $KEY_VAULT_NAME

# Get the key ID (without version for automatic rotation)
export KEY_ID=$(az keyvault key show --name $KEY_NAME --vault-name $KEY_VAULT_NAME --query 'key.kid' -o tsv)
export KEY_ID_NO_VERSION=$(echo $KEY_ID | sed 's|/[^/]*$||')

Create a user-assigned managed identity

Create a user-assigned managed identity for the cluster.

export IDENTITY_NAME="<your-identity-name>"

az identity create --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP

# Get the identity details
export IDENTITY_OBJECT_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'principalId' -o tsv)
export IDENTITY_RESOURCE_ID=$(az identity show --name $IDENTITY_NAME --resource-group $RESOURCE_GROUP --query 'id' -o tsv)

Assign the required roles to the managed identity.

# Assign Key Vault Crypto User role for encrypt/decrypt operations
az role assignment create \
    --role "Key Vault Crypto User" \
    --assignee-object-id $IDENTITY_OBJECT_ID \
    --assignee-principal-type "ServicePrincipal" \
    --scope $KEY_VAULT_RESOURCE_ID

# Assign Key Vault Contributor role for key management
az role assignment create \
    --role "Key Vault Contributor" \
    --assignee-object-id $IDENTITY_OBJECT_ID \
    --assignee-principal-type "ServicePrincipal" \
    --scope $KEY_VAULT_RESOURCE_ID

Create a new AKS cluster with customer-managed keys

Create a new AKS cluster with KMS encryption using customer-managed keys.

az aks create \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --kubernetes-version 1.33.0 \
    --kms-infrastructure-encryption Enabled \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID_NO_VERSION \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID \
    --azure-keyvault-kms-key-vault-network-access Public \
    --assign-identity $IDENTITY_RESOURCE_ID \
    --generate-ssh-keys

Enable customer-managed keys on an existing cluster

Enable KMS encryption with customer-managed keys on an existing AKS cluster.

Note

The cluster must be running Kubernetes version 1.33 or later.

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --kms-infrastructure-encryption Enabled \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID_NO_VERSION \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID \
    --azure-keyvault-kms-key-vault-network-access Public \
    --assign-identity $IDENTITY_RESOURCE_ID

Verify KMS configuration

After enabling KMS encryption, verify the configuration.

az aks show --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --query 'securityProfile'

The output includes the KMS configuration:

{
    "azureKeyVaultKms": {
        "enabled": true,
        "keyId": "https://<key-vault-name>.vault.azure.net/keys/<key-name>",
        "keyVaultNetworkAccess": "Public",
        "keyVaultResourceId": "<key-vault-resource-id>"
    },
    "kubernetesResourceObjectEncryptionProfile": {
        "infrastructureEncryption": "Enabled"
    }
}

Migrate between key management options

You can migrate between platform-managed keys and customer-managed keys.

Migrate from platform-managed keys to customer-managed keys

To migrate from platform-managed keys to customer-managed keys, first set up the key vault, key, and managed identity as described in the customer-managed keys section, then run the update command:

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --kms-infrastructure-encryption Enabled \
    --enable-azure-keyvault-kms \
    --azure-keyvault-kms-key-id $KEY_ID_NO_VERSION \
    --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID \
    --azure-keyvault-kms-key-vault-network-access Public \
    --assign-identity $IDENTITY_RESOURCE_ID

Migrate from customer-managed keys to platform-managed keys

To migrate from customer-managed keys to platform-managed keys:

az aks update \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --kms-infrastructure-encryption Enabled \
    --disable-azure-keyvault-kms

Key rotation

With KMS data encryption, key rotation is handled differently depending on your key management option:

Platform-managed keys: Key rotation is automatic. No action is required.
Customer-managed keys: When you rotate the key version in Azure Key Vault, the KMS controller detects the rotation periodically (every 6 hours) and uses the new key version.

Note

Unlike the legacy KMS experience, with this new implementation you don't need to manually re-encrypt secrets after key rotation. The platform handles this automatically.

Feedback

Was this page helpful?

Last updated on 2025-12-22

Share via

Enable KMS data encryption in Azure Kubernetes Service (AKS) clusters (Preview)

Prerequisites

Register the feature flag

Set up environment variables

Enable platform-managed key encryption

Create a new AKS cluster with platform-managed keys

Enable platform-managed keys on an existing cluster

Enable customer-managed key encryption with a private key vault

Create a key vault and key with trusted services access

Create a user-assigned managed identity

Create a new AKS cluster with customer-managed keys (private)

Enable customer-managed keys on an existing cluster (private)

Enable customer-managed key encryption with a public key vault

Create a key vault and key

Create a user-assigned managed identity

Create a new AKS cluster with customer-managed keys

Enable customer-managed keys on an existing cluster

Verify KMS configuration

Migrate between key management options

Migrate from platform-managed keys to customer-managed keys

Migrate from customer-managed keys to platform-managed keys

Key rotation

Related content

Feedback

Additional resources