使用 kubeadm 管理证书

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

Kubernetes 项目建议及时升级到最新的补丁版本，并确保运行受支持的 Kubernetes 小版本。遵循此建议有助于保持安全。

开始之前

你应该熟悉 Kubernetes 中的 PKI 证书及要求。

你应该熟悉如何向 kubeadm 命令传递 配置文件。

本指南涵盖了 openssl 命令的使用（如果你选择手动签名证书，会用到该命令），但你可以使用你喜欢的工具。

这里的一些步骤使用了 sudo 来获得管理员权限。你可以使用任何等效的工具。

使用自定义证书

默认情况下，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 来签署其余证书。

选择加密算法

kubeadm 允许你选择用于创建公钥和私钥的加密算法。这可以通过使用 kubeadm 配置中的 encryptionAlgorithm 字段来完成。

apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
encryptionAlgorithm: <ALGORITHM>

<ALGORITHM> 可以是 RSA-2048 (默认)、RSA-3072、RSA-4096 或 ECDSA-P256 之一。

选择证书有效期

kubeadm 允许你选择 CA 证书和叶子证书的有效期。这可以通过使用 kubeadm 配置中的 certificateValidityPeriod 和 caCertificateValidityPeriod 字段来完成。

apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
certificateValidityPeriod: 8760h # Default: 365 days × 24 hours = 1 year
caCertificateValidityPeriod: 87600h # Default: 365 days × 24 hours * 10 = 10 years

这些字段的值遵循 Go 的 time.Duration 值 的接受格式，支持的最长单位是 h (小时)。

外部 CA 模式

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

相反，应单独运行 controller-manager，并带有 --controllers=csrsigner 标志，指向 CA 证书和密钥。

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

手动准备组件凭据

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

本指南涵盖了 openssl 命令的使用（如果你选择手动签名证书，会用到该命令），但你可以使用你喜欢的工具。

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

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

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

此外，也可以使用 kubeadm phase 命令来自动化此过程。

• 转到你想要准备作为带有外部 CA 的 kubeadm 控制平面节点的宿主机。
• 将你拥有的外部 CA 文件 ca.crt 和 ca.key 复制到该节点的 /etc/kubernetes/pki 目录中。
• 准备一个临时 kubeadm 配置文件，命名为 config.yaml，可用于 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 会通知用户；在这种情况下，用户应负责手动或使用其他工具管理证书续订。

上述列表中不包括 kubelet.conf 配置文件，因为 kubeadm 配置 kubelet 以在 /var/lib/kubelet/pki 下使用可轮换的证书自动续订证书。要修复过期的 kubelet 客户端证书，请参阅Kubelet 客户端证书轮换失败。

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

自动证书续订

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

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

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

手动证书续订

你可以使用 kubeadm certs renew 命令以及适当的命令行选项随时手动续订证书。如果你正在运行具有复制控制平面的集群，则需要在所有控制平面节点上执行此命令。

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

kubeadm certs renew 使用现有证书作为属性（通用名称、组织、主题备用名称）的权威来源，而不依赖于 kubeadm-config ConfigMap。尽管如此，Kubernetes 项目建议保持提供的证书和该 ConfigMap 中的相关值同步，以避免任何混淆风险。

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

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

# 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

复制管理员证书（可选）

使用 kubeadm 构建的集群通常会将 admin.conf 证书复制到 $HOME/.kube/config 中，如使用 kubeadm 创建集群 中所述。在此类系统上，在续订 admin.conf 后更新 $HOME/.kube/config 的内容，可以运行以下命令

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/v1beta4
kind: ClusterConfiguration
controllerManager:
  extraArgs:
  - name: "cluster-signing-cert-file"
    value: "/etc/kubernetes/pki/ca.crt"
  - name: "cluster-signing-key-file"
    value: "/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 服务端证书是自签名的。这意味着来自 metrics-server 等外部服务到 kubelet 的连接无法使用 TLS 保护。

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

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

如果你已经创建了集群，则必须通过执行以下操作进行修改

• 在 kube-system 命名空间中找到并编辑 kubelet-config-1.33 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 中的默认签名者 - kubernetes.io/kubelet-serving 无法自动批准这些证书的 CSRs (Certificate Signing Requests)。这将需要用户或第三方控制器的操作。

这些 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 签名者。

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

• kubelet-csr-approver

除非此类控制器不仅验证 CSR 中的通用名称 (CommonName)，还验证请求的 IP 和域名，否则它不是安全的机制。这将防止恶意行为者（拥有 kubelet 客户端证书访问权限）创建请求任何 IP 或域名的服务端证书的 CSR。

为额外用户生成 kubeconfig 文件

在集群创建期间，kubeadm init 会为 super-admin.conf 中的证书签名，使其具有 Subject: O = system:masters, CN = kubernetes-super-admin。 system:masters 是一个紧急逃生、超级用户组，它绕过授权层（例如，RBAC）。kubeadm 还在控制平面节点上创建了 admin.conf 文件，该文件包含一个证书，其 Subject: O = kubeadm:cluster-admins, CN = kubernetes-admin。kubeadm:cluster-admins 是一个逻辑上属于 kubeadm 的组。如果你的集群使用 RBAC（kubeadm 默认设置），则 kubeadm:cluster-admins 组绑定到 cluster-admin ClusterRole。

你可以使用 kubeadm kubeconfig user 命令为额外用户生成 kubeconfig 文件。该命令接受命令行标志和 kubeadm 配置 选项的混合。生成的 kubeconfig 将写入标准输出，并可以通过管道重定向到文件，例如使用 kubeadm kubeconfig user ... > somefile.conf。

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

# example.yaml
apiVersion: kubeadm.k8s.io/v1beta4
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}"

以下示例将生成一个 kubeconfig 文件，其中包含对属于 appdevs 组的新用户 johndoe 有效 24 小时的凭据。

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

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

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 等命令类似。任何规范，例如额外的 SANs 和自定义 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

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

对于辅助控制平面节点（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 文件。