本页展示了如何配置密钥管理服务（Key Management Service，KMS）驱动和插件以启用 Secret 数据加密。 目前有两个 KMS API 版本。KMS v1 将继续工作，而 KMS v2 将开发得逐渐成熟。 如果你不确定要选用哪个 KMS API 版本，可选择 v1。

准备开始

你必须拥有一个 Kubernetes 的集群，同时你的 Kubernetes 集群必须带有 kubectl 命令行工具。 建议在至少有两个节点的集群上运行本教程，且这些节点不作为控制平面主机。 如果你还没有集群，你可以通过 Minikube 构建一个你自己的集群，或者你可以使用下面任意一个 Kubernetes 工具构建：

• Killercoda

• 玩转 Kubernetes

你所需要的 Kubernetes 版本取决于你已选择的 KMS API 版本。

• 如果你选择了 KMS API v1，所有受支持的 Kubernetes 版本都可以正常工作。

• 如果你选择了 KMS API v2，则应使用 Kubernetes v1.26 （如果你正在运行也支持 KMS API v2 的其他 Kubernetes 版本，需查阅该 Kubernetes 版本的文档）。要获知版本信息，请输入 kubectl version.

KMS v1

• 需要 Kubernetes 1.10.0 或更高版本

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

• 特性状态： Kubernetes v1.12 [beta]

KMS v2

• 需要 Kubernetes 1.25.0 或更高版本

• 设置 kube-apiserver 特性门控：--feature-gates=KMSv2=true 以配置 KMS v2 驱动

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

• 特性状态： Kubernetes v1.25 [alpha]

KMS 加密驱动使用封套加密模型来加密 etcd 中的数据。 数据使用数据加密密钥（DEK）加密；每次加密都生成一个新的 DEK。 这些 DEK 经一个密钥加密密钥（KEK）加密后在一个远端的 KMS 中存储和管理。 KMS 驱动使用 gRPC 与一个特定的 KMS 插件通信。这个 KMS 插件作为一个 gRPC 服务器被部署在 Kubernetes 控制平面的相同主机上，负责与远端 KMS 的通信。

配置 KMS 驱动

为了在 API 服务器上配置 KMS 驱动，在加密配置文件中的 providers 数组中加入一个类型为 kms 的驱动，并设置下列属性：

KMS 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、v1 或空值。任何其他值都将产生一个错误。） 必须设置为 v2 才能使用 KMS v2 API。

• name：KMS 插件的显示名称。一旦设置，就无法更改。

• endpoint：gRPC 服务器（KMS 插件）的监听地址。该端点是一个 UNIX 域套接字。

• cachesize：以明文缓存的数据加密密钥（DEK）的数量。一旦被缓存， 就可以直接使用 DEK 而无需另外调用 KMS；而未被缓存的 DEK 需要调用一次 KMS 才能解包。

• timeout：在返回一个错误之前，kube-apiserver 等待 kms-plugin 响应的时间（默认是 3 秒）。

参见理解静态配置加密

实现 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作为对过程调用 Version 的响应，兼容的 KMS 插件应把 v1beta1 作为 VersionResponse.version 版本返回。

• 消息版本：v1beta1所有来自 KMS 驱动的消息都把 version 字段设置为当前版本 v1beta1

• 协议：UNIX 域套接字 (unix)该插件被实现为一个在 UNIX 域套接字上侦听的 gRPC 服务器。 该插件部署时应在文件系统上创建一个文件来运行 gRPC UNIX 域套接字连接。 API 服务器（gRPC 客户端）配置了 KMS 驱动（gRPC 服务器）UNIX 域套接字端点，以便与其通信。 通过以 /@ 开头的端点，可以使用一个抽象的 Linux 套接字，即 unix:///@foo。 使用这种类型的套接字时必须小心，因为它们没有 ACL 的概念（与传统的基于文件的套接字不同）。 然而，这些套接字遵从 Linux 网络命名空间约束，因此只能由同一 Pod 中的容器进行访问，除非使用了主机网络。

KMS v2

• kms 插件版本：v2alpha1作为对过程调用 Status 的响应，兼容的 KMS 插件应把 v2alpha1 作为 StatusResponse.Version 版本、 “ok” 作为 StatusResponse.Healthz 并且 keyID（KMS KEK ID）作为 StatusResponse.KeyID 返回。

• 协议：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 插件

确保 KMS 插件与 Kubernetes 主服务器运行在同一主机上。

使用 KMS 驱动加密数据

为了加密数据：

1. 使用适合于 kms 驱动的属性创建一个新的 EncryptionConfiguration 文件，以加密 Secret 和 ConfigMap 等资源。 如果要加密使用 CustomResourceDefinition 定义的扩展 API，你的集群必须运行 Kubernetes v1.26 或更高版本。

1. 设置 kube-apiserver 的 --encryption-provider-config 参数指向配置文件的位置。

1. --encryption-provider-config-automatic-reload 布尔参数决定了磁盘内容发生变化时是否应自动重新加载 通过 --encryption-provider-config 设置的文件。这样可以在不重启 API 服务器的情况下进行密钥轮换。

1. 重启你的 API 服务器。

KMS v1

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:- resources:- secrets- configmaps- pandas.awesome.bears.exampleproviders:- kms:name: myKmsPluginFooendpoint: unix:///tmp/socketfile.sockcachesize:100timeout:3s- kms:name: myKmsPluginBarendpoint: unix:///tmp/socketfile.sockcachesize:100timeout:3s

KMS v2

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:- resources:- secrets- configmaps- pandas.awesome.bears.exampleproviders:- kms:apiVersion: v2name: myKmsPluginFooendpoint: unix:///tmp/socketfile.sockcachesize:100timeout:3s- kms:name: myKmsPluginBarendpoint: unix:///tmp/socketfile.sockcachesize:100timeout:3s

--encryption-provider-config-automatic-reload 设置为 true 会将所有健康检查集中到同一个健康检查端点。 只有 KMS v1 驱动正使用且加密配置未被自动重新加载时，才能进行独立的健康检查。

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

Single Healthcheck 意味着唯一的健康检查端点是 /healthz/kms-providers。

Individual Healthchecks 意味着每个 KMS 插件都有一个对应的健康检查端点， 并且这一端点基于插件在加密配置中的位置确定，例如 /healthz/kms-provider-0、/healthz/kms-provider-1 等。

这些健康检查端点路径是由服务器硬编码、生成并控制的。 Individual Healthchecks 的索引序号对应于 KMS 加密配置被处理的顺序。

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

有关 EncryptionConfiguration 格式的更多详细信息，请参阅 kube-apiserver 加密 API 参考 (v1).

验证数据已经加密

写入 etcd 时数据被加密。重启 kube-apiserver 后，所有新建或更新的 Secret 或在 EncryptionConfiguration 中配置的其他资源类型在存储时应该已被加密。 要验证这点，你可以用 etcdctl 命令行程序获取私密数据的内容。

1. 在默认的命名空间里创建一个名为 secret1 的 Secret：

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

1. 用 etcdctl 命令行，从 etcd 读取出 Secret：

ETCDCTL_API=3 etcdctl get /kubernetes.io/secrets/default/secret1 [...]|hexdump-C

Copy

其中 [...] 包含连接 etcd 服务器的额外参数。

3.验证对于 KMS v1，保存的 Secret 以 k8s:enc:kms:v1: 开头， 对于 KMS v2，保存的 Secret 以 k8s:enc:kms:v2: 开头，这表明 kms 驱动已经对结果数据加密。

4. 验证通过 API 获取的 Secret 已被正确解密：

kubectl describe secret secret1 -n default Secret 应包含 mykey: mydata。

确保所有 Secret 都已被加密

因为 Secret 是在写入时被加密的，所以在更新 Secret 时也会加密该内容。

下列命令读取所有 Secret 并更新它们以便应用服务器端加密。如果因为写入冲突导致错误发生， 请重试此命令。对较大的集群，你可能希望根据命名空间或脚本更新去细分 Secret 内容。

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

从本地加密驱动切换到 KMS 驱动

为了从本地加密驱动切换到 kms 驱动并重新加密所有 Secret 内容：

1. 在配置文件中加入 kms 驱动作为第一个条目，如下列样例所示

  apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:- resources:- secretsproviders:- kms:name : myKmsPluginendpoint: unix:///tmp/socketfile.sockcachesize:100- aescbc:keys:- name: key1secret:<BASE64ENCODEDSECRET>

2. 重启所有 kube-apiserver 进程。

3. 运行下列命令使用 kms 驱动强制重新加密所有 Secret。

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

禁用静态数据加密

要禁用静态数据加密：

1. 将 identity 驱动作为配置文件中的第一个条目：

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:- resources:- secretsproviders:- identity:{}- kms:name : myKmsPluginendpoint: unix:///tmp/socketfile.sockcachesize:100

2. 重启所有 kube-apiserver 进程。

3. 运行下列命令强制重新加密所有 Secret。

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