Rancher证书过期处理：从Helm安装到Ingress证书更新全攻略

上次帮某内部运维平台组处理Rancher证书过期，发现一个特别普遍的情况：大家清楚记得当初是用Helm装的Rancher，但问起当时选的是哪种证书来源、TLS Secret叫什么名字、有没有开启私有CA，没人说得清。等浏览器开始飘红告警，下游集群的Agent接连报x509证书校验失败，才手忙脚乱地开始研究怎么更新Ingress证书。

这篇文章把我这两年处理Rancher证书问题的实操经验完整盘一遍：先用Helm把Rancher装起来，覆盖证书来源选型、私有CA配置这些关键决策；再重点讲更新Ingress证书的完整链路——怎么换Secret、怎么让Nginx重新加载、什么时候要重启Rancher和Agent、更新后怎么验证。适合刚接手K8s集群准备部署Rancher的运维同学，也适合已经装上Rancher但证书快过期、正到处找文档的人。

1. 先搞清楚Rancher的Ingress证书从哪来：三种模式对应不同的维护节奏

1.1 证书不在Rancher手里，它挂载在Ingress层

很多第一次接触Rancher的朋友以为证书是Rancher自己生成、自己管理的。实际上，Rancher被Helm安装到cattle-system命名空间后，对外流量走的是一个标准的Kubernetes Ingress对象。浏览器访问https://你的域名时，TLS握手发生在这个Ingress对应的Ingress Controller上，证书内容存放在一个Kubernetes Secret里。也就是说，你更新证书的本质操作，是替换这个Secret，再让Ingress Controller重新加载。

这个认知非常关键，后面所有排查思路都从它延伸出来：为什么删了旧Secret、重建新Secret后页面还是旧证书？因为Nginx内存里还持有一份旧证书。为什么Rancher的Pod有时也要重启？因为CA变化时需要让Rancher重新挂载新CA。把"Ingress引用Secret、Secret里放证书"这条链路理清楚，问题就解决了一半。

1.2 三种证书来源：rancher、letsEncrypt、secret

Rancher的Helm Chart通过ingress.tls.source控制证书从哪来，我在实际项目里遇到的主要是三种：

注意，rancher和letsEncrypt两种模式依赖cert-manager，证书快到期时会自动续期，维护成本低。但自签证书不被浏览器信任，Let's Encrypt需要域名能通过公网验证。绝大多数企业正式环境用的是secret，向内部CA或第三方CA申请证书后手工放成Secret。这也解释了为什么"更新Ingress证书"这个需求如此常见——secret模式没有自动续期机制，完全靠人维护。

1.3 私有CA是大坑：别忘了还有一个CA Secret

用secret模式时，如果证书来自公司内部的私有CA，光有TLS Secret远远不够。Rancher要验证各集群Agent的证书连接，必须知道签发Ingress证书的那张CA证书。图表约定：在ingress.tls.secretName指定的名字后面加-ca，放一个key为cacerts.pem的Generic Secret。TLS Secret叫tls-rancher-ingress，CA Secret就叫tls-rancher-ingress-ca。

我在现场见过太多次这个坑：有人把证书换成正规CA签发的，大家很开心，结果过几天下游集群Agent开始CrashLoopBackOff，日志全是x509: certificate signed by unknown authority。原因就是CA Secret没同步更新，Agent不认新CA。后面更新证书时，叶子证书和CA证书必须一起判断有没有变化。

2. 安装前必须定下来的三件事：证书来源、域名和私有CA

2.1 证书来源怎么选：别图省事埋雷

我见过一个值得惋惜的案例：某公司测试集群部署Rancher时图方便用了默认的rancher自签模式，跑得很顺。后来想转正式环境，结果发现一堆Agent、环境变量、下游集群都绑定在旧证书上，切换成本比一开始就配好高得多。所以安装前就要想清楚，这个集群将来会不会纳入生产。

如果是企业正式环境，建议直接选secret，从第一天就用私有CA签发的证书。就算你觉得能应付，也别在内网环境用Let's Encrypt——域名无法公网验证，证书根本签发不下来。这个决策会影响后续所有证书维护动作，越早定下来越好。

2.2 域名和证书SAN：必须完全匹配

Rancher安装有一个hostname参数，这个值必须和Ingress证书的SAN完全匹配。浏览器访问https://rancher.xxx.com时，证书SAN里没有这个域名，HTTPS直接告警，Agent注册也会失败。

实操经验：向CA申请证书时，把主域名和可能用到的别名一并写进SAN。证书申请下来后，先本地验一遍再上传：

openssl x509 -in rancher.xxx.com.pem -noout -text | grep -A 1 "Subject Alternative Name"

我看到有人把证书做给了rancher.xxx.com，结果浏览器通过rancher.xxx.com:8443访问。端口无所谓，域名对得上就行；但如果是rancher-test.xxx.com，那就对不上了，浏览器和Agent都会不认。

2.3 私有CA要不要开启：决定Agent的信任链

secret模式下，证书是私有CA签发的，必须设置privateCA=true，并在安装前把CA Secret准备好。否则Rancher部署起来后，内部组件互相通信时用同一套CA校验，Agent连不上Server，UI能打开但集群一直处于Unavailable状态。

这里再强调一遍准备工作：安装之前先把两个Secret建好，Rancher的Helm Chart不会替你去创建。顺序错了后面全是莫名报错，排查起来特别耗时。

3. Helm安装Rancher实操：命令行与values.yaml两种姿势

3.1 环境准备清单

装Rancher之前，先确认这几样：

• Kubernetes集群可用，kubectl能正常访问集群
• Helm 3已安装，helm version能跑通
• Ingress Controller已就绪，例如ingress-nginx，并且有对应的Service或LoadBalancer地址
• 域名DNS已经解析到Ingress Controller地址

如果是首次使用Rancher的Chart仓库，先把仓库加上：

helm repo add rancher-stable https://releases.rancher.com/server-charts/stable helm repo update kubectl create namespace cattle-system

命名空间统一用cattle-system，这是Rancher官方的约定，别自己另起名字，否则很多默认配置和行为都会对不上。

3.2 先建两个Secret，再执行Helm安装

假设证书文件是rancher.xxx.com.pem和rancher.xxx.com.key，CA证书是ca.pem，按下面的顺序操作：

# 1. 创建TLS Secret kubectl -n cattle-system create secret tls tls-rancher-ingress \ --cert=rancher.xxx.com.pem \ --key=rancher.xxx.com.key # 2. 创建CA Secret（私有CA场景必做） kubectl -n cattle-system create secret generic tls-rancher-ingress-ca \ --from-file=cacerts.pem=ca.pem # 3. 用Helm安装 helm install rancher rancher-stable/rancher \ --namespace cattle-system \ --set hostname=rancher.xxx.com \ --set bootstrapPassword='Y0ur-Strong-P@ssw0rd!' \ --set ingress.tls.source=secret \ --set ingress.tls.secretName=tls-rancher-ingress \ --set ingress.tls.privateCA=true

bootstrapPassword是首次登录用的管理员密码。Rancher对密码强度有要求，至少12位，不能有连续3个相同字符，也不能是常见字典词。我习惯生成一个随机密码串，装完后再去UI里修改。

3.3 values.yaml写法：便于后期维护

命令行参数一多，后期不好维护。我通常在项目里保留一份values.yaml，顺着Chart文档把关键配置写清楚：

hostname: rancher.xxx.com replicas: 3 bootstrapPassword: 'Y0ur-Strong-P@ssw0rd!' ingress: tls: source: secret secretName: tls-rancher-ingress privateCA: true

安装命令简化为：

helm install rancher rancher-stable/rancher \ --namespace cattle-system \ --values values.yaml

这份values文件建议跟着项目放进代码仓库。等两年后需要查当初怎么配的证书，一条helm get values rancher -n cattle-system或者直接翻values文件，比靠回忆靠谱得多。顺便说一句，ingress.tls.privateCA这个字段在较新版本的Chart里是标准路径，如果你用的Chart版本不认，执行helm show values rancher-stable/rancher查一下真实字段名，以实际版本为准。

3.4 安装完成后的检查

安装完成不代表能立刻访问。先看状态：

kubectl -n cattle-system get pods -w kubectl -n cattle-system get ingress kubectl -n cattle-system get secret

Ingress对象出现、Rancher Pod变成Running后，用浏览器访问域名。首次打开会进入初始化页面，用它设置管理员密码和Server URL。如果页面直接正常打开，说明证书和CA配置基本没问题，后续就是正常的集群导入流程了。

4. 证书更新前的体检：用openssl查有效期和SAN，别漏了CA

4.1 先确认当前证书的真实状态

收到证书过期告警邮件，或者浏览器开始提示证书即将到期，第一件事不是急着换证书，而是确认现状。在集群里把Ingress引用的Secret翻出来看：

kubectl -n cattle-system get secret tls-rancher-ingress \ -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -dates -subject -issuer

输出里的notBefore和notAfter就是证书有效期，issuer能看到签发者，判断它是私有CA还是公共CA。另外两个信息很关键：

# 当前Ingress到底引用了哪个Secret kubectl -n cattle-system get ingress rancher -o yaml | grep -A 5 "tls:" # 当初Helm配的证书来源是什么 helm get values rancher -n cattle-system

这两条命令能帮你确认维护对象没错。我自己就遇到过Ingress引用的Secret名字和想象中完全不一样的情况，全靠这条排查才发现。

4.2 外部视角体检：模拟浏览器访问

集群内部看的是Secret内容，外部看的是实际下发给浏览器的证书。正常情况下两者一致，但偶尔会因为Nginx缓存、前置负载均衡等配置出现不一致。从一台能访问域名的机器上直接检查：

echo | openssl s_client -connect rancher.xxx.com:443 -servername rancher.xxx.com 2>/dev/null | openssl x509 -noout -dates -issuer -subject

如果外部看到的证书和集群里Secret的内容不一致，先别急着更新，要查明中间链路是不是还有别的证书在生效。有些团队在前面叠了一层负载均衡，证书终止在LB层而不是K8s Ingress层，那种环境下该更新的是LB证书，跟Secret无关。这个问题我在维护现场至少碰到过三次，每次都有人白折腾半天集群里的Secret。

4.3 判断更新范围：只有叶子证书变化，还是CA也变了

这一步是很多人忽略的。内部CA签发的证书临近过期，通常重新签发一张叶子证书，CA本身不变，此时只需要替换TLS Secret里的tls.crt和tls.key，CA Secret不用动。

但如果是公司证书体系整体迁移，比如从旧CA迁到新CA，那CA Secret也要一起替换，并且要重启Rancher和全部Agent。判断方法很简单：拿到新证书后，本地执行openssl x509 -in new-cert.pem -noout -issuer看签发者，和4.2里旧证书的issuer对比。完全一样，就只换叶子；不一样，就按全套流程走。

5. 更新Ingress证书的标准链路：换Secret、踢Nginx、滚重启Rancher

5.1 备份永远是第一步

替换Secret前，把旧Secret导出留底。万一新证书有问题，能快速回滚：

kubectl -n cattle-system get secret tls-rancher-ingress -o yaml > old-tls-secret.yaml kubectl -n cattle-system get secret tls-rancher-ingress-ca -o yaml > old-ca-secret.yaml

备份文件里含有私钥，注意别提交到公开仓库，也不要在群里传播。建议备份完先确认文件能正常读取，避免真到回滚时才发现备份损坏。

5.2 替换TLS Secret：用dry-run加apply，避免空窗

直接删除旧Secret再创建同名Secret是可行的，但会有一小段时间Ingress引用的Secret不存在，Nginx拿不到证书或直接拒绝连接。更稳的做法是利用create --dry-run=client生成对象，再apply覆盖：

kubectl -n cattle-system create secret tls tls-rancher-ingress \ --cert=rancher.xxx.com-new.pem \ --key=rancher.xxx.com-new.key \ --dry-run=client -o yaml | kubectl apply -f -

这样Secret的metadata不变，只换data里的证书内容，Ingress对象引用不受影响，操作基本无感知。

5.3 CA Secret同步更新

如果确认CA也变了，紧接着替换CA Secret：

kubectl -n cattle-system create secret generic tls-rancher-ingress-ca \ --from-file=cacerts.pem=new-ca.pem \ --dry-run=client -o yaml | kubectl apply -f -

5.4 让Nginx重新加载证书

Secret内容变了，但Ingress-nginx仍持有着旧证书。正常情况下它会监听Secret变化并自动reload，但我在实际运维中遇到过多次没自动更新的情况。为了确保生效，手动踢一下：

kubectl -n ingress-nginx rollout restart deployment ingress-nginx-controller

如果你的环境把ingress-nginx跑成DaemonSet，就把deployment换成daemonset。踢完稍等片刻，用4.2的openssl命令重新查外部证书，确认已经变成新证书。这一步是整个链路里最容易被忽略的，很多人换了Secret就跑去看页面，结果看到的还是旧证书，急得团团转。

5.5 Rancher和相关Agent的重启顺序

只有叶子证书变化、CA没变时，Rancher Server和Agent不需要重启。但CA变了，Rancher Server必须重启，让它重新挂载CA Secret：

kubectl -n cattle-system rollout restart deployment rancher

接着重启Agent组件。本集群的Agent是cattle-cluster-agent（Deployment）和cattle-node-agent（DaemonSet）：

kubectl -n cattle-system rollout restart deployment cattle-cluster-agent kubectl -n cattle-system rollout restart daemonset cattle-node-agent

如果接了导入的下游集群，还要去下游集群里同样操作一番，让下游Agent拿着新CA重新连接Rancher Server。这个顺序不能乱：先Rancher Server，再上游Agent，最后下游Agent。反过来操作，下游Agent会一直连不上正在重启的Server，白白拉长恢复时间。

5.6 为什么非要重启：Secret挂载的更新机制

这里解释下背后的原理。Rancher把CA Secret以Volume形式挂载进Pod。Secret被kubectl apply更新后，kubelet要等同步周期（默认60秒左右）才会把新内容写进Volume，而且某些情况下Pod里打开的文件句柄仍指向旧文件。rollout restart强制Pod重建，立即挂载最新Secret，省去等待，也避免读到旧文件。

Nginx同理。TLS证书被加载进内存，单纯更新Secret文件不会立刻改写Nginx内存里的证书链，必须重新加载配置或重建Pod，才会用新证书完成TLS握手。理解这个机制之后，你就明白为什么"只换Secret"往往不够了。

6. 更新完不等于结束：验证清单与三种常见回退场景

6.1 验证清单，按顺序过一遍

更新操作做完，按这个清单逐项验证，全部通过才算完事：

# 1. 集群内Secret里的证书有效期 kubectl -n cattle-system get secret tls-rancher-ingress \ -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -enddate # 2. 外部实际下发的证书及有效期 echo | openssl s_client -connect rancher.xxx.com:443 -servername rancher.xxx.com 2>/dev/null | openssl x509 -noout -dates -issuer # 3. Rancher API可访问 curl -k https://rancher.xxx.com/v3

/v3接口正常返回JSON，里面能看到Rancher版本号，说明后端服务正常。浏览器打开管理页面，确认地址栏的证书锁图标正常，不再有红色警告。然后进集群列表逐项看：本地集群状态是Active，下游集群状态是Active，每个集群下的节点状态都是Healthy。

如果下游集群出现Unavailable或节点变成Unhealthy，基本就是CA同步的问题，回到5.5核对重启顺序和范围。

6.2 更新后还是旧证书，先查这两个地方

更新完发现浏览器里还是旧证书，优先检查两处。

第一，Nginx是否真的重新加载了。用4.2的openssl命令查外部握手证书，如果还是旧证书，再看Ingress引用的Secret名字对不对、内容对不对。都不对就回到5.4，确认restart命令执行成功。

第二，集群前面是不是还有一层独立的负载均衡或网关。很多公司会在K8s前面再叠一层Nginx或硬件LB，证书终止在最外层，这种情况下集群里的Secret换了也没用，要去改最外层那台设备的证书配置。

6.3 Agent不断CrashLoopBackOff，检查CA信任链

更新后出现x509: certificate signed by unknown authority这类日志，说明新CA没被Agent信任。检查顺序：

kubectl -n cattle-system logs deployment/cattle-cluster-agent --tail=50 | grep -i x509

可能的修复路径：

• 确认CA Secret的名字和key是否正确，Rancher约定key必须是cacerts.pem
• 确认Rancher Server是否挂载新CA，执行kubectl -n cattle-system get deploy rancher -o yaml检查相关volumeMounts
• 重新执行5.5里的Agent重启命令

6.4 快速回滚方案

新证书有问题需要回滚，直接把5.1备份的旧Secret重新apply回去：

kubectl apply -f old-tls-secret.yaml kubectl apply -f old-ca-secret.yaml kubectl -n ingress-nginx rollout restart deployment ingress-nginx-controller kubectl -n cattle-system rollout restart deployment rancher

经验是备份文件一定留到所有验证通过后再清理，别刚换完就删。很多团队吃了这个亏才长记性。

6.5 后面的自动化思路

这套手动流程跑顺之后，可以加一道保险：用脚本定期检查证书剩余天数，到期前30天发告警。简单版就是cron里跑一行openssl命令，复杂版可以把证书内容放到密钥管理系统，配合证书签发流程做成半自动。对大多数团队而言，先把这次的手动链路走熟，再谈自动化，是最务实的路径。

最后再分享一点个人体会。Rancher的证书维护，技术层面的难度其实不在Helm命令，也不在OpenSSL的用法，而在能不能想清楚证书到底挂在哪一层。是挂在K8s Ingress，还是挂在前置LB，决定了你要改的地方可能差出十万八千里。把"Ingress引用Secret、Secret里放证书、CA单独一个Secret、Agent靠它建立信任链"这条链路理清楚，后面不管是换证书还是排查问题，都会顺很多。希望这篇文章能帮你少走我之前走过的弯路。