kubespray-certificates

用途

该技能面向 Kubespray 部署的 Kubernetes 集群证书管理，主要解决四类问题：检查证书过期日期、启用证书自动续期、手动续期已过期证书、排查 x509 证书错误。核心原则是在部署阶段启用自动续期；若证书过期，则必须进行时间紧迫的手动续期。不适用于初始部署（应使用 kubespray-deployment）和集群升级（应使用 kubespray-operations）。

主要能力

证书类型覆盖

技能列出 Kubespray 集群中常见证书及其位置与用途：

CA 证书：/etc/kubernetes/pki/ca.crt，用于签发其他所有证书。
API server 证书：/etc/kubernetes/pki/apiserver.crt，标识 API server 身份。
kubelet 客户端证书：/etc/kubernetes/pki/apiserver-kubelet-client.crt，用于 API server 到 kubelet 的认证。
etcd CA 证书：/etc/ssl/etcd/ssl/ca.pem，用于签发 etcd 证书。
etcd member 证书：/etc/ssl/etcd/ssl/member-*.pem，用于 etcd peer 认证。

过期检查

提供多种检查方式：使用 kubeadm certs check-expiration 查看全部证书过期时间；使用 openssl x509 -in <证书路径> -noout -dates 检查单个证书；提供一行命令循环检查 /etc/kubernetes/pki/*.crt 下所有证书；使用 openssl x509 -in ... -noout -text | grep -A2 Validity 查看证书有效期详细信息。

自动续期配置

在初始部署时，于 inventory/mycluster/group_vars/k8s_cluster/k8s-cluster.yml 中添加：

auto_renew_certificates: true
auto_renew_certificates_systemd_calendar: "Mon *-*-1,15 03:00:00"

该配置会创建 systemd 定时器，每月运行两次。自动续期执行 kubeadm certs renew all，并通过 kubelet 重启控制平面组件。可使用 systemctl list-timers | grep cert 和 systemctl status k8s-cert-renew.timer 验证定时器状态。

手动续期

未配置自动续期时，可运行 Kubespray 证书续期 playbook：

cd kubespray
ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml \
  --tags=k8s-secrets,kubernetes/control-plane \
  -b

也可在每个控制平面节点直接使用 kubeadm：kubeadm certs renew all，然后按部署方式重启控制平面。静态 Pod 方式下可移动 /etc/kubernetes/manifests/*.yaml 到临时目录，等待 10 秒后移回。最后用 kubectl get nodes 验证。

支持续期特定证书，如 kubeadm certs renew apiserver、apiserver-kubelet-client、front-proxy-client、admin.conf。

etcd 证书续期

etcd 证书独立于 Kubernetes 证书。检查命令：

openssl x509 -in /etc/ssl/etcd/ssl/member-$(hostname).pem -noout -dates
openssl x509 -in /etc/ssl/etcd/ssl/admin-$(hostname).pem -noout -dates

通过 Kubespray 续期 etcd 证书：

ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml \
  --tags=etcd \
  -b

故障排查

遇到 x509: certificate has expired or is not yet valid：在控制平面执行 kubeadm certs renew all，重启 kubelet（systemctl restart kubelet），等待静态 Pod 启动后用 kubectl get nodes 验证。
遇到 x509: certificate signed by unknown authority：表示 CA 不匹配，属于信任链根本问题。可选方案为使用 reset.yml 重置并重新部署（会丢失所有数据），或执行 CA 轮换（高级操作，参考 Kubernetes CA 轮换文档）。CA 轮换复杂，操作不当可能破坏集群，应先在生产外环境测试。
kubectl 无法连接服务器且证书已过期：执行 kubeadm certs renew admin.conf，然后复制新 kubeconfig：cp /etc/kubernetes/admin.conf ~/.kube/config。

有效期与监控

Kubespray 默认大多数证书有效期为 1 年，CA 为 10 年。部署前可在 group_vars/k8s_cluster/k8s-cluster.yml 中通过 kube_cert_validity_duration: 365（天）修改。

提供 systemd 定时器与服务配置示例（k8s-cert-renew.timer 和 k8s-cert-renew.service），以及 Prometheus 告警规则示例：当 apiserver_client_certificate_expiration_seconds_bucket{le="604800"} > 0 时触发“7 天内过期”告警。还提供一个 bash 监控脚本示例 cert-check.sh，遍历 /etc/kubernetes/pki/*.crt，剩余天数少于 30 天时输出警告，可通过 cron 运行。

使用方式

该技能以操作指南形式提供命令与配置片段，适用于已用 Kubespray 部署的集群。使用时应根据实际 inventory 路径、节点角色和部署方式调整命令；涉及控制平面重启和证书续期的操作需谨慎执行。

适用场景

定期检查 Kubespray 集群证书过期时间。
在部署时启用证书自动续期。
证书已过期导致集群故障时进行紧急手动续期。
排查 x509 证书错误和 kubectl 连接失败问题。
配置证书过期监控与告警。

限制

不适用于初始部署和集群升级。CA 轮换属于复杂操作，文档明确警告可能破坏集群，需先非生产测试。文档中未提供除 Kubespray 默认有效期之外的更多平台或版本兼容性信息。