1. 问题背景与现象描述在Rancher Prime v2.13.1版本中系统升级控制器(System Upgrade Controller)错误地使用了不兼容的kubectl镜像这会导致集群升级过程中出现意外行为。具体表现为升级作业(Job)因镜像拉取失败而卡在Pending状态集群节点无法按预期完成Kubernetes版本升级系统日志中出现ImagePullBackOff或ErrImagePull错误事件这个问题主要影响使用Rancher管理的RKE2和K3s集群的版本升级流程。系统升级控制器是Rancher用于管理集群滚动升级的核心组件它通过创建计划(Plan)和作业(Job)来协调节点的升级顺序。2. 根本原因分析2.1 镜像标签错误根本原因是system-upgrade-controller部署中错误配置了kubectl镜像的标签。在v2.13.1中控制器错误地尝试拉取rancher/kubectl:v1.21.14而不是正确的rancher/kubectl:v1.23.10镜像。版本对应关系如下表Rancher Prime版本应使用的kubectl镜像实际使用的镜像v2.13.1rancher/kubectl:v1.23.10rancher/kubectl:v1.21.142.2 影响范围该问题会影响以下场景新创建的RKE2/K3s集群启用版本管理时现有集群执行Kubernetes版本升级时系统自动触发的安全补丁更新3. 问题解决方案3.1 临时修复方案对于已出现问题的集群可手动修正镜像标签kubectl -n cattle-system patch deployments.apps system-upgrade-controller \ --typejson \ -p[{op: replace, path: /spec/template/spec/containers/0/image, value: rancher/kubectl:v1.23.10}]然后删除错误的Pod使其重建kubectl -n cattle-system delete pods -l appsystem-upgrade-controller3.2 永久解决方案Rancher官方已在v2.13.2中修复此问题建议升级到最新版本备份当前Rancher配置通过Helm执行升级helm upgrade rancher rancher-latest/rancher \ --namespace cattle-system \ --version 2.13.24. 详细排查步骤4.1 诊断问题检查system-upgrade-controller日志kubectl -n cattle-system logs -l appsystem-upgrade-controller查看升级计划状态kubectl get plans -A -o wide检查Pod事件kubectl get events -A --field-selector involvedObject.kindPod4.2 验证修复确认新Pod使用的正确镜像kubectl -n cattle-system get pods -l appsystem-upgrade-controller \ -o jsonpath{.items[0].spec.containers[0].image}5. 预防措施为避免类似问题建议在测试环境验证所有集群升级操作监控关键系统组件的镜像版本定期检查Rancher官方发布的已知问题列表6. 相关配置参考正确的system-upgrade-controller部署应包含以下镜像配置spec: template: spec: containers: - image: rancher/kubectl:v1.23.10 imagePullPolicy: IfNotPresent7. 版本兼容性说明不同Rancher版本对应的kubectl镜像要求Rancher版本Kubernetes支持范围推荐kubectl镜像v2.12.xv1.20-v1.24rancher/kubectl:v1.21.14v2.13.xv1.21-v1.25rancher/kubectl:v1.23.10v2.14.xv1.22-v1.26rancher/kubectl:v1.24.88. 操作注意事项修改系统组件前务必创建快照或备份生产环境建议在维护窗口期执行升级确保节点有足够的资源下载新镜像多节点集群建议分批执行升级9. 常见问题排查Q: 升级后部分节点仍卡在旧版本 A: 检查节点上的system-upgrade服务状态journalctl -u system-upgrade-controller -fQ: 镜像拉取速度慢导致超时 A: 可预先在节点上手动拉取镜像docker pull rancher/kubectl:v1.23.10Q: 升级后API Server不可用 A: 检查控制平面节点资源使用情况必要时扩展资源