Edit

Share via

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

Important

This article applies to clusters using the legacy KMS experience that need to migrate from KMS v1 to KMS v2. For clusters running Kubernetes version 1.33 or later, we recommend using the new KMS data encryption experience, which offers platform-managed keys, customer-managed keys with automatic key rotation, and a simplified configuration experience.

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.

Important

If your cluster version is older than 1.27 and you already turned on KMS, the upgrade to cluster version 1.27 or later is blocked.

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 -

    When you run the command, the following error is safe to ignore:

    The object has been modified; please apply your changes to the latest version and try again.

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:

  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 -

    When you run the command, the following error is safe to ignore:

    The object has been modified; please apply your changes to the latest version and try again.

Next steps

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

  • Last updated on