From 41b796a961be34917be914d0537b6a3ceb7a5e3a Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Sun, 16 Aug 2020 13:43:38 +0800 Subject: [PATCH] [zh] Resync kubeadm-certs task --- .../kubeadm/kubeadm-certs.md | 401 ++++++++++-------- 1 file changed, 231 insertions(+), 170 deletions(-) diff --git a/content/zh/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md b/content/zh/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md index 664381d24b..5e3d098340 100644 --- a/content/zh/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md +++ b/content/zh/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md @@ -1,16 +1,13 @@ --- -reviewers: -- sig-cluster-lifecycle title: 使用 kubeadm 进行证书管理 content_type: task +weight: 10 --- @@ -20,251 +17,319 @@ content_type: task - -由 [kubeadm](/docs/reference/setup-tools/kubeadm/kubeadm/) 生成的客户端证书在 1 年后到期。 本页说明如何使用 kubeadm 管理证书续订。 - - +由 [kubeadm](/zh/docs/reference/setup-tools/kubeadm/kubeadm/) 生成的客户端证书在 1 年后到期。 +本页说明如何使用 kubeadm 管理证书续订。 ## {{% heading "prerequisites" %}} - - - -熟悉 [Kubernetes 中的 PKI证书和要求](/docs/setup/certificates/)。 - -您应该熟悉[Kubernetes 中的 PKI 证书和要求](/docs/setup/best-practices/certificates/)。 - - +你应该熟悉 [Kubernetes 中的 PKI 证书和要求](/zh/docs/setup/best-practices/certificates/)。 + +### 使用自定义的证书 {#custom-certificates} + +默认情况下, kubeadm 会生成运行一个集群所需的全部证书。 +你可以通过提供你自己的证书来改变这个行为策略。 + + +如果要这样做, 你必须将证书文件放置在通过 `--cert-dir` 命令行参数或者配置文件里的 +`CertificatesDir` 配置项指明的目录中。默认的值是 `/etc/kubernetes/pki`。 + + +如果在运行 `kubeadm init` 之前存在给定的证书和私钥对，kubeadm 将不会重写它们。 +例如，这意味着您可以将现有的 CA 复制到 `/etc/kubernetes/pki/ca.crt` 和 +`/etc/kubernetes/pki/ca.key` 中，而 kubeadm 将使用此 CA 对其余证书进行签名。 + + +#### 外部 CA 模式 {#external-ca-mode} + +只提供了 `ca.crt` 文件但是不提供 `ca.key` 文件也是可以的 (这只对 CA 根证书可用，其它证书不可用)。 +如果所有的其它证书和 kubeconfig 文件已就绪， kubeadm 检测到满足以上条件就会激活 +"外部 CA" 模式。kubeadm 将会在没有 CA 密钥文件的情况下继续执行。 + + +否则, kubeadm 将独立运行 controller-manager，附加一个 `--controllers=csrsigner` +的参数，并且指明 CA 证书和密钥。 + +You can use the `check-expiration` subcommand to check certificate expiration. +--> ## 检查证书是否过期 - - -`check-expiration` 能被用来检查证书是否过期 +你可以使用 `check-expiration` 子命令来检查证书是否过期 ``` kubeadm alpha certs check-expiration ``` - - + 输出类似于以下内容： ``` -CERTIFICATE EXPIRES RESIDUAL TIME EXTERNALLY MANAGED -admin.conf May 15, 2020 13:03 UTC 364d false -apiserver May 15, 2020 13:00 UTC 364d false -apiserver-etcd-client May 15, 2020 13:00 UTC 364d false -apiserver-kubelet-client May 15, 2020 13:00 UTC 364d false -controller-manager.conf May 15, 2020 13:03 UTC 364d false -etcd-healthcheck-client May 15, 2020 13:00 UTC 364d false -etcd-peer May 15, 2020 13:00 UTC 364d false -etcd-server May 15, 2020 13:00 UTC 364d false -front-proxy-client May 15, 2020 13:00 UTC 364d false -scheduler.conf May 15, 2020 13:03 UTC 364d false +CERTIFICATE EXPIRES RESIDUAL TIME CERTIFICATE AUTHORITY EXTERNALLY MANAGED +admin.conf Dec 30, 2020 23:36 UTC 364d no +apiserver Dec 30, 2020 23:36 UTC 364d ca no +apiserver-etcd-client Dec 30, 2020 23:36 UTC 364d etcd-ca no +apiserver-kubelet-client Dec 30, 2020 23:36 UTC 364d ca no +controller-manager.conf Dec 30, 2020 23:36 UTC 364d no +etcd-healthcheck-client Dec 30, 2020 23:36 UTC 364d etcd-ca no +etcd-peer Dec 30, 2020 23:36 UTC 364d etcd-ca no +etcd-server Dec 30, 2020 23:36 UTC 364d etcd-ca no +front-proxy-client Dec 30, 2020 23:36 UTC 364d front-proxy-ca no +scheduler.conf Dec 30, 2020 23:36 UTC 364d no + +CERTIFICATE AUTHORITY EXPIRES RESIDUAL TIME EXTERNALLY MANAGED +ca Dec 28, 2029 23:36 UTC 9y no +etcd-ca Dec 28, 2029 23:36 UTC 9y no +front-proxy-ca Dec 28, 2029 23:36 UTC 9y no ``` - -该命令显示 `/etc/kubernetes/pki` 文件夹中的客户端证书以及 kubeadm 使用的 KUBECONFIG 文件中嵌入的客户端证书的到期时间/剩余时间。 +该命令显示 `/etc/kubernetes/pki` 文件夹中的客户端证书以及 kubeadm 使用的 KUBECONFIG +文件中嵌入的客户端证书的到期时间/剩余时间。 +另外， kubeadm 会通知用户证书是否由外部管理； +在这种情况下，用户应该小心的手动/使用其他工具来管理证书更新。 -另外， kubeadm 会通知用户证书是否由外部管理； 在这种情况下，用户应该小心的手动/使用其他工具来管理证书更新。 - -{{< warning >}} `kubeadm` 不能管理由外部 CA 签名的证书 + -->` +{{< warning >}} +kubeadm` 不能管理由外部 CA 签名的证书 {{< /warning >}} -{{< note >}} 上面的列表中没有包含 `kubelet.conf` 因为 kubeadm 将 kubelet 配置为自动更新证书。 - +--> +{{< note >}} +上面的列表中没有包含 `kubelet.conf` 因为 kubeadm 将 kubelet 配置为自动更新证书。 {{< /note >}} + +{{< warning >}} +在通过 `kubeadm init` 创建的节点上，在 kubeadm 1.17 版本之前有一个 +[缺陷](https://github.com/kubernetes/kubeadm/issues/1753)，该缺陷 +使得你必须手动修改 `kubelet.conf` 文件的内容。 +`kubeadm init` 操作结束之后，你必须更新 `kubelet.conf` 文件 +将 `client-certificate-data` 和 `client-key-data` 改为如下所示的内容 +以便使用轮换后的 kubelet 客户端证书： + +```yaml +client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem +client-key: /var/lib/kubelet/pki/kubelet-client-current.pem +``` +{{< /warning >}} + -## 自动更新证书 - -`kubeadm` 会在控制面板[升级](/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-15/)的时候更新所有证书 +## 自动更新证书 + +`kubeadm` 会在控制面 +[升级](/zh/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/) +的时候更新所有证书。 -这个功能旨在解决最简单的用例；如果您对此类证书的更新没有特殊要求，并且定期执行 Kubernetes 版本升级（每次升级之间的间隔时间少于 1 年），则 kubeadm 将确保您的集群保持最新状态并保持合理的安全性。 +这个功能旨在解决最简单的用例；如果你对此类证书的更新没有特殊要求， +并且定期执行 Kubernetes 版本升级（每次升级之间的间隔时间少于 1 年）， +则 kubeadm 将确保你的集群保持最新状态并保持合理的安全性。 -{{< note >}} 最佳的做法是经常升级集群以确保安全。 +--> +{{< note >}} +最佳的做法是经常升级集群以确保安全。 {{< /note >}} +如果你对证书更新有更复杂的需求，则可通过将 `--certificate-renewal=false` 传递给 +`kubeadm upgrade apply` 或者 `kubeadm upgrade node`，从而选择不采用默认行为。 -如果您对证书更新有更复杂的需求，则可通过将 `--certificate-renewal=false` 传递给 `kubeadm upgrade apply` 或者 `kubeadm upgrade node` ，从而选择不采用默认行为。 + +{{< warning >}} +kubeadm 在 1.17 版本之前有一个[缺陷](https://github.com/kubernetes/kubeadm/issues/1818)， +该缺陷导致 `kubeadm update node` 执行时 `--certificate-renewal` 的默认值被设置为 `false`。 +在这种情况下，你需要显式地设置 `--certificate-renewal=true`。 +{{< /warning >}} ## 手动更新证书 - -您能随时通过 `kubeadm alpha certs renew` 命令手动更新您的证书。 +你能随时通过 `kubeadm alpha certs renew` 命令手动更新你的证书。 +此命令用 CA （或者 front-proxy-CA ）证书和存储在 `/etc/kubernetes/pki` 中的密钥执行更新。 -这个命令用 CA （或者 front-proxy-CA ）证书和存储在 `/etc/kubernetes/pki` 中的密钥执行更新。 - -{{< warning >}} 如果您运行了一个 HA 集群，这个命令需要在所有控制面板节点上执行。 +--> +{{< warning >}} +如果你运行了一个 HA 集群，这个命令需要在所有控制面板节点上执行。 {{< /warning >}} -{{< note >}} -`alpha certs renew` 使用现有的证书作为属性 (Common Name、Organization、SAN 等) 的权威来源，而不是 kubeadm-config ConfigMap 。强烈建议使它们保持同步。 +{{< note >}} +`alpha certs renew` 使用现有的证书作为属性 (Common Name、Organization、SAN 等) 的权威来源， +而不是 kubeadm-config ConfigMap 。强烈建议使它们保持同步。 {{< /note >}} - -`kubeadm alpha certs renew` 提供下列选项 - Kubernetes 证书通常在一年后到期。 - -- `--csr-only` 可用于经过一个外部 CA 生成的证书签名请求来更新证书（无需实际替换更新证书）；更多信息请参见下一段。 - - -- 也可以更新单个证书而不是全部证书。 +`kubeadm alpha certs renew` 提供下列选项 + +- `--csr-only` 可用于经过一个外部 CA 生成的证书签名请求来更新证书（无需实际替换更新证书）； + 更多信息请参见下节。 +- 可以更新单个证书而不是全部证书。 ## 用 Kubernetes 证书 API 更新证书 - - 本节提供有关如何使用 Kubernetes 证书 API 执行手动证书更新的更多详细信息。 -{{< caution >}} -这些是针对需要将其组织的证书基础结构集成到 kubeadm 构建的集群中的用户的高级主题。如果默认的 kubeadm 配置满足了您的需求，则应让 kubeadm 管理证书。 +{{< caution >}} +这些是针对需要将其组织的证书基础结构集成到 kubeadm 构建的集群中的用户的高级主题。 +如果默认的 kubeadm 配置满足了你的需求，则应让 kubeadm 管理证书。 {{< /caution >}} -### 设置一个签名者 - +### 设置一个签名者（Signer） + Kubernetes 证书颁发机构不是开箱即用。 -您可以配置外部签名者，例如 [cert-manager][cert-manager-issuer] ，也可以使用内置签名者。 -内置签名者是 [`kube-controller-manager`][kcm] 的一部分。 +你可以配置外部签名者，例如 +[cert-manager](https://docs.cert-manager.io/en/latest/tasks/issuers/setup-ca.html)， +也可以使用内置签名者。 +内置签名者是 +[`kube-controller-manager`](/zh/docs/reference/command-line-tools-reference/kube-controller-manager/) +的一部分。 要激活内置签名者，请传递`--cluster-signing-cert-file` 和 `--cluster-signing-key-file`参数。 这个内置签名者是 [`kube-controller-manager`][kcm] 的一部分。 - - 要激活内置签名者，必须传递 `--cluster-signing-cert-file` 和 `--cluster-signing-key-file` 参数。 -如果您正在正在创建一个新的集群，您可以使用 kubeadm 的 [配置文件](config) +如果你正在正在创建一个新的集群，你可以使用 kubeadm 的 +[配置文件](https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2)。 - ```yaml - apiVersion: kubeadm.k8s.io/v1beta2 - kind: ClusterConfiguration - controllerManager: - extraArgs: - cluster-signing-cert-file: /etc/kubernetes/pki/ca.crt - cluster-signing-key-file: /etc/kubernetes/pki/ca.key - ``` - -[cert-manager-issuer]: https://cert-manager.readthedocs.io/en/latest/tutorials/ca/creating-ca-issuer.html -[kcm]: /docs/reference/command-line-tools-reference/kube-controller-manager/ -[config]: https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2 +```yaml +apiVersion: kubeadm.k8s.io/v1beta2 +kind: ClusterConfiguration +controllerManager: + extraArgs: + cluster-signing-cert-file: /etc/kubernetes/pki/ca.crt + cluster-signing-key-file: /etc/kubernetes/pki/ca.key +``` ### 创建证书签名请求 (CSR) - -您能用 `kubeadm alpha certs renew --use-api` 为 Kubernetes 证书 API 创建一个证书签名请求。 +你可以用 `kubeadm alpha certs renew --use-api` 为 Kubernetes 证书 API 创建一个证书签名请求。 -如果您设置例如 [cert-manager][cert-manager] 等外部签名者，则会自动批准证书签名请求（CSRs）。 -否者，您必须使用 [`kubectl certificate`][certs] 命令手动批准证书。 -以下 kubeadm 命令输出要批准的证书名称，然后缓慢等待批准发生： +如果你设置例如 [cert-manager](https://github.com/jetstack/cert-manager) +等外部签名者，证书签名请求（CSRs）会被自动批准。 +否则，你必须使用 [`kubectl certificate`](/zh/docs/setup/best-practices/certificates/) +命令手动批准证书。 +以下 kubeadm 命令输出要批准的证书名称，然后阻塞等待批准发生： ```shell sudo kubeadm alpha certs renew apiserver --use-api & ``` - + + 输出类似于以下内容： ``` [1] 2890 @@ -273,41 +338,42 @@ The output is similar to this: ### 批准证书签名请求 (CSR) - -如果您设置了一个外部签名者， 证书签名请求 (CSRs) 会自动被批准。 +如果你设置了一个外部签名者， 证书签名请求 (CSRs) 会自动被批准。 - -否则，您必须用 [`kubectl certificate`][certs] 命令手动批准证书，例如 +否则，你必须用 [`kubectl certificate`](/zh/docs/setup/best-practices/certificates/) +命令手动批准证书，例如： ```shell kubectl certificate approve kubeadm-cert-kube-apiserver-ld526 ``` + +The output is similar to this: --> 输出类似于以下内容： -```shell + +``` certificatesigningrequest.certificates.k8s.io/kubeadm-cert-kube-apiserver-ld526 approved ``` -您可以使用 `kubectl get csr` 查看待处理证书列表。 +你可以使用 `kubectl get csr` 查看待处理证书列表。 ## 通过外部 CA 更新证书 - 本节提供有关如何使用外部 CA 执行手动更新证书的更多详细信息。 ### 创建证书签名请求 (CSR) - -您可以传入一个带有 `--csr-dir` 的目录，将 CRS 输出到指定位置。 +你可以通过 `kubeadm alpha certs renew --csr-only` 命令创建证书签名请求。 + +CSR 和随附的私钥都在输出中给出。 +你可以传入一个带有 `--csr-dir` 的目录，将 CRS 输出到指定位置。 如果未指定 `--csr-dir` ，则使用默认证书目录( `/etc/kubernetes/pki` )。 -CSR 和随附的私钥都在输出中给出。签署证书后，必须将证书和私钥复制到 PKI 目录（默认情况下为 `/etc/kubernetes/pki`）。 - -CSR 代表对 CA 的请求，要求获得客户端的签名证书。 - - -您能用 `kubeadm alpha certs renew --csr-only` 创建一个证书签名请求。 - - -输出中给出了 CSR 和随附的私钥；您可以输入目录名和 `--csr-dir` ，以将 CSR 输出到指定位置。 - - -证书能用 `kubeadm alpha certs renew --csr-only` 更新。 +证书可以通过 `kubeadm alpha certs renew --csr-only` 来续订。 +和 `kubeadm init` 一样，可以使用 `--csr-dir` 标志指定一个输出目录。 -在 `kubeadm init` ,通过 `--csr-dir` 能指定输出文件夹。 +CSR 签署证书后，必须将证书和私钥复制到 PKI 目录（默认情况下为 `/etc/kubernetes/pki`）。 -要使用新证书，请将签名的证书和私钥复制到 PKI 目录（默认情况下为 `/etc/kubernetes/pki` ） - - -一个 CSR 包含一个证书的名字，域和 IP， 但是未指定用法 - - -颁发证书时， CA 有责任指定[正确的证书用法][cert-table] 。 +CSR 中包含一个证书的名字，域和 IP，但是未指定用法。 +颁发证书时，CA 有责任指定[正确的证书用法](/zh/docs/setup/best-practices/certificates/#all-certificates) -* 在 `openssl` 中，这是通过 [`openssl ca` 命令][openssl-ca] 完成的。 -* 在 `cfssl` 中，这是通过 [在配置文件中指定用法][cfssl-usages] 来完成的。 +* 在 `openssl` 中，这是通过 + [`openssl ca` 命令](https://superuser.com/questions/738612/openssl-ca-keyusage-extension) + 来完成的。 +* 在 `cfssl` 中，这是通过 + [在配置文件中指定用法](https://github.com/cloudflare/cfssl/blob/master/doc/cmd/cfssl.txt#L170) + 来完成的。 -使用首选方法对证书签名后，必须将证书和私钥复制到 PKI 目录（默认为 `/etc/kubernetes/pki` ）。 +使用首选方法对证书签名后，必须将证书和私钥复制到 PKI 目录（默认为 `/etc/kubernetes/pki` ）。 + +## 证书机构（CA）轮换 {#certificate-authority-rotation} + +kubeadm 并不直接支持对 CA 证书的轮换或者替换。 + +关于手动轮换或者置换 CA 的更多信息，可参阅 +[手动轮换 CA 证书](/zh/docs/tasks/tls/manual-rotation-of-ca-certificates/)。