Rotate the key encryption key

Beta feature

Beta functionality is stable but possibly incomplete and subject to change. We strongly discourage using beta features in production deployments of Vault.

You can rotate the KEK in Vault without restarting the vault-kube-kms process or the Kubernetes API server. During the rotation process, the vault-kube-kms process emits log entries indicating that it observed a new Transit key version along with the results of encryption operations using the new key version.

Consider minimum version updates carefully

Changing min_decryption_version for the Transit plugin can prevent Kubernetes from reading data encrypted with older key versions. Always ensure min_decryption_version includes the oldest key version currently in-use by your Kubernetes cluster.

To rotate the KEK, call the Transit rotate endpoint with the key name configured for the vault-kube-kms process:

$ vault write -f <mount_path>/keys/<key_name>/rotate

For example:

$ vault write -f k8s-transit/keys/kms-kek/rotate

Vault creates a new version of the key while retaining previous versions for decryption. Once you rotate the key in Vault:

The vault-kube-kms process automatically detects the new Transit key version.
Within a few minutes of rotation, the vault-kube-kms process updates the active key version used for encryption.
The Kubernetes API server encrypts the new DEK using the latest key version. Refer to the Kubernetes doc, Understanding key_id and Key Rotation for more details on the timing.
Existing encrypted DEKs remain decryptable using older key versions.