1. 版本升级前的整体规划与思路拆解Rancher 作为主流的容器管理平台版本迭代节奏一直比较快。从 2.5 到 2.6、2.7、2.8每个大版本都会带来底层 Kubernetes 版本支持范围的变化、UI 重构、API 调整甚至某些组件的彻底移除。我经历过好几次跨版本升级有顺利的一把过也有半夜回滚的惨痛教训。这篇文章就把我踩过的坑和总结出来的流程完整梳理一遍给准备动手升级的朋友一个可参考的路线图。先说清楚适用对象如果你正在维护一套 Rancher 管理集群管理着若干下游业务集群现在需要把 Rancher 从旧版本升到新版本那这篇内容就是写给你的。不管你是刚接手运维的新手还是已经管过几十个集群的老手升级前的规划逻辑和检查清单都是通用的。升级这件事最核心的原则只有一条永远不要在生产环境直接操作先在测试环境完整走一遍。听起来像废话但我见过太多人因为“就升一个小版本应该没事”而翻车的案例。Rancher 的升级涉及管理集群自身的组件、下游集群的 agent、以及各种 CRD 和 webhook任何一个环节出问题都可能导致管理面不可用进而影响所有下游集群的日常运维。1.1 为什么 Rancher 升级不能“一键搞定”很多人习惯用包管理工具的思路来理解升级觉得换个镜像 tag 重启一下就行了。Rancher 的架构决定了它比普通应用复杂得多。管理集群里跑着 rancher-server、rancher-webhook、fleet、cattle-cluster-agent 等一堆组件下游集群里还有各自的 cluster-agent 和 node-agent。升级过程中管理面和数据面的版本需要匹配否则 agent 连不上 server集群状态就会变成 Unavailable。另外Rancher 的每个大版本对 Kubernetes 的版本支持是有窗口的。比如 Rancher 2.7 支持的 K8s 版本范围是 1.24 到 1.26到了 2.8 就变成了 1.25 到 1.27。如果你管理集群的 K8s 版本太老升级 Rancher 之前必须先升 K8s否则新版本 Rancher 根本不兼容。这个依赖关系必须在规划阶段就查清楚不能等到升级当天才发现。还有一个容易被忽略的点Rancher 的升级路径是有要求的。官方支持的是逐个小版本升级比如 2.6.x 先升到 2.7.x再升到 2.8.x。跨大版本直接跳比如从 2.6 直接上 2.8虽然有时候能成功但出问题的概率会明显增大。我个人的建议是老老实实按版本顺序来每一步都验证通过再走下一步。1.2 升级方案选型在线升级还是离线升级Rancher 的升级方式主要分两种在线升级和离线升级。在线升级适合管理集群能访问外网的情况直接改 Helm chart 的版本号或者用 Docker 换镜像 tag 就行。离线升级则需要提前把新版本的镜像同步到内网 registry然后修改配置指向内网地址。选哪种方式取决于你的网络环境。如果管理集群有稳定的外网出口在线升级最省事。但要注意Rancher 升级过程中需要拉取不少镜像如果网络不稳定拉取超时会导致升级卡住。我一般会提前把需要的镜像手动 pull 到本地或者用私有 registry 做缓存这样升级过程会顺畅很多。离线升级的准备工作更重一些但胜在可控。你需要用 Rancher 提供的rancher-save-images.sh脚本把新版本所有镜像导出成 tar 包传到内网后再用rancher-load-images.sh导入。这个过程比较耗时尤其是镜像多的时候可能要跑一两个小时。但好处是升级时不需要依赖外网速度稳定。提示不管选哪种方式升级前一定要备份管理集群的 etcd 和 Rancher 的 CRD 数据。etcd 备份是最后的保命手段万一升级失败还能回滚到快照。1.3 升级窗口和回滚预案的制定升级窗口的选择很关键。虽然 Rancher 升级过程中管理面会短暂不可用但下游集群的业务 Pod 不会受影响因为业务负载跑在下游集群里不依赖管理面的实时连接。不过升级期间你没法通过 Rancher UI 操作下游集群所以最好选业务低峰期操作。回滚预案必须提前写好。Rancher 的回滚不像普通应用换个镜像那么简单因为升级过程中会修改数据库 schema 和 CRD。如果升级到一半失败想回滚到旧版本可能需要恢复 etcd 快照这意味着管理集群会回到升级前的状态升级期间的所有变更都会丢失。所以回滚预案里要明确什么情况下决定回滚、回滚的具体步骤是什么、谁来执行、预计耗时多久。我一般会把回滚决策点设在“升级后 30 分钟内核心功能不可用”这个条件上。如果升级完成 30 分钟后下游集群状态还是 Unavailable或者 UI 无法正常加载就果断回滚不要抱着“再等等可能就好了”的心态。2. 升级前的环境检查与备份实操规划做完之后下一步就是动手检查环境。这一步做得越细升级过程中遇到的意外就越少。我习惯把检查项分成三类版本兼容性检查、集群健康检查、备份完整性检查。每一类都有具体的命令和验证标准下面逐一说明。2.1 版本兼容性检查别让 K8s 版本成为拦路虎Rancher 每个版本对 Kubernetes 的支持范围都在官方文档的“支持矩阵”里写着。升级前第一件事就是确认当前管理集群的 K8s 版本是否在新 Rancher 版本的支持范围内。查看管理集群 K8s 版本的方法很简单kubectl version --short输出里会显示 Server Version那就是管理集群的 K8s 版本。然后对照目标 Rancher 版本的兼容性矩阵。如果当前 K8s 版本低于新 Rancher 要求的最低版本就必须先升级 K8s。升级 K8s 又是另一个大工程需要单独规划。除了 K8s 版本还要检查 Rancher 自身的版本。用 Helm 部署的 Rancher可以用以下命令查看当前版本helm list -n cattle-system输出里的 CHART 列会显示 rancher 的版本号。如果是用 Docker 单容器部署的用docker ps找到 rancher 容器看镜像 tag 就行。还有一个容易漏掉的检查项下游集群的 agent 版本。Rancher 升级后下游集群的 agent 会自动升级到匹配版本但如果某个下游集群长时间离线agent 可能升不上去导致升级后连不上。所以升级前要确认所有下游集群都是 Active 状态没有 Unavailable 或 Reconciling 的。2.2 集群健康检查确保升级前一切正常升级前管理集群必须是健康的否则升级只会把问题放大。我通常会跑一遍以下检查所有节点 Readykubectl get nodes确保没有 NotReady 的节点。所有系统 Pod Runningkubectl get pods -A重点看 cattle-system、kube-system、ingress-nginx 这几个命名空间。etcd 健康如果管理集群是 RKE 部署的可以用rke etcd snapshot-list查看快照状态如果是 RKE2 或 K3s检查 etcd 或 datastore 的健康状态。证书有效期Rancher 的 webhook 证书和 ingress 证书如果快过期了升级前最好先续期避免升级后证书过期导致服务不可用。这些检查看起来琐碎但每一条都对应着我实际遇到过的问题。比如有一次升级后 UI 打不开排查半天发现是 ingress 证书过期了跟升级本身没关系但升级过程中重启了 ingress controller把问题暴露出来了。2.3 备份操作etcd 快照和 Rancher 数据导出备份是升级前最重要的一步没有之一。Rancher 的备份分两个层面管理集群的 etcd 快照以及 Rancher 自身的 CRD 数据导出。etcd 快照的创建方式取决于你的管理集群类型。RKE 集群可以用rke etcd snapshot-save --name pre-upgrade-snapshot --config cluster.ymlRKE2 集群可以用rke2 etcd-snapshot save --name pre-upgrade-snapshotK3s 集群类似k3s etcd-snapshot save --name pre-upgrade-snapshot快照创建后确认文件存在且大小合理。我一般会把快照文件额外复制一份到远程存储防止本地磁盘故障。Rancher 数据导出主要是备份 CRD 对象比如 clusters、projects、users 等。可以用kubectl get把关键 CRD 导出成 yamlkubectl get clusters.management.cattle.io -o yaml clusters-backup.yaml kubectl get projects.management.cattle.io -o yaml projects-backup.yaml kubectl get users.management.cattle.io -o yaml users-backup.yaml这些备份在回滚时不一定用得上但万一升级后数据出现异常可以用来对比排查。注意etcd 快照恢复会覆盖整个管理集群的状态包括升级期间的所有变更。所以恢复快照是最后的手段执行前要确认没有其他办法了。3. 升级过程的核心环节与实操记录环境检查和备份做完就可以开始升级了。这一部分我按在线升级的流程来写离线升级的差异会在关键步骤里说明。整个升级过程大概需要 15 到 30 分钟具体取决于镜像拉取速度和集群规模。3.1 Helm 方式升级 Rancher Server如果你的 Rancher 是用 Helm 部署的升级就是更新 Helm release 的 chart 版本。首先添加 Rancher 的 Helm repohelm repo add rancher-stable https://releases.rancher.com/server-charts/stable helm repo update然后查看当前 release 的 values确认升级时要保留的配置helm get values rancher -n cattle-system把输出的 values 保存下来升级时要用同样的配置只改版本号。接下来执行升级helm upgrade rancher rancher-stable/rancher \ --namespace cattle-system \ --version 2.8.3 \ --values values.yaml \ --set hostnamerancher.example.com \ --set replicas3这里的--version指定目标版本--values指定之前保存的配置文件。升级命令执行后Helm 会创建新的 rancher-server Pod等新 Pod Ready 后旧 Pod 会被终止。升级过程中可以用以下命令观察 Pod 状态kubectl get pods -n cattle-system -w正常情况下你会看到新的 rancher Pod 创建然后旧的被删除。如果新 Pod 一直起不来用kubectl describe pod和kubectl logs排查。3.2 Docker 单容器升级方式如果是 Docker 单容器部署的 Rancher升级就是停掉旧容器用新镜像启动新容器。首先拉取新版本镜像docker pull rancher/rancher:v2.8.3然后停止并重命名旧容器不要直接删除万一要回滚还能用docker stop rancher docker rename rancher rancher-old接着用同样的配置启动新容器docker run -d --restartunless-stopped \ --name rancher \ -p 80:80 -p 443:443 \ -v /opt/rancher:/var/lib/rancher \ --privileged \ rancher/rancher:v2.8.3启动后观察容器日志docker logs -f rancher日志里会显示 Rancher 启动过程和数据库迁移进度。等日志出现 “Rancher startup complete” 之类的信息就说明启动完成了。3.3 升级后的验证清单升级命令执行完不代表万事大吉必须做一轮完整的验证。我通常按以下顺序检查UI 可访问打开 Rancher 地址确认登录页面正常加载能正常登录。下游集群状态进入 Cluster Management确认所有下游集群都是 Active 状态。如果有 Unavailable 的点进去看 agent 状态。核心功能可用随便点开一个下游集群确认能查看节点、Pod、Service 等资源能执行 kubectl 命令。API 可用用curl调一下 Rancher API确认返回正常。告警和日志检查 Rancher 的告警配置是否还在日志是否能正常查看。如果下游集群升级后变成 Unavailable通常是 agent 版本没升上去。可以手动重启下游集群的 cattle-cluster-agent Podkubectl rollout restart deployment cattle-cluster-agent -n cattle-system等 agent 重新连接后集群状态应该会恢复。3.4 离线升级的镜像同步操作离线升级的核心是提前把镜像同步到内网 registry。Rancher 官方提供了两个脚本rancher-save-images.sh和rancher-load-images.sh。在有外网的机器上执行./rancher-save-images.sh --image-list rancher-images.txt这个脚本会拉取所有需要的镜像并打包成rancher-images.tar.gz。文件可能有好几个 GB传输到内网需要一些时间。传到内网后在能访问内网 registry 的机器上执行./rancher-load-images.sh --image-list rancher-images.txt --registry registry.internal.example.com脚本会把镜像推送到内网 registry。然后升级 Rancher 时通过--set image.repository或--set systemDefaultRegistry指定内网 registry 地址。提示离线升级时下游集群的 agent 镜像也需要同步到内网 registry否则 agent 升级会失败。这个容易漏我踩过一次升级后下游集群全部 Unavailable排查半天才发现是 agent 镜像拉不到。4. 常见问题排查与避坑经验实录升级过程中遇到的问题五花八门我挑几个最典型的整理成速查表方便对照排查。4.1 升级后 UI 无法访问的排查思路UI 打不开是最常见的问题可能的原因有好几种。先确认 rancher Pod 是否 Runningkubectl get pods -n cattle-system如果 Pod 不是 Running看 describe 和 logs。常见原因是资源不足、镜像拉取失败、或者数据库迁移卡住。如果 Pod 是 Running 但 UI 打不开检查 ingress 和 servicekubectl get ingress -n cattle-system kubectl get svc -n cattle-system确认 ingress 的地址和证书配置正确。有时候升级后 ingress 的 annotation 会变导致路由规则失效。还有一种情况是浏览器缓存问题。升级后 UI 的静态资源路径可能变了浏览器加载的是旧缓存。强制刷新CtrlShiftR或者换无痕窗口试试。4.2 下游集群 Unavailable 的恢复方法下游集群 Unavailable 通常是因为 agent 连不上 server。先在管理集群里检查 cattle-cluster-agent 的状态kubectl get pods -n cattle-system --context downstream-cluster如果 agent Pod 在 CrashLoopBackOff看日志找原因。常见原因包括agent 镜像版本不匹配、证书过期、网络策略阻断。如果是证书问题可以删除 agent 的 secret让它重新生成kubectl delete secret cattle-credentials -n cattle-system --context downstream-cluster然后重启 agentkubectl rollout restart deployment cattle-cluster-agent -n cattle-system --context downstream-cluster等几分钟集群状态应该会恢复。4.3 升级卡在数据库迁移阶段的处理Rancher 升级时会执行数据库迁移如果迁移卡住Pod 会一直处于 Running 但未 Ready 的状态。看日志会看到类似 “running migrations” 的信息。这种情况通常是数据库连接有问题或者迁移脚本执行超时。先检查数据库连接kubectl exec -it rancher-xxx -n cattle-system -- sh # 在容器内测试数据库连接如果是外部数据库确认网络连通性和账号权限。如果是内置的 SQLite检查磁盘空间是否充足。如果迁移确实卡死了可以尝试回滚到旧版本恢复 etcd 快照然后排查迁移失败的原因。不要强行 kill 迁移进程可能导致数据库处于不一致状态。4.4 常见问题速查表问题现象可能原因排查命令解决方法UI 无法访问Pod 未 Readykubectl get pods -n cattle-system看 logs 排查启动失败原因下游集群 Unavailableagent 版本不匹配kubectl get pods -n cattle-system --context cluster重启 agent 或手动升级 agent 镜像升级卡在迁移阶段数据库连接问题kubectl logs rancher-xxx -n cattle-system检查数据库连通性和磁盘空间证书错误证书过期kubectl get secret -n cattle-system续期证书或删除 secret 重新生成镜像拉取失败网络问题或 registry 不可达kubectl describe pod rancher-xxx -n cattle-system检查网络和 registry 配置4.5 我踩过的几个坑和应对技巧第一个坑是忽略了 webhook 证书。Rancher 升级后会重新生成 webhook 证书但如果旧证书的 CN 或 SAN 配置有问题新证书可能签发失败导致 webhook 不可用。表现是创建或修改资源时报 webhook 错误。解决办法是升级前检查 webhook 配置确保证书模板正确。第二个坑是下游集群的 agent 镜像没有提前同步。离线升级时我只同步了 Rancher server 的镜像忘了 agent 镜像。升级后下游集群全部 Unavailable因为 agent 拉不到新镜像。后来我把 agent 镜像也同步到内网 registry问题解决。第三个坑是升级窗口选在了业务高峰期。虽然业务 Pod 不受影响但升级期间运维团队没法通过 Rancher 操作集群正好赶上有个紧急故障需要处理只能干等升级完成。从那以后我都选在深夜或周末升级。第四个坑是没有提前测试回滚流程。有一次升级失败想回滚发现 etcd 快照恢复的步骤没演练过手忙脚乱搞了两个小时才恢复。后来我养成了习惯每次升级前都在测试环境完整走一遍回滚流程确保真出事的时候能快速操作。4.6 升级后的收尾工作升级完成并验证通过后还有几件收尾的事要做。第一是清理旧版本的镜像和容器释放磁盘空间。第二是更新监控和告警配置确保新版本的指标能正常采集。第三是记录升级过程中的问题和解决方法形成文档下次升级可以参考。如果升级过程中修改了任何配置比如调整了 replicas 或资源限制记得把这些变更同步到版本控制里避免下次升级时配置丢失。我个人在实际操作中的体会是Rancher 升级这件事准备工作占七成执行占三成。准备做得越充分执行时越从容。每次升级前花一两个小时做检查和备份远比升级出问题后花一整天排查要划算。另外不要迷信“小版本升级没事”的说法我遇到过好几次小版本升级引入的 bug所以不管升多小的版本流程一步都不能省。