使用 KMS 提供程序进行数据加密

此页面介绍如何配置密钥管理服务 (KMS) 提供程序和插件以启用机密数据加密。在 Kubernetes 1.35 中，有两种版本的 KMS 静态加密。如果可行，您应该使用 KMS v2，因为 KMS v1 已弃用（自 Kubernetes v1.28 起）并且默认禁用（自 Kubernetes v1.29 起）。KMS v2 比 KMS v1 具有显著更好的性能特征。

注意

此文档适用于 KMS v2 的通用可用实现（以及已弃用的版本 1 实现）。如果您正在使用任何早于 Kubernetes v1.29 的控制平面组件，请检查集群正在运行的 Kubernetes 版本的文档中的相应页面。Kubernetes 的早期版本具有不同的行为，这些行为可能与信息安全相关。

开始之前

您需要一个 Kubernetes 集群，并且 kubectl 命令行工具必须配置为与您的集群通信。建议在至少具有两个非控制平面主机的集群上运行此教程。如果您还没有集群，可以使用 minikube 创建一个，或者可以使用以下 Kubernetes 游乐场之一

您需要的 Kubernetes 版本取决于您选择的 KMS API 版本。Kubernetes 建议使用 KMS v2。

如果您选择 KMS API v1 以支持版本早于 v1.27 的集群，或者您有一个仅支持 KMS v1 的遗留 KMS 插件，那么任何受支持的 Kubernetes 版本都可以工作。此 API 自 Kubernetes v1.28 起已弃用。Kubernetes 不建议使用此 API。

要检查版本，请输入 kubectl version。

KMS v1

功能状态： Kubernetes v1.28 [已弃用]

需要 Kubernetes 版本 1.10.0 或更高版本
对于版本 1.29 及更高版本，KMS 的 v1 实现默认禁用。要启用该功能，请将 --feature-gates=KMSv1=true 设置为配置 KMS v1 提供程序。
您的集群必须使用 etcd v3 或更高版本

KMS v2

功能状态： Kubernetes v1.29 [稳定]

您的集群必须使用 etcd v3 或更高版本

KMS 加密和每对象加密密钥

KMS 加密提供程序使用信封加密方案来加密 etcd 中的数据。数据使用数据加密密钥 (DEK) 进行加密。DEK 使用存储并在远程 KMS 中管理的密钥加密密钥 (KEK) 进行加密。

如果您使用（已弃用）KMS 的 v1 实现，则每次加密都会生成一个新的 DEK。

使用 KMS v2，每个加密都会生成一个新的 DEK：API 服务器使用密钥派生函数从与一些随机数据组合的秘密种子生成一次性数据加密密钥。每当 KEK 旋转时，种子都会旋转（有关更多详细信息，请参阅下面的了解 key_id 和密钥轮换部分）。

KMS 提供程序使用 gRPC 通过 UNIX 域套接字与特定的 KMS 插件进行通信。KMS 插件作为 gRPC 服务器实现，并部署在与 Kubernetes 控制平面相同的宿主机上，负责与远程 KMS 的所有通信。

配置 KMS 提供程序

要在 API 服务器上配置 KMS 提供程序，请在加密配置文件中的 providers 数组中包含一个类型为 kms 的提供程序，并设置以下属性

KMS v1

apiVersion: KMS 提供程序的 API 版本。将此值保留为空或设置为 v1。
name: KMS 插件的显示名称。设置后无法更改。
endpoint: gRPC 服务器（KMS 插件）的侦听地址。端点是一个 UNIX 域套接字。
cachesize: 要以明文缓存的数据加密密钥 (DEK) 的数量。缓存后，可以在无需再次调用 KMS 的情况下使用 DEK；而未缓存的 DEK 需要调用 KMS 才能解包。
timeout: kube-apiserver 在返回错误之前等待 kms-plugin 响应多长时间（默认值为 3 秒）。

KMS v2

apiVersion: KMS 提供程序的 API 版本。将其设置为 v2。
name: KMS 插件的显示名称。设置后无法更改。
endpoint: gRPC 服务器（KMS 插件）的侦听地址。端点是一个 UNIX 域套接字。
timeout: kube-apiserver 在返回错误之前等待 kms-plugin 响应多长时间（默认值为 3 秒）。

KMS v2 不支持 cachesize 属性。所有数据加密密钥 (DEK) 在服务器解包它们并通过调用 KMS 后都将以明文缓存。缓存后，可以使用 DEK 无限制地执行解密，而无需调用 KMS。

请参阅了解静态加密配置。

实现 KMS 插件

要实现 KMS 插件，您可以开发一个新的插件 gRPC 服务器，或者启用云提供程序已经提供的 KMS 插件。然后，您将插件与远程 KMS 集成，并将其部署在 Kubernetes 控制平面上。

启用云提供程序支持的 KMS

请参阅您的云提供程序，以获取有关启用云提供程序特定的 KMS 插件的说明。

开发 KMS 插件 gRPC 服务器

您可以使用 Go 提供的存根文件来开发 KMS 插件 gRPC 服务器。对于其他语言，您可以使用 proto 文件来创建可用于开发 gRPC 服务器代码的存根文件。

KMS v1

使用 Go：使用存根文件中的函数和数据结构：api.pb.go 来开发 gRPC 服务器代码
使用 Go 以外的语言：使用 proto 编译器和 proto 文件：api.proto 为特定语言生成存根文件

KMS v2

使用 Go：提供了一个高级库以简化该过程。低级实现可以使用存根文件中的函数和数据结构：api.pb.go 来开发 gRPC 服务器代码
使用 Go 以外的语言：使用 proto 编译器和 proto 文件：api.proto 为特定语言生成存根文件

然后使用存根文件中的函数和数据结构来开发服务器代码。

备注

KMS v1

kms 插件版本：v1beta1
作为对过程调用的响应，兼容的 KMS 插件应将 v1beta1 作为 VersionResponse.version 返回。
message version: v1beta1
所有来自 KMS 提供程序的消息都将版本字段设置为 v1beta1。
协议：UNIX 域套接字 (unix)
插件作为侦听 UNIX 域套接字的 gRPC 服务器实现。插件部署应在文件系统上创建一个文件以运行 gRPC unix 域套接字连接。API 服务器（gRPC 客户端）配置为使用 KMS 提供程序（gRPC 服务器）unix 域套接字端点进行通信。可以通过从 /@ 开始来使用抽象 Linux 套接字，即 unix:///@foo。在使用这种类型的套接字时必须小心，因为它们没有 ACL 的概念（与基于文件的传统套接字不同）。但是，它们受 Linux 网络命名空间的约束，因此除非使用主机网络，否则只能被同一 Pod 内的容器访问。

KMS v2

KMS 插件版本：v2
作为对 Status 远程过程调用的响应，兼容的 KMS 插件应将其 KMS 兼容性版本作为 StatusResponse.version 返回。该状态响应还应包含 key_id（远程 KMS KEK ID）作为 StatusResponse.key_id 以及“ok”作为 StatusResponse.healthz。Kubernetes 项目建议您使您的插件与稳定的 v2 KMS API 兼容。Kubernetes 1.35 还支持 KMS 的 v2beta1 API；未来的 Kubernetes 版本可能会继续支持该 beta 版本。
API 服务器在一切正常时大约每分钟轮询一次 Status 过程调用，并在插件不正常时每 10 秒轮询一次。插件必须注意优化此调用，因为它将承受持续的负载。
加密
EncryptRequest过程调用提供明文和一个 UID 用于日志记录。响应必须包含密文、用于 KEK 的 key_id，以及 KMS 插件可能需要用于辅助未来 DecryptRequest 调用（通过 annotations 字段）的任何元数据（可选）。插件必须保证任何不同的明文都会产生不同的响应 (ciphertext, key_id, annotations)。
如果插件返回一个非空的 annotations map，所有 map 键必须是完全限定域名，例如 example.com。annotation 的一个示例用例是 {"kms.example.io/remote-kms-auditid":"<远程 KMS 使用的审计 ID>"}
API 服务器不会以高频率执行 EncryptRequest 过程调用。插件实现仍然应力求将每个请求的延迟保持在 100 毫秒以下。
解密
DecryptRequest 过程调用提供来自 EncryptRequest 的 (ciphertext, key_id, annotations) 和一个 UID 用于日志记录。正如预期的那样，它是 EncryptRequest 调用的反向操作。插件必须验证 key_id 是它们理解的 - 它们不得尝试解密数据，除非它们确定数据是由它们在之前的时间加密的。
API 服务器可能在启动时执行数千个 DecryptRequest 过程调用以填充其 watch 缓存。因此，插件实现必须尽快执行这些调用，并应力求将每个请求的延迟保持在 10 毫秒以下。
理解 key_id 和密钥轮换
key_id 是当前正在使用的远程 KMS KEK 的公共、非秘密名称。它可能在 API 服务器的正常操作期间被记录，因此不得包含任何私有数据。鼓励插件实现使用哈希值以避免泄露任何数据。KMS v2 指标会在通过 /metrics 端点公开之前对该值进行哈希处理。
API 服务器认为从 Status 过程调用返回的 key_id 是权威的。因此，此值的更改向 API 服务器发出信号，表明远程 KEK 已更改，并且使用旧 KEK 加密的数据在执行无操作写入时应标记为陈旧（如下所述）。如果 EncryptRequest 过程调用返回的 key_id 与 Status 不同，则响应将被丢弃，并且插件被认为不正常。因此，实现必须保证从 Status 返回的 key_id 将与 EncryptRequest 返回的 key_id 相同。此外，插件必须确保 key_id 是稳定的，并且不会在值之间翻转（例如，在远程 KEK 轮换期间）。
即使在先前使用的远程 KEK 已恢复的情况下，插件不得重新使用 key_id。例如，如果插件正在使用 key_id=A，切换到 key_id=B，然后返回到 key_id=A - 而不是报告 key_id=A，插件应报告一些派生值，例如 key_id=A_001 或使用新值，例如 key_id=C。
由于 API 服务器大约每分钟轮询一次 Status，因此 key_id 轮换并非立即生效。此外，API 服务器将在最后一个有效状态下运行大约三分钟。因此，如果用户希望采取被动方法进行存储迁移（即等待），他们必须安排迁移在远程 KEK 轮换后的 3 + N + M 分钟发生（N 是插件观察到 key_id 更改所需的时间，而 M 是允许处理配置更改的所需缓冲 - 建议至少 M 为五分钟）。请注意，执行 KEK 轮换不需要重新启动 API 服务器。
注意
由于您无法控制使用 DEK 执行的写入次数，Kubernetes 项目建议至少每 90 天轮换一次 KEK。
协议：UNIX 域套接字 (unix)
插件作为侦听 UNIX 域套接字的 gRPC 服务器实现。插件部署应在文件系统上创建一个文件以运行 gRPC unix 域套接字连接。API 服务器（gRPC 客户端）配置为使用 KMS 提供程序（gRPC 服务器）unix 域套接字端点进行通信。可以通过从 /@ 开始来使用抽象 Linux 套接字，即 unix:///@foo。在使用这种类型的套接字时必须小心，因为它们没有 ACL 的概念（与基于文件的传统套接字不同）。但是，它们受 Linux 网络命名空间的约束，因此除非使用主机网络，否则只能被同一 Pod 内的容器访问。

将 KMS 插件与远程 KMS 集成

KMS 插件可以使用 KMS 支持的任何协议与远程 KMS 进行通信。所有配置数据，包括 KMS 插件用于与远程 KMS 通信的身份验证凭据，都由 KMS 插件独立存储和管理。KMS 插件可以对密文进行编码，添加在发送到 KMS 进行解密之前可能需要的其他元数据（KMS v2 通过提供专用的 annotations 字段使此过程更容易）。

部署 KMS 插件

确保 KMS 插件在与 Kubernetes API 服务器相同的宿主机上运行。

使用 KMS 提供程序加密您的数据

加密数据

使用适用于 kms 提供程序的适当属性创建新的 EncryptionConfiguration 文件，以加密 Secret 和 ConfigMap 等资源。如果您想加密在 CustomResourceDefinition 中定义的扩展 API，您的集群必须运行 Kubernetes v1.26 或更高版本。
在 kube-apiserver 上设置 --encryption-provider-config 标志，以指向配置文件的位置。
--encryption-provider-config-automatic-reload 布尔参数确定由 --encryption-provider-config 设置的文件是否应该在磁盘内容更改时自动重新加载。
重新启动您的 API 服务器。

KMS v1

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources:
      - secrets
      - configmaps
      - pandas.awesome.bears.example
    providers:
      - kms:
          name: myKmsPluginFoo
          endpoint: unix:///tmp/socketfile-foo.sock
          cachesize: 100
          timeout: 3s
      - kms:
          name: myKmsPluginBar
          endpoint: unix:///tmp/socketfile-bar.sock
          cachesize: 100
          timeout: 3s

KMS v2

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources:
      - secrets
      - configmaps
      - pandas.awesome.bears.example
    providers:
      - kms:
          apiVersion: v2
          name: myKmsPluginFoo
          endpoint: unix:///tmp/socketfile-foo.sock
          timeout: 3s
      - kms:
          apiVersion: v2
          name: myKmsPluginBar
          endpoint: unix:///tmp/socketfile-bar.sock
          timeout: 3s

将 --encryption-provider-config-automatic-reload 设置为 true 会将所有健康检查折叠为单个健康检查端点。只有在使用 KMS v1 提供程序且未自动重新加载加密配置时，才能使用单独的健康检查。

下表总结了每个 KMS 版本的健康检查端点

KMS 配置	不带自动重新加载	带自动重新加载
仅 KMS v1	单独的健康检查	单个健康检查
仅 KMS v2	单个健康检查	单个健康检查
KMS v1 和 v2	单独的健康检查	单个健康检查
无 KMS	无	单个健康检查

单个健康检查 表示唯一的健康检查端点是 /healthz/kms-providers。

单独的健康检查 表示每个 KMS 插件都有一个与其在加密配置中的位置相关的健康检查端点：/healthz/kms-provider-0、/healthz/kms-provider-1 等。

这些健康检查端点路径是硬编码的，并由服务器生成/控制。单独健康检查的索引对应于加密配置中处理 KMS 的顺序。

在执行确保所有 Secret 都已加密中定义的步骤之前，providers 列表应以 identity: {} 提供程序结尾，以允许读取未加密的数据。加密所有资源后，应删除 identity 提供程序，以防止 API 服务器接受未加密的数据。

有关 EncryptionConfiguration 格式的详细信息，请查看 API 服务器加密 API 参考。

验证数据是否已加密

正确配置静态加密后，资源会在写入时被加密。重新启动 kube-apiserver 后，在 EncryptionConfiguration 中配置的任何新创建或更新的 Secret 或其他资源类型在存储时都应加密。要进行验证，可以使用 etcdctl 命令行程序检索 Secret 数据的內容。

在 default 命名空间中创建一个名为 secret1 的新 Secret

kubectl create secret generic secret1 -n default --from-literal=mykey=mydata

使用 etcdctl 命令行，从 etcd 中读取该 Secret
```
ETCDCTL_API=3 etcdctl get /kubernetes.io/secrets/default/secret1 [...] | hexdump -C
```
其中 [...] 包含连接到 etcd 服务器的附加参数。
验证存储的 Secret 是否以 k8s:enc:kms:v1:（对于 KMS v1）或 k8s:enc:kms:v2:（对于 KMS v2）为前缀，这表示 kms 提供程序已加密结果数据。
验证通过 API 检索时 Secret 是否已正确解密
```
kubectl describe secret secret1 -n default
```
Secret 应包含 mykey: mydata

确保所有 Secret 都已加密

正确配置静态加密后，资源会在写入时被加密。因此，我们可以执行原地无操作更新以确保数据已加密。

以下命令读取所有 Secret，然后更新它们以应用服务器端加密。如果由于冲突写入而发生错误，请重试该命令。对于更大的集群，您可能希望按命名空间细分 Secret 或编写更新脚本。

kubectl get secrets --all-namespaces -o json | kubectl replace -f -

从本地加密提供程序切换到 KMS 提供程序

要从本地加密提供程序切换到 kms 提供程序并重新加密所有 Secret

将 kms 提供程序作为配置文件中的第一个条目，如以下示例所示。

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources:
      - secrets
    providers:
      - kms:
          apiVersion: v2
          name : myKmsPlugin
          endpoint: unix:///tmp/socketfile.sock
      - aescbc:
          keys:
            - name: key1
              secret: <BASE 64 ENCODED SECRET>

重新启动所有 kube-apiserver 进程。
运行以下命令以强制使用 kms 提供程序重新加密所有 Secret。
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```

接下来

如果您不再希望对 Kubernetes API 中持久化的数据使用加密，请阅读解密已存储的静态数据。

最后修改时间：2025 年 5 月 9 日下午 12:28 PST：同步加密文档评审人员与 kubernetes sig-auth-encryption-at-rest-reviewers (4e42436cf9)

使用 KMS 提供程序进行数据加密

注意

开始之前

KMS v1

KMS v2

KMS 加密和每对象加密密钥

配置 KMS 提供程序

KMS v1

KMS v2

实现 KMS 插件

启用云提供程序支持的 KMS

开发 KMS 插件 gRPC 服务器

KMS v1

KMS v2

备注

KMS v1

KMS v2

注意

将 KMS 插件与远程 KMS 集成

部署 KMS 插件

使用 KMS 提供程序加密您的数据

KMS v1

KMS v2

验证数据是否已加密

确保所有 Secret 都已加密

从本地加密提供程序切换到 KMS 提供程序

接下来

反馈