diff --git a/content/zh-cn/docs/tasks/administer-cluster/kms-provider.md b/content/zh-cn/docs/tasks/administer-cluster/kms-provider.md index 9f3660c548..c814c75858 100644 --- a/content/zh-cn/docs/tasks/administer-cluster/kms-provider.md +++ b/content/zh-cn/docs/tasks/administer-cluster/kms-provider.md @@ -15,14 +15,16 @@ weight: 370 本页展示了如何配置密钥管理服务(Key Management Service,KMS)驱动和插件以启用 Secret 数据加密。 -目前有两个 KMS API 版本。如果是只需要支持 Kubernetes v1.27+ 的新场景,应使用 KMS v2, -因为 KMS v2 相比 KMS v1 具有显著更佳的性能特征。 -(请注意,下文的“注意”部分说明了不得使用 KMS v2 的特殊场景。) +在 Kubernetes {{< skew currentVersion >}} 中,存在两个版本的 KMS 静态加密方式。 +如果可行的话,建议使用 KMS v2,因为(自 Kubernetes v1.28 起)KMS v1 已经被弃用。 +然而,在某些特殊情况下没办法使用 KMS v2,你应阅读和关注本页中强调的 **注意** 事项。 +KMS v2 提供了比 KMS v1 明显更好的性能特征。 ## {{% heading "prerequisites" %}} @@ -30,24 +32,29 @@ should use KMS v2 as it offers significantly better performance characteristics -你所需要的 Kubernetes 版本取决于你已选择的 KMS API 版本。 +你所需要的 Kubernetes 版本取决于你已选择的 KMS API 版本。Kubernetes 推荐使用 KMS v2。 -- 如果你选择了 KMS API v1,所有受支持的 Kubernetes 版本都可以正常工作。 - 如果你选择了 KMS API v2,则应使用 Kubernetes v{{< skew currentVersion >}} (如果你正在运行也支持 KMS API v2 的其他 Kubernetes 版本,需查阅该 Kubernetes 版本的文档)。 +- 如果你选择了 KMS API v1 来支持早于 v1.27 版本的集群,或者你有一个仅支持 KMS v1 的旧版 KMS 插件, + 那么任何受支持的 Kubernetes 版本都可以良好工作。此 API 自 Kubernetes v1.28 起被弃用。 + Kubernetes 不推荐使用此 API。 {{< version-check >}} ### KMS v1 -{{< feature-state for_k8s_version="v1.12" state="beta" >}} +{{< feature-state for_k8s_version="v1.28" state="deprecated" >}} * 对于 Kubernetes 1.25 和 1.26 版本,需要通过 kube-apiserver 特性门控启用此特性。 设置 `--feature-gates=KMSv2=true` 以配置 KMS v2 驱动。 + 对于所有 API 服务器正在运行 1.28 或更高的版本并且你不需要降级到 Kubernetes v1.27 的环境, + 你可以启用 `KMSv2KDF` 特性门控(Beta 特性)以生成更稳健的数据加密密钥。 + 如果这些前提条件均已满足,则 Kubernetes 项目建议启用 KMS v2 + 密钥派生函数(Key Derivation Function, KDF)。 * 你的集群必须使用 etcd v3 或更高版本。 @@ -80,6 +95,15 @@ enabled will result in data loss. --> KMS v2 API 和实现在 v1.25 的 Alpha 版本和 v1.27 的 Beta 版本之间以不兼容的方式进行了更改。 如果尝试从启用了 Alpha 特性的旧版本进行升级将导致数据丢失。 + +--- + + +不支持在启用 `KMSv2KDF` 特性门控的情况下运行一些服务器为 v1.27 而另一些服务器为 v1.28 的混合 API 服务器版本, +这可能导致数据丢失。 {{< /caution >}} @@ -88,31 +112,58 @@ KMS v2 API 和实现在 v1.25 的 Alpha 版本和 v1.27 的 Beta 版本之间以 The KMS encryption provider uses an envelope encryption scheme to encrypt data in etcd. The data is encrypted using a data encryption key (DEK). The DEKs are encrypted with a key encryption key (KEK) that is stored and managed in a remote KMS. + With KMS v1, a new DEK is generated for each encryption. -With KMS v2, a new DEK is generated on server startup and when the KMS plugin informs the API server -that a KEK rotation has occurred (see `Understanding key_id and Key Rotation` section below). +--> +KMS 加密驱动使用封套加密模型来加密 etcd 中的数据。数据使用数据加密密钥(DEK)加密。 +这些 DEK 经一个密钥加密密钥(KEK)加密后在一个远端的 KMS 中存储和管理。 + +对于 KMS v1,每次加密将生成新的 DEK。 + + +对于 KMS v2,API 服务器生成 DEK 有两种方式。 +Kubernetes 默认在 API 服务器启动时生成一个新的 DEK(数据加密密钥), +然后重复使用该密钥进行资源加密。然而,如果你使用 KMS v2 并且启用了 `KMSv2KDF` +[特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/), +则 Kubernetes 将转为为每次加密生成一个新的 DEK:API 服务器使用**密钥派生函数**根据 +秘密的种子数结合一些随机数据生成一次性的数据加密密钥。 +无论你配置哪种方法,DEK 或种子也会在 KEK 轮换时进行轮换 +(有关更多详细信息,请参阅下面的“了解 key_id 和密钥轮换”章节)。 + + -KMS 加密驱动使用封套加密模型来加密 etcd 中的数据。数据使用数据加密密钥(DEK)加密。 -这些 DEK 经一个密钥加密密钥(KEK)加密后在一个远端的 KMS 中存储和管理。 -对于 KMS v1,每次加密将生成新的 DEK。对于 KMS v2,在服务器启动和 KMS 插件通知 API -服务器已出现 KEK 轮换时生成新的 DEK。(参见以下“了解 key_id 和密钥轮换”章节)。 KMS 驱动使用 gRPC 通过 UNIX 域套接字与一个特定的 KMS 插件通信。 这个 KMS 插件作为一个 gRPC 服务器被部署在 Kubernetes 控制平面的相同主机上,负责与远端 KMS 的通信。 {{< caution >}} -如果你正在运行基于虚拟机 (VM) 的节点并利用此特性使用 VM 状态存储,则不得使用 KMS v2。 +如果你正在运行基于虚机的节点并使用虚机状态存储支持本特性,则使用 KMS v2 是**不安全的**, +且存在信息安全风险,除非你还显式启用了 `KMSv2KDF` +[特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)。 使用 KMS v2 时,API 服务器使用带有 12 字节随机数(8 字节原子计数器和 4 字节随机数据) -的 AES-GCM 进行加密。如果保存并恢复 VM,则可能会出现以下问题: +的 AES-GCM 进行加密。如果保存并恢复虚机,则可能会出现以下问题: -1. 如果 VM 在不一致的状态下保存或恢复不当,则可能会丢失或损坏计数器值。 +1. 如果虚机在不一致的状态下保存或恢复不当,则可能会丢失或损坏计数器值。 这可能导致相同的计数器值被用了两次,从而造成两个不同的消息使用相同的随机数。 -2. 如果将 VM 还原到先前的状态,则计数器值可能会被设置回其先前的值,导致再次使用相同的随机数。 +2. 如果将虚机还原到先前的状态,则计数器值可能会被设置回其先前的值,导致再次使用相同的随机数。 尽管这两种情况都通过 4 字节随机数进行了部分缓解,但这可能会损害加密的安全性。 + + +如果你已启用了 `KMSv2KDF` +[特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/) +并且正在使用 KMS v2(而不是 KMS v1),API 服务器会根据秘密的种子数生成一次性的数据加密密钥。 +这就不再需要使用基于计数器的随机数 (nonce),同时避免了随机数冲突问题。 +这样还消除了使用 KMS v2 和虚机状态存储的特定问题。 {{< /caution >}} ## 实现 KMS 插件 {#implementing-a-kms-plugin} 为实现一个 KMS 插件,你可以开发一个新的插件 gRPC 服务器或启用一个由你的云服务驱动提供的 KMS 插件。 -你可以将这个插件与远程 KMS 集成,并把它部署到 Kubernetes 的主服务器上。 +你可以将这个插件与远程 KMS 集成,并把它部署到 Kubernetes 控制平面上。 - 因为你未控制使用 DEK 执行的写入次数,所以建议至少每 90 天轮换一次 KEK。 + 因为你未控制使用 DEK 执行的写入次数,所以 Kubernetes 项目建议至少每 90 天轮换一次 KEK。 {{< /caution >}} ### 部署 KMS 插件 {#deploying-the-kms-plugin} -确保 KMS 插件与 Kubernetes 主服务器运行在同一主机上。 +确保 KMS 插件与 Kubernetes API 服务器运行在同一主机上。