Use Vault as a Kubernetes KMS provider

Vault Kubernetes Key Management provides a Kubernetes KMS v2 plugin (not a Vault plugin) called vault-kube-kms.

Vault Kubernetes Key Management allows Kubernetes clusters to use Vault Enterprise for encryption at rest. The Kubernetes API server uses a DEK (data encryption key) seed to generate DEKs for encrypting and decrypting cluster data. The API server encrypts and decrypts the DEK seed by calling the vault-kube-kms process, rather than storing key encryption keys (KEKs) in the cluster.

The vault-kube-kms process runs on the Kubernetes control plane and exposes a KMS v2–compatible gRPC endpoint that the API server uses for envelope encryption.

The vault-kube-kms process can only run on Kubernetes clusters where you have permission to modify the EncryptionConfig and the kube-apiserver manifest.

How it works

When a Kubernetes cluster administrator enables KMS encryption on the cluster or when a Vault cluster administrator rotates the Transit key, the Kubernetes API server makes a gRPC call to the vault-kube-kms process to encrypt the DEK seed.

On startup, the Kubernetes API server calls the vault-kube-kms process to decrypt previously encrypted DEKs.

The vault-kube-kms process forwards encrypt and decrypt requests to your Vault server, which uses the Transit secrets engine plugin to perform encryption and decryption operations. The Kubernetes API server then encrypts resource data locally using single-use DEKs that it generates from the DEK seed. The API server stores the encrypted DEKs in etcd, while Vault retains cryptographic authority over KEK encryption.

Use cases

• Encrypt Kubernetes secrets at rest. Protect secrets stored in etcd with Vault-backed encryption without changing application code.

• Centralize key management and policies. Manage encryption keys and access policies in Vault, with centralized auditing and RBAC enforcement.

• Support key rotation workflows. Rotate keys in Vault while preserving the ability to decrypt existing data.

• Improve operational visibility. Inspect key usage, latency, and errors using Vault audit logs and Vault Kubernetes Key Management logs and metrics.

Supported kubernetes versions

IBM tests and verifies Vault against the following Kubernetes minor releases. IBM does not support Vault with other versions of Kubernetes, although the functionality may work.

• 1.35
• 1.34
• 1.33
• 1.32
• 1.31
• 1.30
• 1.29

Supported Kubernetes distributions

Vault Kubernetes Key Management is validated on the following Kubernetes distributions:

• Red Hat OpenShift
• Self-managed and managed Kubernetes distributions that allow cluster administrators to modify the EncryptionConfig and the kube-apiserver manifest.