使用 KMS 提供商进行数据加密

此页面展示了如何配置密钥管理服务 (KMS) 提供程序和插件以启用机密数据加密。在 Kubernetes 1.30 中，有两种版本的 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 v2，您应该使用 Kubernetes v1.30（如果您正在运行也支持 v2 KMS API 的不同版本的 Kubernetes，请切换到该版本的 Kubernetes 文档）。
如果您选择了 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) 的数量。缓存后，DEK 可在不调用 KMS 的情况下使用；而未缓存的 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 属性。一旦服务器通过调用 KMS 解包了所有数据加密密钥 (DEK)，它们将以明文形式缓存。缓存后，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 之外的语言：使用 protoc 编译器和 proto 文件：api.proto 为特定语言生成存根文件

KMS v2

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

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

注意

KMS v1

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

KMS v2

KMS 插件版本：v2
响应 Status 远程过程调用，兼容的 KMS 插件应返回其 KMS 兼容性版本作为 StatusResponse.version。该状态响应还应包括 StatusResponse.healthz 中的“ok”以及 StatusResponse.key_id 中的 key_id（远程 KMS KEK ID）。Kubernetes 项目建议您使您的插件与稳定的 v2 KMS API 兼容。Kubernetes 1.30 还支持 v2beta1 API 用于 KMS；未来的 Kubernetes 版本可能会继续支持该测试版。
当一切正常时，API 服务器大约每分钟轮询一次 Status 过程调用，当插件不正常时，每 10 秒轮询一次。插件必须注意优化此调用，因为它将处于持续负载下。
加密
EncryptRequest 过程调用提供明文和用于记录目的的 UID。响应必须包括密文、用于 KEK 的 key_id 以及 KMS 插件在将来 DecryptRequest 调用中需要帮助的任何元数据（通过 annotations 字段）。插件必须保证任何不同的明文都会导致不同的响应 (ciphertext, key_id, annotations)。
如果插件返回一个非空的 annotations 映射，则所有映射键必须是完全限定的域名，例如 example.com。annotation 的一个示例用例是 {"kms.example.io/remote-kms-auditid":"<audit ID used by the remote KMS>"}
API 服务器不会以高频率执行 EncryptRequest 过程调用。插件实现仍应努力将每个请求的延迟保持在 100 毫秒以下。
解密
DecryptRequest 过程调用提供来自 EncryptRequest 的 (ciphertext, key_id, annotations) 以及用于记录目的的 UID。正如预期的那样，它是 EncryptRequest 调用的逆过程。插件必须验证 key_id 是否是它们理解的 - 它们不得尝试解密数据，除非它们确定它是在之前由它们加密的。
API 服务器可能会在启动时执行数千个 DecryptRequest 过程调用以填充其监视缓存。因此，插件实现必须尽快执行这些调用，并且应努力将每个请求的延迟保持在 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 轮换期间）。
插件不得重复使用 key_id，即使在先前使用的远程 KEK 已恢复的情况下也是如此。例如，如果插件使用 key_id=A，切换到 key_id=B，然后返回到 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)
插件作为 gRPC 服务器实现，监听 UNIX 域套接字。插件部署应在文件系统上创建一个文件以运行 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 文件，以加密诸如 Secrets 和 ConfigMaps 之类的资源。如果您想加密在 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 加密配置的顺序。

在执行确保所有密钥都已加密中定义的步骤之前，providers 列表应以 identity: {} 提供商结尾，以允许读取未加密的数据。一旦所有资源都被加密，就应该删除 identity 提供商，以防止 API 服务器认可未加密的数据。

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

验证数据是否已加密

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

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

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

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

确保所有密钥都已加密

当正确配置了静止数据加密时，资源会在写入时被加密。因此，我们可以执行一次就地无操作更新，以确保数据已加密。

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

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

从本地加密提供商切换到 KMS 提供商

要从本地加密提供商切换到 kms 提供商并重新加密所有密钥

将 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 提供商重新加密所有密钥。
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```

下一步

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

上次修改时间：2024 年 5 月 16 日下午 2:58 PST：修复示例 KMS 配置文档 (81e6c94293)

使用 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

验证数据是否已加密

确保所有密钥都已加密

从本地加密提供商切换到 KMS 提供商

下一步

反馈