diff --git a/content/zh-cn/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md b/content/zh-cn/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md index e1a04e859e..7e22bc1b34 100644 --- a/content/zh-cn/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md +++ b/content/zh-cn/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md @@ -1,14 +1,14 @@ --- title: 使用 kubeadm 进行证书管理 content_type: task -weight: 10 +weight: 80 --- @@ -23,13 +23,30 @@ to kubeadm certificate management. 由 [kubeadm](/zh-cn/docs/reference/setup-tools/kubeadm/) 生成的客户端证书在 1 年后到期。 本页说明如何使用 kubeadm 管理证书续订,同时也涵盖其他与 kubeadm 证书管理相关的说明。 + +Kubernetes 项目建议及时升级到最新的补丁版本,并确保你正在运行受支持的 Kubernetes 次要版本。 +遵循这一建议有助于你确保安全。 + ## {{% heading "prerequisites" %}} 你应该熟悉 [Kubernetes 中的 PKI 证书和要求](/zh-cn/docs/setup/best-practices/certificates/)。 +本指南将介绍如何使用 `openssl` 命令(用于手动证书签名),但你可以使用你喜欢的工具。 + +这里的一些步骤使用 `sudo` 来获取管理员访问权限。你可以使用任何等效的工具。 + - ## 使用自定义的证书 {#custom-certificates} 默认情况下,kubeadm 会生成运行一个集群所需的全部证书。 @@ -71,7 +87,6 @@ If all other certificates and kubeconfig files are in place, kubeadm recognizes this condition and activates the "External CA" mode. kubeadm will proceed without the CA key on disk. --> - ## 外部 CA 模式 {#external-ca-mode} 只提供了 `ca.crt` 文件但是不提供 `ca.key` 文件也是可以的 @@ -95,12 +110,17 @@ There are various ways to prepare the component credentials when using external [PKI certificates and requirements](/docs/setup/best-practices/certificates/) includes information on how to prepare all the required by kubeadm component credentials manually. + +This guide covers the usage of the `openssl` command (used for manual certificate signing, +if you choose that approach), but you can use your preferred tools. --> -### 手动准备组件证书 +### 手动准备组件证书 {#manual-preparation-of-component-credentials} [PKI 证书和要求](/zh-cn/docs/setup/best-practices/certificates/)包含有关如何手动准备 kubeadm 组件证书所需的所有信息。 +本指南将介绍如何使用 `openssl` 命令(用于手动证书签名),但你可以使用你喜欢的工具。 + -### 通过签署 kubeadm 生成的 CSR 来准备证书 +### 通过签署 kubeadm 生成的 CSR 来准备证书 {#preparation-of-credentials-by-signing-csrs-generated-by-kubeadm} kubeadm 可以[生成 CSR 文件](#signing-csr),你可以使用 `openssl` 和外部 CA 等工具手动签署这些文件。 这些 CSR 文件将包含 kubeadm 部署的组件所需的所有证书规范。 @@ -118,7 +138,7 @@ kubeadm 可以[生成 CSR 文件](#signing-csr),你可以使用 `openssl` 和 Alternatively, it is possible to use kubeadm phase commands to automate this process. --> -### 使用 kubeadm 阶段自动准备组件证书 +### 使用 kubeadm 阶段自动准备组件证书 {#automated-preparation-of-component-credentials-by-using-kubeadm-phases} 或者,可以使用 kubeadm 阶段命令来自动化此过程。 @@ -170,13 +190,21 @@ and its `pki` sub directory. kubeadm 将使用 `/etc/kubernetes/` 及其 `pki` 子目录下现有的 kubeconfig 和证书文件。 +## 证书过期和管理 {#check-certificate-expiration} +{{< note >}} + +`kubeadm` 不能管理由外部 CA 签名的证书。 +{{< /note >}} + + -## 检查证书是否过期 {#check-certificate-expiration} - -你可以使用 `check-expiration` 子命令来检查证书何时过期 +你可以使用 `check-expiration` 子命令来检查证书何时过期: ```shell kubeadm certs check-expiration @@ -222,38 +250,30 @@ user should take care of managing certificate renewal manually/using other tools 另外,kubeadm 会通知用户证书是否由外部管理; 在这种情况下,用户应该小心的手动/使用其他工具来管理证书更新。 -{{< warning >}} -`kubeadm` 不能管理由外部 CA 签名的证书。 -{{< /warning >}} - -{{< note >}} - -上面的列表中没有包含 `kubelet.conf`,因为 kubeadm 将 kubelet +上面的列表中没有包含 `kubelet.conf` 配置文件,因为 kubeadm 将 kubelet 配置为[自动更新证书](/zh-cn/docs/tasks/tls/certificate-rotation/)。 轮换的证书位于目录 `/var/lib/kubelet/pki`。 要修复过期的 kubelet 客户端证书,请参阅 [kubelet 客户端证书轮换失败](/zh-cn/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm/#kubelet-client-cert)。 -{{< /note >}} -{{< warning >}} +{{< note >}} -在通过 `kubeadm init` 创建的节点上,在 kubeadm 1.17 -版本之前有一个[缺陷](https://github.com/kubernetes/kubeadm/issues/1753), +在通过 kubeadm 1.17 之前的版本以 `kubeadm init` 创建的节点上, +有一个[缺陷](https://github.com/kubernetes/kubeadm/issues/1753), 该缺陷使得你必须手动修改 `kubelet.conf` 文件的内容。 `kubeadm init` 操作结束之后,你必须更新 `kubelet.conf` 文件将 `client-certificate-data` 和 `client-key-data` 改为如下所示的内容以便使用轮换后的 kubelet 客户端证书: @@ -262,7 +282,7 @@ point to the rotated kubelet client certificates, by replacing `client-certifica client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem client-key: /var/lib/kubelet/pki/kubelet-client-current.pem ``` -{{< /warning >}} +{{< /note >}} -最佳的做法是经常升级集群以确保安全。 -{{< /note >}} - -kubeadm 在 1.17 版本之前有一个[缺陷](https://github.com/kubernetes/kubeadm/issues/1818), -该缺陷导致 `kubeadm update node` 执行时 `--certificate-renewal` 的默认值被设置为 `false`。 -在这种情况下,你需要显式地设置 `--certificate-renewal=true`。 -{{< /warning >}} - ## 手动更新证书 {#manual-certificate-renewal} 你能随时通过 `kubeadm certs renew` 命令手动更新你的证书,只需带上合适的命令行选项。 +如果你正在运行的集群具有多副本的控制平面,则需要在所有控制平面节点上执行此命令。 此命令用 CA(或者 front-proxy-CA )证书和存储在 `/etc/kubernetes/pki` 中的密钥执行更新。 +`kubeadm certs renew` 使用现有的证书作为属性(Common Name、Organization、SAN 等)的权威来源, +而不依赖于 `kubeadm-config` ConfigMap。强烈建议使它们保持同步。 +即便如此,Kubernetes 项目仍然建议使用的证书与 ConfigMap 中的关联值保持同步,以避免任何混淆的风险。 + 执行完此命令之后你需要重启控制面 Pod。因为动态证书重载目前还不被所有组件和证书支持,所有这项操作是必须的。 [静态 Pod](/zh-cn/docs/tasks/configure-pod-container/static-pod/) 是被本地 kubelet 而不是 API 服务器管理,所以 kubectl 不能用来删除或重启他们。 @@ -344,50 +359,41 @@ the Pod and the certificate renewal for the component can complete. 在另一个 `fileCheckFrequency` 周期之后你可以将文件移回去,kubelet 可以完成 Pod 的重建,而组件的证书更新操作也得以完成。 -{{< warning >}} -如果你运行了一个 HA 集群,这个命令需要在所有控制面板节点上执行。 -{{< /warning >}} - -{{< note >}} - -`certs renew` 使用现有的证书作为属性(Common Name、Organization、SAN 等)的权威来源, -而不是 `kubeadm-config` ConfigMap。强烈建议使它们保持同步。 -{{< /note >}} +`kubeadm certs renew` 可以更新任何特定的证书,或者使用子命令 `all` 更新所有的证书: -`kubeadm certs renew` 可以更新任何特定的证书,或者使用子命令 `all` -更新所有的证书,如下所示: - ```shell +# If you are running cluster with a replicated control plane, this command +# needs to be executed on all the control-plane nodes. +kubeadm certs renew all +``` +--> +```shell +# 如果你运行的集群具有多副本的控制平面,则需要在所有控制平面节点上执行这条命令 kubeadm certs renew all ``` -{{< note >}} -使用 kubeadm 构建的集群通常会将 `admin.conf` 证书复制到 `$HOME/.kube/config` 中, -如[使用 kubeadm 创建集群](/zh-cn/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/)中所指示的那样。 -在这样的系统中,为了在更新 `admin.conf` 后更新 `$HOME/.kube/config` 的内容, -你必须运行以下命令: +### 复制管理员证书(可选) {#admin-certificate-copy} + +使用 kubeadm 构建的集群通常会将 `admin.conf` 证书复制到 `$HOME/.kube/config`, +参阅[使用 kubeadm 创建集群](/zh-cn/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/)。 +在这样的系统上,若要在更新 `admin.conf` 后更新 `$HOME/.kube/config` 的内容,你可以运行以下命令: ```shell sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config ``` -{{< /note >}} - ### 设置一个签名者(Signer) {#set-up-a-signer} Kubernetes 证书颁发机构不是开箱即用。你可以配置外部签名者,例如 @@ -489,7 +494,7 @@ Renewal of ceritficates is possible by generating new CSRs and signing them with For more details about working with CSRs generated by kubeadm see the section [Signing certificate signing requests (CSR) generated by kubeadm](#signing-csr). --> -### 使用证书签名请求(CSR)续订 +### 使用证书签名请求(CSR)续订 {#renewal-by-using-certificate-signing-requests-csr} 可以通过生成新的 CSR 并使用外部 CA 对其进行签名来对证书进行续约。 有关使用 kubeadm 生成的 CSR 的更多详细信息,请参阅[对 kubeadm 生成的证书签名请求(CSR)进行签名](#signing-csr)部分。 @@ -643,28 +648,47 @@ IP 或域名请求服务证书。 ## 为其他用户生成 kubeconfig 文件 {#kubeconfig-additional-users} -在集群创建过程中,kubeadm 对 `admin.conf` 中的证书进行签名时,将其配置为 -`Subject: O = system:masters, CN = kubernetes-admin`。 +在集群创建过程中,`kubeadm init` 对 `super-admin.conf` 中的证书进行签名时,将其配置为 +`Subject: O = system:masters, CN = kubernetes-super-admin`。 [`system:masters`](/zh-cn/docs/reference/access-authn-authz/rbac/#user-facing-roles) 是一个例外的超级用户组,可以绕过鉴权层(例如 [RBAC](/zh-cn/docs/reference/access-authn-authz/rbac/))。 -强烈建议不要将 `admin.conf` 文件与任何人共享。 +文件 `admin.conf` 也由 kubeadm 在控制平面节点上创建,此文件包含设为 +`Subject: O = kubeadm:cluster-admins, CN = kubernetes-admin` 的证书。 +`kubeadm:cluster-admins` 是一个逻辑上属于 kubeadm 的组。 +如果你的集群使用 RBAC(kubeadm 的默认设置),则 `kubeadm:cluster-admins` +组被绑定到 [`cluster-admin`](/zh-cn/docs/reference/access-authn-authz/rbac/#user-facing-roles) ClusterRole。 + +{{< warning >}} + +避免共享 `super-admin.conf` 或 `admin.conf` 文件。 +实际上,即使是管理员等工作人员,也只为其创建最小访问权限, +这种最小权限的方案适用于除例外(应急)访问之外的所有场景。 +{{< /warning >}} -你要使用 [`kubeadm kubeconfig user`](/zh-cn/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig) +你可以使用 [`kubeadm kubeconfig user`](/zh-cn/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig) 命令为其他用户生成 kubeconfig 文件,这个命令支持命令行参数和 [kubeadm 配置结构](/zh-cn/docs/reference/config-api/kubeadm-config.v1beta4/)。 以上命令会将 kubeconfig 打印到终端上,也可以使用 `kubeadm kubeconfig user ... > somefile.conf` @@ -768,31 +792,27 @@ file, similarly to commands such as `kubeadm init`. Any specification such as extra SANs and custom IP addresses must be stored in the same configuration file and used for all relevant kubeadm commands by passing it as `--config`. --> -`kubeadm certs generate-csr` 命令为 kubeadm 所了解并管理的所有证书生成 CSR。 -该标志接受 [kubeadm 配置](/zh-cn/docs/reference/config-api/kubeadm-config.v1beta3/)文件, +要将自定义选项传递给 `kubeadm certs generate-csr`,可以使用 `--config` 标志, +此标志接受 [kubeadm 配置](/zh-cn/docs/reference/config-api/kubeadm-config.v1beta3/)文件, 与诸如 `kubeadm init` 这类命令相似。 所有规约(例如额外的 SAN 和自定义 IP 地址)都必须存储在同一配置文件中, 并通过将其作为 `--config` 传递来用于所有相关的 kubeadm 命令。 {{< note >}} -本指南将介绍如何使用 `openssl` 命令来执行 CSR,但你可以使用你喜欢的工具。 -{{< /note >}} +This guide uses the default Kubernetes directory `/etc/kubernetes`, which requires +a super user. If you are following this guide and are using directories that you can +write to (typically, this means running `kubeadm` with `--cert-dir` and `--kubeconfig-dir`) +then you can omit the `sudo` command). -{{< note >}} - -本指南将使用默认的 Kubernetes 目录 `/etc/kubernetes`,需要超级用户权限。 -如果你按照本指南使用访问权限较低的目录(通过指定 `--cert-dir` 和 `--kubeconfig-dir`),可以省略 `sudo` 命令。 -但请注意,生成的文件必须被复制到 `/etc/kubernetes` 目录下,以便 `kubeadm init` +本指南使用默认的 Kubernetes 目录 `/etc/kubernetes`,需要超级用户权限。 +如果你按照本指南使用你可以写入的目录 +(通常这意味着使用 `--cert-dir` 和 `--kubeconfig-dir` 运行 `kubeadm`),你可以省略 `sudo` 命令。 + +然后,你必须将生成的文件复制到 `/etc/kubernetes` 目录下,以便 `kubeadm init` 或 `kubeadm join` 能够找到它们。 {{< /note >}} @@ -802,7 +822,7 @@ so that `kubeadm init` or `kubeadm join` will find them. On the primary control plane node, where `kubeadm init` will be executed, call the following commands: --> -### 准备 CA 和服务帐户文件 +### 准备 CA 和服务帐户文件 {#preparing-ca-and-service-account-files} 在将执行` kubeadm init` 的主控制平面节点上,执行以下命令: @@ -825,12 +845,13 @@ private keys) that kubeadm needs for a control plane node. {{< note >}} -如果你使用外部 CA,则必须在带外生成相同的文件,并手动将它们复制到 -主控制平面节点上的 `/etc/kubernetes`。 +如果你使用外部 CA,则你必须在带外生成相同的文件,并手动将它们复制到主控制平面节点上的 `/etc/kubernetes`。 + 所有 CSR 被签名后,你可以删除根 CA 密钥(`ca.key`),如[外部 CA 模式](#external-ca-mode)部分中所述。 {{< /note >}} @@ -903,9 +924,14 @@ for signing new kubelet client certificates. Processing the `kubelet.conf.csr` on the primary control plane node (`kubeadm init`) is required, because that is considered the node that bootstraps the cluster and a pre-populated `kubelet.conf` is needed. + +You must process the `kubelet.conf.csr` file on the primary control plane node +(the host where you originally ran `kubeadm init`). This is because `kubeadm` +considers that as the node that bootstraps the cluster, and a pre-populated +`kubelet.conf` is needed. --> -你仍需要在主控制平面节点(`kubeadm init`)上处理 `kubelet.conf.csr`, -因为该节点被视为引导集群的节点,并且需要预先填充的 `kubelet.conf`。 +你必须在主控制平面节点(你最初运行 `kubeadm init` 的主机)上处理 `kubelet.conf.csr`, +这是因为 `kubeadm` 将该节点视为引导集群的节点,并且需要预先填充的 `kubelet.conf`。 {{< /note >}} -### 签署所有证书的 CSR +### 签署所有证书的 CSR {#signing-csrs-for-all-certificates} {{< note >}} -### 在 kubeconfig 文件中嵌入证书 +### 在 kubeconfig 文件中嵌入证书 {#embedding-certificates-in-kubeconfig-files} 对具有 CSR 文件的所有节点重复此步骤。 @@ -1099,9 +1127,15 @@ and execute the script. 在 `/etc/kubernetes` 目录中编写以下脚本,进入该目录并执行脚本。 ```bash #!/bin/bash @@ -1133,7 +1167,7 @@ to create a Kubernetes cluster from these nodes. During `init` and `join`, kubea uses existing certificates, encryption keys and kubeconfig files that it finds in the `/etc/kubernetes` tree on the host's local filesystem. --> -### kubeadm 节点初始化 +### kubeadm 节点初始化 {#kubeadm-node-initialization} 一旦 CSR 文件被签名并且所需的证书在要用作节点的主机上就位,你就可以使用命令 `kubeadm init` 和 `kubeadm join` 使用这些节点创建 Kubernetes 集群。