Update the key vault mode for an Azure Kubernetes Service (AKS) cluster with Key Management Service (KMS) etcd encryption

This article shows you how to update the key vault mode from public to private or private to public for an Azure Kubernetes Service (AKS) cluster with Key Management Service (KMS) etcd encryption.

Prerequisites

An AKS cluster with KMS etcd encryption enabled. For more information, see Add Key Management Service (KMS) etcd encryption to an Azure Kubernetes Service (AKS) cluster.
Azure CLI version 2.39.0 or later. Find your version using the az --version command. If you need to install or upgrade, see Install the Azure CLI.

Update a key vault mode

Note

To change a different key vault with a different mode (whether public or private), you can run az aks update directly. To change the mode of an attached key vault, you must first turn off KMS, then turn it on again using the new key vault IDs.

Update from a public to a private key vault
Update from a private to a public key vault

Turn off KMS on the existing cluster and release the key vault 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
```
Warning

After you turn off KMS, the encryption key vault key is still needed. You can't delete or expire it.
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 -
```
Update the key vault from public to private using the az keyvault update command with the --public-network-access parameter set to Disabled.
```
az keyvault update --name $KEY_VAULT --resource-group $RESOURCE_GROUP --public-network-access Disabled
```

Turn on KMS with the updated private key vault using the az aks update command with the --azure-keyvault-kms-key-vault-network-access parameter set to Private.

az aks update \
     --name $CLUSTER_NAME \
     --resource-group $RESOURCE_GROUP  \
     --enable-azure-keyvault-kms \
     --azure-keyvault-kms-key-id $KEY_ID \
     --azure-keyvault-kms-key-vault-network-access "Private" \
     --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID

Turn off KMS on the existing cluster to release the key vault using the az aks update command.
```
az aks update --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --disable-azure-keyvault-kms
```
Warning

After you turn off KMS, the encryption key vault key is still needed. You can't delete or expire it.
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 -
```
Update the key vault from public to private using the az keyvault update command with the --public-network-access parameter set to Enabled.
```
az keyvault update --name $KEY_VAULT --resource-group $RESOURCE_GROUP --public-network-access Enabled
```

Turn on KMS with the updated private key vault using the az aks update command with the --azure-keyvault-kms-key-vault-network-access parameter set to Public.

az aks update \
     --name $CLUSTER_NAME \
     --resource-group $RESOURCE_GROUP  \
     --enable-azure-keyvault-kms \
     --azure-keyvault-kms-key-id $KEY_ID \
     --azure-keyvault-kms-key-vault-network-access "Public" \
     --azure-keyvault-kms-key-vault-resource-id $KEY_VAULT_RESOURCE_ID

Next steps

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

Last updated on 2025-10-30

Update the key vault mode for an Azure Kubernetes Service (AKS) cluster with Key Management Service (KMS) etcd encryption

Prerequisites

Update a key vault mode

Additional resources