背景介绍

使用 Kubeadm 搭建的集群默认证书有效期是一年，证书过期后集群会无法使用，因此必须在证书过期前及时续期证书。

如果集群证书过期，我们在使用 kubectl 连接集群时会收到如下报错：

Unable to connect to the server: x509: certificate has expired or is not yet valid

过期的证书会阻止对 etcd 集群的访问，因为实例间无法相互通信，etcd 日志可能包含如下错误条目：

W | rafthttp: health check for peer 6221a1d241bb2d0a could not connect: x509: certificate
has expired or is not yet valid
I | embed: rejected connection from "10.200.0.4:46108" (error "remote error: tls: bad
certificate", ServerName "")

可以通过如下命令检查集群证书的有效期： kubeadm certs check-expiration

[root@master-01 ~]# kubeadm  certs check-expiration[check-expiration] Reading configuration from the "kubeadm-config" ConfigMap in namespace "kube-system"...[check-expiration] Use 'kubeadm init phase upload-config --config your-config.yaml' to re-upload it.CERTIFICATE                EXPIRES                  RESIDUAL TIME   CERTIFICATE AUTHORITY   EXTERNALLY MANAGEDadmin.conf                 Jul 01, 2026 09:46 UTC   286d            ca                      no      apiserver                  Jul 01, 2026 09:46 UTC   286d            ca                      no      apiserver-etcd-client      Jul 01, 2026 09:46 UTC   286d            etcd-ca                 no      apiserver-kubelet-client   Jul 01, 2026 09:46 UTC   286d            ca                      no      controller-manager.conf    Jul 01, 2026 09:46 UTC   286d            ca                      no      etcd-healthcheck-client    Jul 01, 2026 09:46 UTC   286d            etcd-ca                 no      etcd-peer                  Jul 01, 2026 09:46 UTC   286d            etcd-ca                 no      etcd-server                Jul 01, 2026 09:46 UTC   286d            etcd-ca                 no      front-proxy-client         Jul 01, 2026 09:46 UTC   286d            front-proxy-ca          no      scheduler.conf             Jul 01, 2026 09:46 UTC   286d            ca                      no      super-admin.conf           Jul 01, 2026 09:46 UTC   286d            ca                      no      CERTIFICATE AUTHORITY   EXPIRES                  RESIDUAL TIME   EXTERNALLY MANAGEDca                      Jun 29, 2035 09:46 UTC   9y              no      etcd-ca                 Jun 29, 2035 09:46 UTC   9y              no      front-proxy-ca          Jun 29, 2035 09:46 UTC   9y              no      

这个集群证书有效期到 2026年7月1日，一般建议在证书到期前一个月左右就得续期证书。

证书更新

环境介绍

这个测试环境有3台master节点，1台worker 节点，已经运行了78天。

[root@master-01 ~]# kubectl  get node 
NAME        STATUS   ROLES           AGE   VERSION
master-01   Ready    control-plane   78d   v1.32.2
master-02   Ready    control-plane   78d   v1.32.2
master-03   Ready    control-plane   78d   v1.32.2
worker-01   Ready    <none>          78d   v1.32.2

证书备份

在更新证书之前建议先备份 现有证书，对运维人员来说在任何变更前都备份是一个好习惯，关键时刻是救命的稻草。使用 Kubeadm 部署的集群证书都放在 /etc/kubernetes/pki/ 目录下。

[root@master-01 ~]# ll /etc/kubernetes/pki/ 
total 56
-rw-r--r-- 1 root root 1306 Jul  1 17:46 apiserver.crt
-rw-r--r-- 1 root root 1123 Jul  1 17:46 apiserver-etcd-client.crt
-rw------- 1 root root 1675 Jul  1 17:46 apiserver-etcd-client.key
-rw------- 1 root root 1679 Jul  1 17:46 apiserver.key
-rw-r--r-- 1 root root 1176 Jul  1 17:46 apiserver-kubelet-client.crt
-rw------- 1 root root 1675 Jul  1 17:46 apiserver-kubelet-client.key
-rw-r--r-- 1 root root 1107 Jul  1 17:46 ca.crt
-rw------- 1 root root 1675 Jul  1 17:46 ca.key
drwxr-xr-x 2 root root  162 Jul  1 17:46 etcd
-rw-r--r-- 1 root root 1123 Jul  1 17:46 front-proxy-ca.crt
-rw------- 1 root root 1679 Jul  1 17:46 front-proxy-ca.key
-rw-r--r-- 1 root root 1119 Jul  1 17:46 front-proxy-client.crt
-rw------- 1 root root 1679 Jul  1 17:46 front-proxy-client.key
-rw------- 1 root root 1675 Jul  1 17:46 sa.key
-rw------- 1 root root  451 Jul  1 17:46 sa.pub

可以将 /etc/kubernetes 目录都备份了，kubernetes 相关的大多数配置文件和证书都放在这里。

cp -r /etc/kubernetes/  /tmp/k8s-backup

更新第一台 Master 节点证书

我有 3 台 Master 节点 ，先在 第一台 Master 节点上执行命令 kubeadm certs renew all 。​​​​​​​

[root@master-01 ~]# kubeadm certs renew all [renew] Reading configuration from the "kubeadm-config" ConfigMap in namespace "kube-system"...[renew] Use 'kubeadm init phase upload-config --config your-config.yaml' to re-upload it.certificate embedded in the kubeconfig file for the admin to use and for kubeadm itself renewedcertificate for serving the Kubernetes API renewedcertificate the apiserver uses to access etcd renewedcertificate for the API server to connect to kubelet renewedcertificate embedded in the kubeconfig file for the controller manager to use renewedcertificate for liveness probes to healthcheck etcd renewedcertificate for etcd nodes to communicate with each other renewedcertificate for serving etcd renewedcertificate for the front proxy client renewedcertificate embedded in the kubeconfig file for the scheduler manager to use renewedcertificate embedded in the kubeconfig file for the super-admin renewedDone renewing certificates. You must restart the kube-apiserver, kube-controller-manager, kube-scheduler and etcd, so that they can use the new certificates.

没有报错证书就更新成功了，重新检查证书有效期，可以看到证书有效期已经更新到 2026年9月18日。   ​​​​​​​

[root@master-01 ~]# kubeadm  certs check-expiration[check-expiration] Reading configuration from the "kubeadm-config" ConfigMap in namespace "kube-system"...[check-expiration] Use 'kubeadm init phase upload-config --config your-config.yaml' to re-upload it.CERTIFICATE                EXPIRES                  RESIDUAL TIME   CERTIFICATE AUTHORITY   EXTERNALLY MANAGEDadmin.conf                 Sep 18, 2026 08:31 UTC   364d            ca                      no      apiserver                  Sep 18, 2026 08:31 UTC   364d            ca                      no      

证书更新成功后不会生效，需要重启控制面组件，控制面组件都是静态Pod，重启时可以把清单文件 /etc/kubernetes/manifests/*.yaml 移走，等20秒左右再移回来就实现了重启。

mkdir -p /tmp/manifests
mv /etc/kubernetes/manifests/*.yaml /tmp/manifests
sleep 20 
mv /tmp/manifests/*.yaml  /etc/kubernetes/manifests/

更新剩余 Master 节点

在另外几台 Master 节点上也执行相同的操作即可，一台更新成功后再更新另一台，Master 节点都配置的负载均衡，对 Worker 节点是没有影响的，还是建议在业务低峰期操作。

kubeadm certs renew all 

mkdir -p /tmp/manifests
mv /etc/kubernetes/manifests/*.yaml /tmp/manifests
sleep 20 
mv /tmp/manifests/*.yaml  /etc/kubernetes/manifests/

更新 kubeconfig 文件

证书更新成功后还需要更新 kubeconfig 文件 。

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

99 年证书

每年更新证书确实很麻烦，在 kubeadm v1beta4 版本中增加了定义证书有效期的字段，我们可以把证书修改为 99 年，这样就再也不用为续期证书烦恼了。

apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
certificateValidityPeriod: 8760h # 默认：365 天 × 24 小时 = 1 年
caCertificateValidityPeriod: 87600h # 默认：365 天 × 24 小时 * 10 = 10 年

修改为

certificateValidityPeriod: 876000h # 99 年
caCertificateValidityPeriod: 876000h # 99 年

检查集群证书，都变成了 99 年，是不是很爽。​​​​​​​

[root@master-01 ~]# kubeadm  certs   check-expiration[check-expiration] Reading configuration from the "kubeadm-config" ConfigMap in namespace "kube-system"...[check-expiration] Use 'kubeadm init phase upload-config --config your-config.yaml' to re-upload it.CERTIFICATE                EXPIRES                  RESIDUAL TIME   CERTIFICATE AUTHORITY   EXTERNALLY MANAGEDadmin.conf                 Aug 26, 2125 08:36 UTC   99y             ca                      no      apiserver                  Aug 26, 2125 08:36 UTC   99y             ca                      no      ...CERTIFICATE AUTHORITY   EXPIRES                  RESIDUAL TIME   EXTERNALLY MANAGEDca                      Aug 26, 2125 08:36 UTC   99y             no      etcd-ca                 Aug 26, 2125 08:36 UTC   99y             no      front-proxy-ca          Aug 26, 2125 08:36 UTC   99y             no      

总结

本文演示了如何更新 Kubernetes 集群证书，如果是新搭建集群就可以通过修改参数将集群证书修改为99年，这样就不至于忘记更新证书导致的故障了。