Rancher证书轮换过期导致不能访问UI问题处理

1. 问题背景

Rancher 管理平台在运行过程中，其内置的 Kubernetes 证书（包括 kube-apiserver、etcd、kubelet 等组件证书）会定期轮换。当证书轮换机制因版本升级、时间偏差或手动操作失误而失效时，证书过期会导致 Rancher UI 无法访问，用户访问时会遇到 502 Bad Gateway 、证书过期 或 连接被拒绝 等错误。

本文基于实际生产环境排障经验，梳理 Rancher 证书轮换过期导致 UI 无法访问的完整处理流程，涵盖问题定位、证书状态检查、手动轮换以及验证恢复等环节。

2. 问题现象与影响范围

证书过期后，Rancher UI 无法访问的典型表现包括：

浏览器访问 Rancher UI 时提示 502 Bad Gateway 或 504 Gateway Timeout。
通过 kubectl 访问 Rancher 所在集群时，提示 x509: certificate has expired or is not yet valid。
Rancher 的 cattle-system 命名空间下 Pod 反复重启，日志中出现 TLS handshake error 或 certificate expired 相关报错。
Rancher 的 rancher Deployment 无法正常就绪，Ingress 后端无可用 Pod。

影响范围通常包括 Rancher 管理面、下游集群的认证代理以及通过 Rancher 访问的 Kubernetes API。

3. 证书轮换机制概述

Rancher 使用 k3s 或 RKE 部署时，证书由对应组件自动管理。Rancher 自身的 TLS 证书（用于 UI 和 API 的 HTTPS 访问）以及集群内部组件证书（如 kube-apiserver 证书）都有各自的有效期。

证书轮换的常见触发方式包括：

Rancher 版本升级时自动轮换。
手动执行证书轮换命令。
证书即将过期时由集群组件自动续期。

当轮换流程中断或证书签发时间异常时，就会出现证书过期问题。

4. 问题定位与诊断

在动手处理之前，需要先确认证书过期的具体范围和影响组件。以下是推荐的诊断步骤。

4.1 检查 Rancher Pod 状态

bash 复制代码

kubectl get pods -n cattle-system

如果 rancher Pod 处于 CrashLoopBackOff 或 Pending 状态，需要进一步查看日志。

4.2 查看 Rancher 容器日志

bash 复制代码

kubectl logs -n cattle-system deployment/rancher --tail=200

日志中如果出现 x509: certificate has expired 或 tls: failed to verify certificate，基本可以确认证书过期。

4.3 检查证书有效期

登录到 Rancher 所在节点，使用 openssl 检查证书有效期：

bash 复制代码

openssl x509 -in /etc/kubernetes/ssl/kube-apiserver.pem -noout -dates

对于 k3s 部署，证书路径通常在 /var/lib/rancher/k3s/server/tls/ 目录下。

4.4 检查 Ingress 与负载均衡状态

bash 复制代码

kubectl get ingress -n cattle-system
kubectl get svc -n cattle-system

确认 Ingress 后端 Service 是否指向正常的 Pod，排除网络层问题。

5. 解决方案

根据部署方式不同，证书轮换的处理方法有所差异。以下分别针对 k3s 部署 和 RKE 部署 给出处理步骤。

5.1 k3s 部署的证书轮换

k3s 内置证书轮换命令，可以手动触发全部证书重新签发。

bash 复制代码

sudo k3s server --cluster-init

如果证书已经过期，需要先停止 k3s 服务，删除过期证书后重新启动：

bash 复制代码

sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/tls
sudo systemctl start k3s

重新启动后，k3s 会重新生成所有证书。如果 Rancher 安装在 k3s 之上，还需要重启 Rancher Deployment 使其重新加载证书：

bash 复制代码

kubectl rollout restart deployment/rancher -n cattle-system

5.2 RKE 部署的证书轮换

RKE 集群使用 rke cert rotate 命令进行证书轮换。在 RKE 配置文件所在目录执行：

bash 复制代码

rke cert rotate --config cluster.yml

该命令会轮换集群内所有组件证书。轮换完成后，需要更新本地 kubeconfig：

bash 复制代码

rke config --config cluster.yml

然后重启 Rancher Deployment：

bash 复制代码

kubectl rollout restart deployment/rancher -n cattle-system

5.3 仅轮换 Rancher 自身证书

如果只是 Rancher 的 TLS 证书过期，可以通过重新生成 Rancher 证书并重启服务解决。在 Rancher 所在集群中执行：

bash 复制代码

kubectl delete secret -n cattle-system rancher-tls
kubectl rollout restart deployment/rancher -n cattle-system

Rancher 会重新生成自签名证书。如果使用自定义证书，需要重新创建对应的 Secret。

6. 验证恢复结果

证书轮换完成后，需要验证 Rancher UI 是否恢复正常访问。

6.1 检查 Pod 状态

bash 复制代码

kubectl get pods -n cattle-system

确认 rancher Pod 处于 Running 且 READY 为 1/1。

6.2 检查证书有效期

bash 复制代码

openssl x509 -in /var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt -noout -dates

确认新证书的有效期已更新。

6.3 访问 Rancher UI

使用浏览器访问 Rancher UI 地址，确认页面正常加载，不再出现证书过期或 502 错误。

6.4 验证下游集群连接

在 Rancher UI 中检查下游集群状态，确认集群连接正常，认证代理工作正常。

7. 预防措施与最佳实践

为避免证书过期问题再次发生，建议采取以下预防措施：

定期检查证书有效期：通过脚本或监控工具定期检查 Rancher 及集群组件证书的到期时间，提前预警。
保持 Rancher 版本更新：及时升级 Rancher 到最新稳定版本，修复已知的证书轮换缺陷。
统一时间同步：确保所有节点启用 NTP 时间同步，避免因时间偏差导致证书签发异常。
制定应急预案：提前编写证书轮换的操作手册，明确各部署方式下的轮换命令和验证步骤。
备份证书与配置：在轮换前备份证书目录和 RKE 配置文件，便于回滚。

8. 总结

Rancher 证书轮换过期导致 UI 无法访问的问题，核心在于证书签发流程中断或证书有效期异常。通过检查 Pod 状态、查看日志、确认证书有效期，可以快速定位问题范围。根据部署方式选择对应的轮换命令，并在轮换后验证 UI 访问和下游集群连接，即可完成恢复。日常运维中加强证书有效期监控和版本管理，能有效降低此类故障的发生概率。