Rancher证书更新实战：从入口HTTPS到下游K8s集群全攻略

干运维这些年Rancher 证书过期这事儿我前前后后碰到过不少次每次都是先把浏览器打开看一眼证书错误然后顺着链路一层层查下去。Rancher 的证书更新之所以总让人头大是因为它不像普通网站那样换张证书就行它内部至少有三套证书在同时工作UI 入口一套、Rancher 自己签发下游集群的 CA 一套、每个下游集群的 kubelet 和 etcd 又是一套任何一套出了问题表现症状完全不一样。这篇文章我把 Rancher 证书更新的常见场景、实操步骤和踩坑经验完整整理一遍主要针对 Rancher v2.6 及以上版本Helm 部署和 Docker 单容器部署都会覆盖适合正在维护 Rancher 平台、或者已经被证书问题折磨过的同行参考。顺便说一句很多人搜“证书更新”时会把 Rancher 和 esxi 主机证书、vCenter 6.7 证书更新混在一起看这其实是完全不同的两套体系vCenter 那套用的是 VMCA 证书结构Rancher 这边走的是 Kubernetes 的 CSR 和 ingress secret 体系思路不能通用我这边只围绕 Rancher 展开。1. Rancher 证书体系先梳理清楚1.1 三类主要证书与它们各自的作用先别急着动手搞清楚 Rancher 到底有哪些证书在跑这是所有操作的前提。我从实际维护角度把 Rancher 的证书分成三类。第一类是 Rancher Server 自己的 HTTPS 证书也就是你在浏览器里访问https://rancher.example.com时用的那张证书。它由访问入口的 Ingress Controller 加载Rancher 本身在里面扮演的只是一个后端服务。这张证书可以是 Rancher 安装时自动生成的自签证书也可以是你自己申请的商业证书或私有 CA 签发的证书。大多数生产环境想换的就是这张因为它有明确的过期时间过期后你连管理界面都登不进去所有业务方都会来催你。第二类是 Rancher 用来管理下游集群的 CA 证书。Rancher Server 在初始化时会生成一套自己的 CA用它去签发下游集群 agent 连接时用到的客户端证书。这套 CA 的有效期通常特别长默认十年但正因为有效期长很多人把它给忘了。一旦这套 CA 出问题所有下游集群的连接都会异常集群列表里一片红的。第三类是下游 Kubernetes 集群内部的组件证书包括 kube-apiserver、etcd、kubelet、controller-manager、scheduler 等组件之间的通信证书还有你执行kubectl时用的 kubeconfig 里的客户端证书。这类证书的有效期一般是一年或半年到期后不影响 Rancher 界面本身但会出现集群状态同步失败、节点 NotReady、执行 kubectl 报 x509 错误等问题。这三类证书混在一起症状却完全不同所以排查的第一步永远是确认“到底是哪一类证书出了问题”而不是看到一个证书报错就盲目重签。1.2 为什么“证书更新”不是重新签一个那么简单刚开始接触 Rancher 的时候我也天真过以为证书过期就是把新证书传上去、重启一下服务就完事。实际上 Rancher 的证书更新牵扯到一条完整的信任链。Rancher 在安装的时候不管是 Helm 还是 Docker 方式都会把 hostname、证书配置这些参数固化在它的配置里。你更新证书时不只是替换一个文件还要保证新证书里的 SAN 包含 hostname保证私钥格式能被直接加载保证如果是私有 CA 签发的证书Rancher 的 agent 在连接时也能信任这个 CA。任何一个环节没对上就会形成“证书看起来换了但集群还是报错”的诡异状态。另外Rancher 的证书更新有一个很隐蔽的点如果你用的是 ingress 方式暴露那么真正终止 TLS 的是 nginx ingress controllerRancher pod 内部走的反而是 HTTP。这意味着你更新证书后有时候要等 ingress controller 重新加载才能生效不是重启一下 Rancher 就万事大吉。明白了这些后面每一步操作才有意义。2. 核心场景Rancher UI/API 的 HTTPS 证书更新2.1 先定位证书来源你是哪种部署方式处理 HTTPS 证书更新前先登录到服务器上确认你的 Rancher 是怎么装的这决定了后面的命令完全不同。最常见的两种方式是 Helm 方式Rancher 跑在 Kubernetes 集群里和 Docker 单容器方式。检查方法很简单# Helm 部署方式能看到 cattle-system 命名空间下的工作负载 kubectl -n cattle-system get svc rancher kubectl -n cattle-system get pods # Docker 部署方式宿主机上能看到 ranche 容器 docker ps | grep rancher/rancher如果你能看到命名空间和 pod那就是 Helm 或者 kubectl 方式装的如果只看到 docker 容器那就是单容器部署。还有一种更老的方式是 Rancher 跑在 RKE 集群里但老版本大多已经升级到 Helm 模式了这里不做展开。判断出部署方式之后再看当前的证书来源。Helm 方式下证书信息都对应在cattle-system命名空间的 secret 中tls-rancher-ingress这个 secret 就是入口证书相关内容我在 2.2 小节展开。Docker 方式下证书直接以文件形式挂载在容器里路径通常是/etc/rancher/ssl/下的.pem和.key文件。这一步骤的核心价值在于别对着错误的路径去操作否则你会觉得明明改了文件Rancher 却一点反应都没有。2.2 Helm 部署下更新自定义证书的完整流程Helm 模式下Rancher 的 HTTPS 证书最终由 nginx ingress controller 加载证书内容存放在tls-rancher-ingress这个 secret 里。更新证书的正确流程是先更新 secret再让 Rancher 重新加载配置最后验证生效。先看看当前证书的过期时间确认问题kubectl -n cattle-system get secret tls-rancher-ingress -o jsonpath{.data.tls\.crt} | base64 -d | openssl x509 -noout -dates -subject -issuer看到输出里的notAfter日期之后准备新的证书文件。我这里建议把你的证书文件整理成三个fullchain.pem包含域名证书和中间证书的完整链、privkey.pem私钥以及可选但强烈建议的ca.pem根 CA 证书如果用的是私有 CA 签发。然后更新 secret我这里用--dry-runclient -o yaml | kubectl apply -f -的方式避免直接删除 secret 造成短暂的服务中断kubectl -n cattle-system create secret tls tls-rancher-ingress \ --certfullchain.pem \ --keyprivkey.pem \ --dry-runclient -o yaml | kubectl apply -f -如果证书是由私有 CA 签发的还需要同步更新 CA 配置Rancher 管这个 secret 叫做tls-ca里面的 key 名必须是cacerts.pemkubectl -n cattle-system create secret generic tls-ca \ --from-filecacerts.pemca.pem \ --dry-runclient -o yaml | kubectl apply -f -接下来重新应用 Helm 配置。很多人到这里会漏掉一个关键步骤直接看当前 Rancher 的 Helm values确保升级时不会把原有的 hostname、复制数、日志级别这些参数冲掉。先执行helm -n cattle-system get values rancher把这个输出保存下来然后在 helm upgrade 的时候把关键参数补全。一个典型命令如下helm upgrade rancher rancher-latest/rancher -n cattle-system \ --set hostnamerancher.example.com \ --set ingress.tls.sourcesecret \ --set ingress.tls.secretNametls-rancher-ingress \ --set privateCAtrue \ --set tlsCaSecretNametls-ca \ --set replicas3如果证书是从公开 CA比如 Lets Encrypt申请的就不需要设置privateCA和tlsCaSecretName这两个参数。等 helm upgrade 完成再重启 Rancher 的 deployment让进程重新读取证书配置kubectl -n cattle-system rollout restart deploy/rancher kubectl -n cattle-system rollout status deploy/rancher这里有个细节很多人不知道因为证书最终由 nginx ingress controller 加载Rancher pod 重启后有时候你打开浏览器还是会看到旧证书这时候别急等 nginx controller 重新同步 secret 即可一般秒级到几十秒不等。你可以看一下 ingress-nginx 所在命名空间的 controller pod 日志出现updating secret之类的字样说明已经在加载了。2.3 Docker 单容器部署下的证书替换Docker 单容器部署的 Rancher 虽然安装方式老但存量用户并不少很多小环境还在用它跑。单容器模式下Rancher 对外服务的证书不是放在 secret 里而是以挂载卷的形式直接映射到容器内默认路径是/etc/rancher/ssl/下的.pem和.key文件文件命名一般跟随 hostname比如rancher.example.com.pem和rancher.example.com.key。更换证书的思路是保留数据卷、扔掉容器、换新证书后重新创建容器。先把原容器停掉并改名备份防止操作失败时连回退的机会都没有docker stop rancher docker rename rancher rancher-bak-$(date %Y%m%d)然后把新证书放到宿主机目录例如/data/rancher-ssl/再重新创建容器。这里要注意映射路径必须保持/etc/rancher/ssl/下文件名包含 hostnameRancher 在启动时是通过 hostname 来找对应证书文件的docker run -d --restartunless-stopped \ --name rancher \ -p 80:80 -p 443:443 \ -v /data/rancher:/var/lib/rancher \ -v /data/rancher-ssl/rancher.example.com.pem:/etc/rancher/ssl/rancher.example.com.pem \ -v /data/rancher-ssl/rancher.example.com.key:/etc/rancher/ssl/rancher.example.com.key \ -v /data/rancher-ssl/ca.pem:/etc/rancher/ssl/cacerts.pem \ rancher/rancher:v2.7.9如果是公开 CA 签发的证书不需要挂载cacerts.pem。启动后等一两分钟打开浏览器访问 hostname确认证书更新成功。如果确认没问题就可以删掉之前的备份容器如果新证书有问题直接改回原命名启动备份容器即可数据卷没动过回退很干净。Docker 模式更新证书的核心经验是数据卷/var/lib/rancher绝对不能动一定要原样挂载到新容器上。我之前见过有人图省事直接把整个 Rancher 目录复制到新机器结果权限和路径状态不对Rancher 起来后一堆集群失联处理起来比证书过期本身还麻烦。2.4 证书更新后的生效验证证书换完了别急着宣布完成我习惯做三步验证。第一步用 openssl 直接验证服务端口上的证书信息确认线上已经变成新证书echo | openssl s_client -connect rancher.example.com:443 -servername rancher.example.com 2/dev/null | openssl x509 -noout -dates -subject -issuer第二步打开浏览器访问页面确认地址栏证书状态正常F12 看一下页面里的 API 请求没有证书相关的报错。这一步能发现一些 openssl 验证发现不了的问题比如页面二次加载时内部调用仍然走了旧的 CA。第三步检查 Rancher 的 local 集群状态执行kubectl get nodes确保 Rancher 管理面本身没有因为证书更换而出现 agent 连接异常。如果这三步都正常证书更新才算真正完成。如果第一步能看到新证书但页面还是报错十有八九是浏览器缓存了旧的证书连接换个无痕窗口再试一般能定位出来。3. Rancher 内部自签 CA 证书的处理3.1 默认自签证书的有效期与检查很多生产环境图省事安装 Rancher 时没配自定义证书直接用 Rancher 默认生成的自签证书。这个自签证书不是随随便便一签就完事的Rancher 会生成一套自己的 CA并用这套 CA 去签发 HTTPS 证书。这套自签 CA 的有效期一般十年起步很多团队从部署到交接都没人注意过它等发现问题的时候往往已经是“页面完全打不开”的状态。检查自签证书有没有快到期方法和查自定义证书一样重点看 secrettls-rancher-ingress里的证书信息kubectl -n cattle-system get secret tls-rancher-ingress -o jsonpath{.data.tls\.crt} | base64 -d | openssl x509 -noout -dates -subject -issuer看输出里的notAfter如果距离当前时间不足三个月我建议直接安排更新窗口。自签证书的更新窗口选在业务低峰期就好处理过程本身不复杂但不要在业务高峰去抢这个风险。还有一点容易忽略Rancher 自签证书对系统时间非常敏感。如果服务器时间漂移了哪怕证书实际上还有效浏览器也会报“证书尚未生效”或“证书已过期”这时候不要急着重签证书先把系统时间和 NTP 同步修好再说具体我在 3.3 小节展开。3.2 自签 CA 证书到期后的重建方案自签证书如果确认已经到期最直接的处理办法是让 Rancher 重新生成一套。前提是你确认 ingress 的 tls 来源是rancher默认自签而不是secret或letsEncrypt这个可以从安装时的 Helm values 看出来helm -n cattle-system get values rancher | grep -A5 ingress如果tls.source是secret说明走的是自定义证书那就参考第 2 章的流程如果是rancher就可以用下面的方式重建。Helm 部署模式下入口证书 secret 是 Rancher 在安装或启动时自动创建的。你可以把现有的tls-rancher-ingresssecret 删除然后重启 Rancher它会在启动时重新生成一套自签证书kubectl -n cattle-system delete secret tls-rancher-ingress kubectl -n cattle-system rollout restart deploy/rancherRancher 进程起来后会自动创建新的 self-signed 证书 secret有效期从当前时间重新计算。整个过程会短时间造成 UI 不可访问所以要在维护窗口做。Docker 单容器部署模式下自签证书是 Rancher 容器启动时按 hostname 生成的。重建方法是保留数据卷、删掉旧证书文件、删除容器重新运行。运行命令和 2.3 小节类似区别在于不要挂载任何自定义证书文件让 Rancher 完全走默认自签逻辑。容器一旦启动检测到/etc/rancher/ssl下没有对应 hostname 的证书就会自动生成新的自签证书。这里必须提醒一件事删除证书 secret 或证书文件后Rancher 底层所有关联的 agent 连接都会被重置。下游集群的 agent 会拿着旧 CA 签发的客户端证书来找 Rancher证书校验失败后会自动重试通常几分钟内能恢复。但如果你的下游集群数量比较多恢复时间会拉长别慌张耐心等 agent 重连即可。3.3 系统时间异常触发的“证书未生效”处理这应该是 Rancher 证书问题里最坑的一类。有次客户报障说 Rancher 页面打不开浏览器提示证书过期我远程上去一看证书的notBefore是三个月后也就是说证书是未来的还没生效。再一查服务器时间系统时间整整快了半年。时间漂移会让自签证书的校验彻底乱套Rancher 内部组件之间的证书校验依赖时间窗口任何一方的时间偏差都会导致 x509 校验失败。这种情况下的正确姿势是先把系统时间校准。先用 NTP 同步时间不同发行版命令不同我这里以常见的 systemd-timesyncd 和 chrony 为例# 使用 chrony 的 sudo chronyc makestep # 使用 systemd-timesyncd 或直接 ntpdate sudo timedatectl set-ntp true sudo ntpdate -u ntp.aliyun.com时间恢复正常后Rancher 的自签证书如果之前生成时处于错误时间窗口证书本身的notBefore和notAfter可能都是错的这时候需要按照 3.2 小节的方案删掉 secret 让 Rancher 重新生成。排查这种问题有个快捷方法用 openssl 查看证书的validity再和系统当前时间对比如果notBefore在未来就是时间串了。不要先动证书先调时间顺序反过来很容易白忙一场。4. 下游 K8s 集群的证书更新与恢复4.1 在 Rancher UI 中轮换下游集群组件证书Rancher 管理的下游集群Kubernetes 组件之间的证书一样有有效期。kubelet 的证书一般一年一轮etcd、kube-apiserver 这些证书有效期也不长。这些证书一旦到期最常见的表现是集群状态变成Unavailable节点状态异常或者 Rancher 页面里看不到节点信息。Rancher 对下游集群提供了证书轮换功能不过入口藏得比较深UI 上在集群的编辑配置里不同 Rancher 版本叫法不太一样比较新的版本在集群的“高级选项”或者单独的证书管理入口里能找到一个 “Rotate Certificates” 的按钮。点击时可以选择轮换范围只轮换kubelet、etcd、controller-manager、scheduler或者全部一起轮换。轮换kubelet证书是最安全的基本不影响业务。轮换etcd证书会触发 etcd 节点重启短时间内会有写入抖动一定要错开业务高峰。轮换all更是会把 apiserver 也跟着重启整个集群的 API 会短暂不可用执行前务必确认这个窗口期可以接受。如果你不方便进 UI也可以直接用 Rancher 的 API 触发轮换。用https://rancher-server/v3/clusters/cluster-id?actionrotateCertificates接口请求体里带上要轮换的组件类型。我一般只建议 RKE 类型的托管集群走 API导入的集群在 API 里对证书轮换的兼容性参差不齐出了问题难排查不如 UI 稳。4.2 集群失联后的应急恢复顺序证书更新过程中最容易出现的大事故是证书动了所有下游集群全失联了。这时候不要慌按顺序处理。首先确认 Rancher Server 本身是否正常能打开 UI、能看到 local 集群说明 Rancher 管理面是好的问题出在下游连接链路。接着去 Rancher 所在集群执行下面的命令看 agent 的运行状态kubectl -n cattle-system get pods -o wide找到cattle-cluster-agent或cattle-agent相关的 pod看日志里有没有x509、certificate expired、CSR这些关键词kubectl -n cattle-system logs -f agent-pod如果确认是证书过期需要在下游集群的 kube-system 相关命名空间里查看有没有 pending 状态的 CertificateSigningRequest。新证书申请通常以 CSR 的形式提交给 apiserver由 Rancher 侧自动审批但有时审批流程卡住需要手动处理kubectl get csr | grep Pending kubectl certificate approve csr-name审批通过后重启下游集群的 agent pod让它重新建立连接。RKE 自建集群一般通过 Rancher UI 重新生成 kubeconfig 并覆盖 agent 配置。整个恢复过程可能需要五分钟到半小时取决于集群规模和网络状况。这里再强调一个恢复时的关键点如果 Rancher 是在 Kubernetes 里跑的并且 local 集群本身就是 Rancher 用 RKE2 或 k3s 搭的那么在 local 集群失联时你还可以直接 SSH 到控制面节点上用节点本地的 admin kubeconfig 来操作集群路径一般在/etc/rancher/rke2/rke2.yaml或/etc/rancher/k3s/k3s.yaml。这个 kubeconfig 是节点本地生成的不受 Rancher 证书影响用来救急非常有效我从几次真实事故里总结出来的经验关键时刻能救命。5. 常见问题与排查技巧实录5.1 高频故障速查表下面把我在实际运维中遇到过的证书相关问题整理成一张速查表每一条都是真实踩过的坑可以直接对照症状找解决办法。现象可能原因处理办法浏览器显示“证书过期”或“不安全”Rancher 入口 HTTPS 证书过期按第 2 章或第 3 章流程更新证书浏览器提示“证书尚未生效”服务器系统时间漂移先校准 NTP 时间再重建自签证书Rancher 页面能开但集群列表一片红下游集群 agent 连接证书过期查看 agent 日志重启 agent手动 approve CSR执行 kubectl 报 x509 certificate signed by unknown authority本地 kubeconfig 里的 CA 证书和集群 CA 不匹配从 Rancher UI 重新下载 kubeconfig替换本地文件节点状态 NotReadykubelet 证书过期在 Rancher UI 轮换 kubelet 证书重启对应节点 kubelet更新证书后页面仍显示旧证书ingress controller 未重新加载 secret等待几十秒或重启 nginx ingress controller pod更新证书后集群 agent 反复重启私有 CA 证书未同步到 Rancher确认tls-casecret 里的cacerts.pem是最新的重新 helm upgradeRancher UI 能进但 API 返回 401Rancher 内部 API 证书过期重启 Rancher deployment必要时重建 tls-rancher-ingress secret这张表看起来简单但每一条背后都对应一个具体的操作链路处理时建议把对应的章节步骤完整读完再动手避免头疼医头。5.2 我踩过的坑和习惯做法最后分享几个我个人长期养成的习惯不一定每条都适合所有环境但能帮你省掉不少麻烦。第一给证书过期时间做监控不要等业务方来催。最简单的办法就是在定时任务里跑一行 openssl 命令检查 Rancher 入口证书和集群 agent 证书的剩余有效期剩余不足 30 天时发告警。不需要上多复杂的监控系统cron 加 shell 脚本就够用。第二更新证书前务必留好备份。Helm 部署先记录当前 helm values出问题可以按原参数回滚Docker 部署先改容器名或复制数据卷确保能随时回退。我见过太多人图快直接删除重建结果新证书有问题旧的又找不回来只能临时申请新证书整个窗口期被拉长好几倍。第三证书更新不是一台机器的操作是一次全链路检查。Rancher 入口证书、Rancher 内部 CA、下游集群的 kubelet 证书、kubeconfig 客户端证书每一层都要确认一遍因为任何一个环节的残留问题都会在下次业务流量高峰时突然爆发。我习惯每次更新完证书后把第 2.4 小节的验证步骤完完整整走一遍连 kubeconfig 都重新下载替换不给自己留隐患。Rancher 证书更新这件事说难确实难在三套证书体系交织说简单也确实简单本质上就是“确认来源、备份、替换、验证”四个步骤只是每套证书每一步的入口不一样。把本文的流程走一遍下次再遇到证书问题你应该不会再对着浏览器上的红色警告发愁了。