Migrate to Key Management Service (KMS) v2 in Azure Kubernetes Service (AKS)

In this article, you learn how to migrate to KMS v2 for clusters with versions older than 1.27. Beginning in AKS version 1.27, turning on the KMS feature configures KMS v2. With KMS v2, you aren't limited to the 2,000 secrets that earlier versions support. For more information, see KMS v2 improvements.

Turn off KMS

1. Disable KMS on an existing cluster using the az aks update command with the --disable-azure-keyvault-kms parameter.

   az aks update --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --disable-azure-keyvault-kms
   

2. Update all secrets using the kubectl get secrets command to ensure the secrets created earlier are no longer encrypted. For larger clusters, you might want to subdivide the secrets by namespace or create an update script. If the previous command to update KMS fails, still run the following command to avoid unexpected state for KMS plugin.

   kubectl get secrets --all-namespaces -o json | kubectl replace -f -
   

Upgrade your AKS cluster and turn on KMS

1. Upgrade your AKS cluster to version 1.27 or later using the az aks upgrade command with the --kubernetes-version parameter set to your desired version. The following example upgrades to version 1.27.1:

   az aks upgrade --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --kubernetes-version 1.27.1
   

2. Once the upgrade completes, you can turn on KMS for a public or private key vault using one of the following resources:

   • Enable a public key vault and KMS on an existing AKS cluster
   • Update an existing AKS cluster to turn on KMS etcd encryption for a private key vault

3. Update all secrets using the kubectl get secrets command to ensure the secrets created earlier are no longer encrypted. For larger clusters, you might want to subdivide the secrets by namespace or create an update script. If the previous command to update KMS fails, still run the following command to avoid unexpected state for KMS plugin.

   kubectl get secrets --all-namespaces -o json | kubectl replace -f -
   

Next steps

For more information on using KMS with AKS, see the following articles:

• Update the key vault mode for an Azure Kubernetes Service (AKS) cluster with KMS etcd encryption
• Observability for KMS etcd encryption in Azure Kubernetes Service (AKS)