Container Service for Kubernetes:Use KMS to encrypt Kubernetes Secrets

Prerequisites

Ensure that you have:

• A KMS key in the same region as your ACK Pro cluster. Supported types: default, software-protected, and hardware-protected. See Getting started with keys and Billing.

• Authorization to enable Secret encryption:

  • Alibaba Cloud account: authorized to assume AliyunCSManagedSecurityRole. The ACK console prompts for authorization when you enable Secret encryption, or go to the Cloud Resource Access Authorization page directly.

  • RAM user or RAM role: must have both:

    • Administrator or O&M engineer RBAC permissions on the ACK Pro cluster. See Grant RBAC permissions to RAM users or RAM roles.

    • Granted the AliyunKMSCryptoAdminAccess system permission. See Grant permissions to a RAM user or RAM role.

Limitations

• Secret encryption is supported only on ACK Pro clusters and ACK Serverless Pro clusters.

• After enabling Secret encryption, do not disable or delete the key via the KMS API or console. If the key becomes unavailable, the API server cannot retrieve Secrets or service account objects, causing service interruptions.

• To disable Secret encryption, turn off Secret Encryption in the cluster's Basic Information tab.

How it works

ACK uses the Kubernetes KMS provider with envelope encryption to protect Secrets in etcd. The Secret is encrypted with a data encryption key (DEK), and the DEK is encrypted with a key encryption key (KEK) in KMS. The plaintext DEK is never stored alongside the data it protects.

Encryption:

1. When you store a Secret, the API server generates a random DEK and encrypts the Secret with it.

2. The API server sends the DEK to KMS, which encrypts it with your KMS key (the KEK) and returns the encrypted DEK.

3. The API server stores both the encrypted Secret and the encrypted DEK in etcd.

Decryption:

1. The API server calls the KMS Decrypt operation to decrypt the DEK.

2. The API server uses the plaintext DEK to decrypt the Secret and returns it to the caller.

For more information, see the KMS encryption provider and Use envelope encryption.

KMS v2

Starting with Kubernetes 1.31, ACK Pro clusters and use the community KMS v2 interface for encryption at rest. KMS v2 supports more Secret instances in a cluster and provides better encryption and decryption performance. For more information about the KMS v2 encryption and decryption flow, see KMS v2.

To upgrade from the KMS v1 interface to the KMS v2 interface, see How to upgrade to KMS v2 for Secret encryption at rest?

Enable encryption at rest for Secrets

Rotate the encryption key

KMS automatic key rotation encrypts new Secrets with the rotated key. Existing Secrets remain encrypted with the original key until you explicitly re-encrypt them.

• Manual re-encryption: After rotation completes, re-encrypt all existing Secrets with the new key:

kubectl get secrets --all-namespaces -o json | kubectl annotate --overwrite -f - encryption-key-rotation-time="$(date -u +'%Y-%m-%dT%H:%M:%S%z')"

See Configure key rotation for automatic key rotation setup.

FAQ

{
    "Action": [
        "cs:UpdateKMSEncryption"
    ],
    "Effect": "Deny",
    "Resource": [
        "*"
    ]
}