使用 kubeadm 管理证书
Kubernetes v1.15 [稳定]
由 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
独立运行控制器管理器,并指向 CA 证书和密钥。
使用外部 CA 模式时,有多种方法可以准备组件凭据。
手动准备组件凭据
PKI 证书及其要求 包含有关如何手动准备 kubeadm 组件凭据所需的所有内容的信息。
通过签署 kubeadm 生成的 CSR 来准备凭据
kubeadm 可以 生成 CSR 文件,您可以使用诸如 openssl
和您的外部 CA 之类的工具手动签署这些文件。这些 CSR 文件将包含 kubeadm 部署的组件所需的凭据的所有规范。
使用 kubeadm 阶段自动准备组件凭据
或者,可以使用 kubeadm 阶段命令来自动化此过程。
- 转到您想准备为 kubeadm 控制平面节点(使用外部 CA)的主机。
- 将您拥有的外部 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
的节点,或者您可以使用--upload-certs
功能kubeadm init
和--certificate-key
的kubeadm join
来自动化此分发。
一旦在所有节点上准备好了凭据,就为这些节点调用 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 会通知用户证书是否由外部管理;在这种情况下,用户应负责手动/使用其他工具管理证书续期。
警告
kubeadm
无法管理由外部 CA 签名的证书。注意
kubelet.conf
不包含在上面的列表中,因为 kubeadm 为 自动证书续期 配置 kubelet,并使用 /var/lib/kubelet/pki
下的可旋转证书。要修复过期的 kubelet 客户端证书,请参阅 Kubelet 客户端证书轮换失败。警告
在使用 kubeadm init
创建的节点上,在 kubeadm 版本 1.17 之前,存在一个 错误,您必须手动修改 kubelet.conf
的内容。在 kubeadm init
完成后,您应该更新 kubelet.conf
以指向轮换后的 kubelet 客户端证书,方法是将 client-certificate-data
和 client-key-data
替换为
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 版本 1.17 之前,存在一个 错误,其中--certificate-renewal
的默认值为 false
用于 kubeadm upgrade node
命令。在这种情况下,您应该显式设置 --certificate-renewal=true
。手动证书续期
您可以随时使用 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,并且组件的证书续期可以完成。
警告
如果您运行的是 HA 集群,则需要在所有控制平面节点上执行此命令。注意
certs renew
使用现有证书作为属性(通用名称、组织、SAN 等)的权威来源,而不是 kubeadm-config
ConfigMap。强烈建议将两者保持同步。kubeadm certs renew
可以续期任何特定的证书,或者使用子命令 all
,它可以续期所有证书,如下所示
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 执行手动证书续期的更多详细信息。
注意
这些是面向需要将组织的证书基础设施集成到 kubeadm 构建的集群中的用户的更高级的主题。如果默认的 kubeadm 配置满足您的需求,您应该让 kubeadm 管理证书,而不是自己管理。设置签名者
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)
请参阅 创建 CertificateSigningRequest,了解如何使用 Kubernetes API 创建 CSR。
使用外部 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.31
ConfigMap。在该 ConfigMap 中,kubelet
键具有 KubeletConfiguration 文档作为其值。编辑 KubeletConfiguration 文档以设置serverTLSBootstrap: true
。 - 在每个节点上,在
/var/lib/kubelet/config.yaml
中添加serverTLSBootstrap: true
字段,并使用systemctl restart kubelet
重启 kubelet
字段 serverTLSBootstrap: true
将启用 kubelet 服务证书的引导,方法是从 certificates.k8s.io
API 请求它们。一个已知的限制是,这些证书的 CSR(证书签名请求)无法由 kube-controller-manager 中的默认签名者自动批准 - 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 中的通用名,还验证了请求的 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 将写入标准输出,并且可以使用 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
以下示例将生成一个 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 命令。
注意
本指南将介绍使用openssl
命令签署 CSR 的方法,但您可以使用您喜欢的工具。注意
本指南将使用默认的 Kubernetes 目录/etc/kubernetes
,这需要超级用户。如果您使用的是宽松目录(通过传递 --cert-dir
和 --kubeconfig-dir
)来遵循本指南,则可以省略 sudo
命令)。但请注意,生成的文件必须复制到 /etc/kubernetes
树中,以便 kubeadm init
或 kubeadm join
能够找到它们。准备 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
。
注意
如果您使用的是外部 CA,则必须在带外生成相同的文件,并将其手动复制到主控制平面节点上的/etc/kubernetes
中。签署完所有 CSR 后,您可以删除根 CA 密钥 (ca.key
),如 外部 CA 模式 部分所述。对于辅助控制平面节点 (kubeadm join --control-plane
),无需调用上述命令。根据您设置 高可用性 集群的方式,您要么必须手动从主控制平面节点复制相同的文件,要么使用 kubeadm init
的自动 --upload-certs
功能。
生成 CSR
kubeadm certs generate-csr
命令为 kubeadm 管理的所有已知证书生成 CSR。命令完成后,您必须手动删除不需要的 .csr
、.conf
或 .key
文件。
kubelet.conf 的注意事项
本部分适用于控制平面节点和工作节点。
如果您已从控制平面节点 (外部 CA 模式) 中删除了 ca.key
文件,则此集群中的活动 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
) 上处理 kubelet.conf.csr
是必需的,因为这被认为是引导集群的节点,并且需要预填充的 kubelet.conf
。控制平面节点
在主 (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
注意
如果您使用的是外部 CA 并且已经拥有 openssl
的 CA 序列号文件 (.srl
),则可以将这些文件复制到将处理 CSR 的 kubeadm 节点。要复制的 .srl
文件是 /etc/kubernetes/pki/ca.srl
、/etc/kubernetes/pki/front-proxy-ca.srl
和 /etc/kubernetes/pki/etcd/ca.srl
。然后,可以将这些文件移动到将处理 CSR 文件的新节点。
如果节点上缺少 CA 的 .srl
文件,则以下脚本将使用随机的起始序列号生成新的 SRL 文件。
要了解有关 .srl
文件的更多信息,请参阅 openssl
文档,以了解 --CAserial
标志。
对所有包含 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
目录中编写以下脚本,导航到该目录并执行脚本。该脚本将获取在上一步中从 CSR 签署的 kubeconfig 文件的 .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 文件。
本页上的项目指的是提供 Kubernetes 所需功能的第三方产品或项目。Kubernetes 项目作者不对这些第三方产品或项目负责。有关更多详细信息,请参阅 CNCF 网站指南。
在提出添加额外第三方链接的更改之前,您应该阅读 内容指南。