使用 kubeadm 管理证书

由 kubeadm 生成的客户端证书在 1 年后过期。本页介绍如何使用 kubeadm 管理证书续订。它还涵盖了与 kubeadm 证书管理相关的其他任务。

准备工作

您应该熟悉 Kubernetes 中的 PKI 证书和要求。

使用自定义证书

默认情况下，kubeadm 会生成集群运行所需的所有证书。您可以通过提供自己的证书来覆盖此行为。

为此，您必须将它们放在 --cert-dir 标志或 kubeadm 的 ClusterConfiguration 的 certificatesDir 字段指定的任何目录中。默认情况下，这是 /etc/kubernetes/pki。

如果在运行 kubeadm init 之前存在给定的证书和私钥对，则 kubeadm 不会覆盖它们。这意味着您可以，例如，将现有的 CA 复制到 /etc/kubernetes/pki/ca.crt 和 /etc/kubernetes/pki/ca.key 中，并且 kubeadm 将使用此 CA 对其余证书进行签名。

外部 CA 模式

也可以仅提供 ca.crt 文件而不提供 ca.key 文件（这仅适用于根 CA 文件，不适用于其他证书对）。如果所有其他证书和 kubeconfig 文件都已就位，则 kubeadm 会识别此条件并激活“外部 CA”模式。kubeadm 将在没有磁盘上的 CA 密钥的情况下继续进行。

而是使用 --controllers=csrsigner 独立运行 controller-manager，并指向 CA 证书和密钥。

使用外部 CA 模式时，有多种方法可以准备组件凭据。

手动准备组件凭据

PKI 证书和要求 包括有关如何手动准备 kubeadm 所需的所有组件凭据的信息。

通过签署 kubeadm 生成的 CSR 来准备凭据

kubeadm 可以 生成 CSR 文件，您可以使用 openssl 之类的工具和您的外部 CA 手动对其进行签名。这些 CSR 文件将包含 kubeadm 部署的组件所需的凭据的所有规范。

使用 kubeadm 阶段自动准备组件凭据

或者，可以使用 kubeadm 阶段命令来自动执行此过程。

• 转到要使用外部 CA 准备作为 kubeadm 控制平面节点的主机。
• 将您拥有的外部 CA 文件 ca.crt 和 ca.key 复制到节点上的 /etc/kubernetes/pki 中。
• 准备一个名为 config.yaml 的临时 kubeadm 配置文件，该文件可以与 kubeadm init 一起使用。确保此文件包含可能包含在证书中的任何相关的集群范围或主机特定信息，例如，ClusterConfiguration.controlPlaneEndpoint、ClusterConfiguration.certSANs 和 InitConfiguration.APIEndpoint。
• 在同一主机上执行命令 kubeadm init phase kubeconfig all --config config.yaml 和 kubeadm init phase certs all --config config.yaml。这将在 /etc/kubernetes/ 及其 pki 子目录下生成所有必需的 kubeconfig 文件和证书。
• 检查生成的文件。删除 /etc/kubernetes/pki/ca.key，删除或移动文件 /etc/kubernetes/super-admin.conf 到安全位置。
• 在将调用 kubeadm join 的节点上，还要删除 /etc/kubernetes/kubelet.conf。此文件仅在将调用 kubeadm init 的第一个节点上是必需的。
• 请注意，某些文件（例如 pki/sa.*、pki/front-proxy-ca.* 和 pki/etc/ca.*）在控制平面节点之间共享，您可以生成一次并将它们 手动分发 到将调用 kubeadm join 的节点，或者您可以使用 kubeadm init 的 --upload-certs 功能和 kubeadm join 的 --certificate-key 来自动执行此分发。

在所有节点上准备好凭据后，为这些节点调用 kubeadm init 和 kubeadm join 以加入集群。kubeadm 将使用 /etc/kubernetes/ 及其 pki 子目录下的现有 kubeconfig 和证书文件。

检查证书到期时间

您可以使用 check-expiration 子命令来检查证书何时到期

kubeadm certs check-expiration

输出类似于此

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 文件（admin.conf、controller-manager.conf 和 scheduler.conf）中嵌入的客户端证书的到期时间/剩余时间。

此外，如果证书是外部管理的，kubeadm 会通知用户；在这种情况下，用户应注意手动/使用其他工具管理证书续订。

client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem
client-key: /var/lib/kubelet/pki/kubelet-client-current.pem

自动证书续订

kubeadm 在控制平面 升级 期间续订所有证书。

此功能旨在解决最简单的用例；如果您对证书续订没有特定要求并定期执行 Kubernetes 版本升级（每次升级之间不到 1 年），kubeadm 将负责保持您的集群最新且合理安全。

如果您对证书续订有更复杂的要求，则可以通过将 --certificate-renewal=false 传递给 kubeadm upgrade apply 或 kubeadm upgrade node 来选择退出默认行为。

手动证书续订

您可以使用 kubeadm certs renew 命令以及相应的命令行选项随时手动续订证书。

此命令使用存储在 /etc/kubernetes/pki 中的 CA（或 front-proxy-CA）证书和密钥执行续订。

运行该命令后，您应该重新启动控制平面 Pod。这是必需的，因为当前并非所有组件和证书都支持动态证书重新加载。静态 Pod 由本地 kubelet 管理，而不是由 API 服务器管理，因此 kubectl 不能用于删除和重新启动它们。要重新启动静态 Pod，您可以暂时从 /etc/kubernetes/manifests/ 中删除其清单文件并等待 20 秒（请参阅 KubeletConfiguration 结构 中的 fileCheckFrequency 值。如果 Pod 不再位于清单目录中，kubelet 将终止该 Pod。然后，您可以将文件移回，并在另一个 fileCheckFrequency 周期后，kubelet 将重新创建 Pod，并且组件的证书续订可以完成。

kubeadm certs renew 可以续订任何特定证书，或者使用子命令 all 可以续订所有证书，如下所示

kubeadm certs renew all

sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

使用 Kubernetes 证书 API 续订证书

本节提供有关如何使用 Kubernetes 证书 API 执行手动证书续订的更多详细信息。

设置签名者

Kubernetes 证书颁发机构无法开箱即用。您可以配置外部签名者，例如 cert-manager，或者您可以使用内置签名者。

内置签名者是 kube-controller-manager 的一部分。

要激活内置签名者，您必须传递 --cluster-signing-cert-file 和 --cluster-signing-key-file 标志。

如果您要创建新集群，则可以使用 kubeadm 配置文件

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
controllerManager:
  extraArgs:
    cluster-signing-cert-file: /etc/kubernetes/pki/ca.crt
    cluster-signing-key-file: /etc/kubernetes/pki/ca.key

创建证书签名请求 (CSR)

有关使用 Kubernetes API 创建 CSR，请参阅 创建 CertificateSigningRequest。

使用外部 CA 续订证书

本节详细介绍如何使用外部 CA 手动续订证书。

为了更好地与外部 CA 集成，kubeadm 还可以生成证书签名请求 (CSR)。CSR 表示向 CA 请求为客户端签署证书。在 kubeadm 中，任何通常由磁盘上的 CA 签署的证书都可以生成 CSR 来代替。但是，CA 不能生成 CSR。

使用证书签名请求 (CSR) 续订

可以通过生成新的 CSR 并使用外部 CA 对其进行签名来续订证书。有关使用 kubeadm 生成的 CSR 的更多详细信息，请参阅签署 kubeadm 生成的证书签名请求 (CSR)部分。

证书颁发机构 (CA) 轮换

Kubeadm 不支持开箱即用的 CA 证书轮换或替换。

有关手动轮换或替换 CA 的更多信息，请参阅手动轮换 CA 证书。

启用已签名的 kubelet 服务证书

默认情况下，kubeadm 部署的 kubelet 服务证书是自签名的。这意味着无法使用 TLS 保护从外部服务（如metrics-server）到 kubelet 的连接。

要将新 kubeadm 集群中的 kubelet 配置为获取正确签名的服务证书，您必须将以下最小配置传递给kubeadm init

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
serverTLSBootstrap: true

如果您已经创建了集群，则必须通过执行以下操作来调整它

• 在kube-system命名空间中找到并编辑kubelet-config-1.30 ConfigMap。在该 ConfigMap 中，kubelet键的KubeletConfiguration文档作为其值。编辑 KubeletConfiguration 文档以设置serverTLSBootstrap: true。
• 在每个节点上，在/var/lib/kubelet/config.yaml中添加serverTLSBootstrap: true字段，并使用systemctl restart kubelet重新启动 kubelet

字段serverTLSBootstrap: true将通过从certificates.k8s.io API 请求 kubelet 服务证书来启用引导。一个已知的限制是，kube-controller-manager 中的默认签名者无法自动批准这些证书的 CSR（证书签名请求） - kubernetes.io/kubelet-serving。这将需要用户或第三方控制器的操作。

可以使用以下命令查看这些 CSR

kubectl get csr

NAME        AGE     SIGNERNAME                        REQUESTOR                      CONDITION
csr-9wvgt   112s    kubernetes.io/kubelet-serving     system:node:worker-1           Pending
csr-lz97v   1m58s   kubernetes.io/kubelet-serving     system:node:control-plane-1    Pending

要批准它们，您可以执行以下操作

kubectl certificate approve <CSR-name>

默认情况下，这些服务证书将在一年后过期。Kubeadm 将KubeletConfiguration字段rotateCertificates设置为true，这意味着在接近过期时，将为服务证书创建一组新的 CSR，并且必须批准这些 CSR 才能完成轮换。要了解更多信息，请参阅证书轮换。

如果您正在寻找自动批准这些 CSR 的解决方案，建议您联系您的云提供商，询问他们是否有一个 CSR 签名者可以使用带外机制验证节点身份。

可以使用第三方自定义控制器

• kubelet-csr-approver

除非此类控制器不仅验证 CSR 中的 CommonName，还验证请求的 IP 和域名，否则它不是一种安全的机制。这将阻止有权访问 kubelet 客户端证书的恶意行为者创建请求为任何 IP 或域名提供证书的 CSR。

为其他用户生成 kubeconfig 文件

在集群创建期间，kubeadm 会对admin.conf中的证书进行签名，使其具有Subject: O = system:masters, CN = kubernetes-admin。system:masters是一个超级用户组，可以绕过授权层（例如，RBAC）。**不建议**与其他用户共享admin.conf！

相反，您可以使用kubeadm kubeconfig user命令为其他用户生成 kubeconfig 文件。该命令接受命令行标志和kubeadm 配置选项的混合。生成的 kubeconfig 将写入 stdout，并且可以使用kubeadm kubeconfig user ... > somefile.conf将其管道传输到文件。

可与--config一起使用的示例配置文件

# example.yaml
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
# Will be used as the target "cluster" in the kubeconfig
clusterName: "kubernetes"
# Will be used as the "server" (IP or DNS name) of this cluster in the kubeconfig
controlPlaneEndpoint: "some-dns-address:6443"
# The cluster CA key and certificate will be loaded from this local directory
certificatesDir: "/etc/kubernetes/pki"

确保这些设置与所需的目标集群设置匹配。要查看现有集群的设置，请使用

kubectl get cm kubeadm-config -n kube-system -o=jsonpath="{.data.ClusterConfiguration}"

以下示例将为属于appdevs组的新用户johndoe生成一个凭据有效期为 24 小时的 kubeconfig 文件

kubeadm kubeconfig user --config example.yaml --org appdevs --client-name johndoe --validity-period 24h

以下示例将生成一个具有管理员凭据的 kubeconfig 文件，有效期为 1 周

kubeadm kubeconfig user --config example.yaml --client-name admin --validity-period 168h

签署 kubeadm 生成的证书签名请求 (CSR)

您可以使用kubeadm certs generate-csr创建证书签名请求。调用此命令将为常规证书生成.csr / .key文件对。对于嵌入在 kubeconfig 文件中的证书，该命令将生成一个.csr / .conf对，其中密钥已嵌入在.conf文件中。

CSR 文件包含 CA 签署证书所需的所有相关信息。kubeadm 对其所有证书和 CSR 使用定义明确的规范。

默认证书目录为/etc/kubernetes/pki，而 kubeconfig 文件的默认目录为/etc/kubernetes。可以使用标志--cert-dir和--kubeconfig-dir分别覆盖这些默认值。

要将自定义选项传递给kubeadm certs generate-csr，请使用--config标志，该标志接受kubeadm 配置文件，类似于kubeadm init等命令。任何规范（例如额外的 SAN 和自定义 IP 地址）都必须存储在同一个配置文件中，并通过将其作为--config传递给所有相关的 kubeadm 命令来使用。

准备 CA 和服务帐户文件

在将要执行kubeadm init的主控制平面节点上，调用以下命令

sudo kubeadm init phase certs ca
sudo kubeadm init phase certs etcd-ca
sudo kubeadm init phase certs front-proxy-ca
sudo kubeadm init phase certs sa

这会将文件夹/etc/kubernetes/pki和/etc/kubernetes/pki/etcd填充 kubeadm 控制平面节点所需的所有自签名 CA 文件（证书和密钥）和服务帐户（公钥和私钥）。

对于辅助控制平面节点 (kubeadm join --control-plane)，无需调用上述命令。根据您设置高可用性集群的方式，您要么必须从主控制平面节点手动复制相同的文件，要么使用kubeadm init的自动--upload-certs功能。

生成 CSR

kubeadm certs generate-csr命令为 kubeadm 管理的所有已知证书生成 CSR。命令完成后，您必须手动删除不需要的.csr、.conf或.key文件。

kubelet.conf 的注意事项

本节适用于控制平面节点和工作节点。

如果您已从控制平面节点中删除了ca.key文件（外部 CA 模式），则此集群中的活动 kube-controller-manager 将无法签署 kubelet 客户端证书。如果您的设置中不存在用于签署这些证书的外部方法（例如外部签名者，您可以按照本指南中的说明手动签署kubelet.conf.csr。

请注意，这也意味着将禁用自动kubelet 客户端证书轮换。如果是这样，在证书即将过期时，您必须生成一个新的kubelet.conf.csr，对证书进行签名，将其嵌入到kubelet.conf中，然后重新启动 kubelet。

如果这不适用于您的设置，您可以跳过在辅助控制平面节点和工作节点（所有调用kubeadm join ...的节点）上处理kubelet.conf.csr的步骤。这是因为活动的 kube-controller-manager 将负责签署新的 kubelet 客户端证书。

控制平面节点

在主 (kubeadm init) 和辅助 (kubeadm join --control-plane) 控制平面节点上执行以下命令以生成所有 CSR 文件

sudo kubeadm certs generate-csr

如果要使用外部 etcd，请按照使用 kubeadm 的外部 etcd指南了解 kubeadm 和 etcd 节点上需要哪些 CSR 文件。可以删除/etc/kubernetes/pki/etcd下的其他.csr和.key文件。

根据kubelet.conf 的注意事项中的说明，保留或删除kubelet.conf和kubelet.conf.csr文件。

工作节点

根据kubelet.conf 的注意事项中的说明，可以选择调用

sudo kubeadm certs generate-csr

并仅保留kubelet.conf和kubelet.conf.csr文件。或者，完全跳过工作节点的步骤。

为所有证书签署 CSR

对所有具有 CSR 文件的节点重复此步骤。

在/etc/kubernetes目录中编写以下脚本，导航到该目录并执行该脚本。该脚本将为/etc/kubernetes树中存在的所有 CSR 文件生成证书。

#!/bin/bash

# Set certificate expiration time in days
DAYS=365

# Process all CSR files except those for front-proxy and etcd
find ./ -name "*.csr" | grep -v "pki/etcd" | grep -v "front-proxy" | while read -r FILE;
do
    echo "* Processing ${FILE} ..."
    FILE=${FILE%.*} # Trim the extension
    if [ -f "./pki/ca.srl" ]; then
        SERIAL_FLAG="-CAserial ./pki/ca.srl"
    else
        SERIAL_FLAG="-CAcreateserial"
    fi
    openssl x509 -req -days "${DAYS}" -CA ./pki/ca.crt -CAkey ./pki/ca.key ${SERIAL_FLAG} \
        -in "${FILE}.csr" -out "${FILE}.crt"
    sleep 2
done

# Process all etcd CSRs
find ./pki/etcd -name "*.csr" | while read -r FILE;
do
    echo "* Processing ${FILE} ..."
    FILE=${FILE%.*} # Trim the extension
    if [ -f "./pki/etcd/ca.srl" ]; then
        SERIAL_FLAG=-CAserial ./pki/etcd/ca.srl
    else
        SERIAL_FLAG=-CAcreateserial
    fi
    openssl x509 -req -days "${DAYS}" -CA ./pki/etcd/ca.crt -CAkey ./pki/etcd/ca.key ${SERIAL_FLAG} \
        -in "${FILE}.csr" -out "${FILE}.crt"
done

# Process front-proxy CSRs
echo "* Processing ./pki/front-proxy-client.csr ..."
openssl x509 -req -days "${DAYS}" -CA ./pki/front-proxy-ca.crt -CAkey ./pki/front-proxy-ca.key -CAcreateserial \
    -in ./pki/front-proxy-client.csr -out ./pki/front-proxy-client.crt

将证书嵌入 kubeconfig 文件

对所有具有 CSR 文件的节点重复此步骤。

在/etc/kubernetes目录中编写以下脚本，导航到该目录并执行该脚本。该脚本将获取在上一步中为 kubeconfig 文件从 CSR 签名的.crt文件，并将它们嵌入到 kubeconfig 文件中。

#!/bin/bash

CLUSTER=kubernetes
find ./ -name "*.conf" | while read -r FILE;
do
    echo "* Processing ${FILE} ..."
    KUBECONFIG="${FILE}" kubectl config set-cluster "${CLUSTER}" --certificate-authority ./pki/ca.crt --embed-certs
    USER=$(KUBECONFIG="${FILE}" kubectl config view -o jsonpath='{.users[0].name}')
    KUBECONFIG="${FILE}" kubectl config set-credentials "${USER}" --client-certificate "${FILE}.crt" --embed-certs
done

执行清理

对所有具有 CSR 文件的节点执行此步骤。

在 /etc/kubernetes 目录中编写以下脚本，导航到该目录并执行该脚本。

#!/bin/bash

# Cleanup CSR files
rm -f ./*.csr ./pki/*.csr ./pki/etcd/*.csr # Clean all CSR files

# Cleanup CRT files that were already embedded in kubeconfig files
rm -f ./*.crt

（可选）将 .srl 文件移动到要处理的下一个节点。

（可选）如果使用外部 CA，请删除 /etc/kubernetes/pki/ca.key 文件，如“外部 CA 节点”部分所述。

kubeadm 节点初始化

在对 CSR 文件进行签名并在要用作节点的主机上准备好所需的证书后，您可以使用 kubeadm init 和 kubeadm join 命令从这些节点创建 Kubernetes 集群。在 init 和 join 期间，kubeadm 使用它在主机本地文件系统上的 /etc/kubernetes 树中找到的现有证书、加密密钥和 kubeconfig 文件。