企业官网建设流程全解析

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镜像。

版本对应关系如下表：

2.2 影响范围

该问题会影响以下场景：

• 新创建的RKE2/K3s集群启用版本管理时
• 现有集群执行Kubernetes版本升级时
• 系统自动触发的安全补丁更新

3. 问题解决方案

3.1 临时修复方案

对于已出现问题的集群，可手动修正镜像标签：

kubectl -n cattle-system patch deployments.apps system-upgrade-controller \ --type=json \ -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value": "rancher/kubectl:v1.23.10"}]'

然后删除错误的Pod使其重建：

kubectl -n cattle-system delete pods -l app=system-upgrade-controller

3.2 永久解决方案

Rancher官方已在v2.13.2中修复此问题，建议升级到最新版本：

1. 备份当前Rancher配置
2. 通过Helm执行升级：

helm upgrade rancher rancher-latest/rancher \ --namespace cattle-system \ --version 2.13.2

4. 详细排查步骤

4.1 诊断问题

检查system-upgrade-controller日志：

kubectl -n cattle-system logs -l app=system-upgrade-controller

查看升级计划状态：

kubectl get plans -A -o wide

检查Pod事件：

kubectl get events -A --field-selector involvedObject.kind=Pod

4.2 验证修复

确认新Pod使用的正确镜像：

kubectl -n cattle-system get pods -l app=system-upgrade-controller \ -o jsonpath='{.items[0].spec.containers[0].image}'

5. 预防措施

为避免类似问题，建议：

1. 在测试环境验证所有集群升级操作
2. 监控关键系统组件的镜像版本
3. 定期检查Rancher官方发布的已知问题列表

6. 相关配置参考

正确的system-upgrade-controller部署应包含以下镜像配置：

spec: template: spec: containers: - image: rancher/kubectl:v1.23.10 imagePullPolicy: IfNotPresent

7. 版本兼容性说明

不同Rancher版本对应的kubectl镜像要求：

8. 操作注意事项

1. 修改系统组件前务必创建快照或备份
2. 生产环境建议在维护窗口期执行升级
3. 确保节点有足够的资源下载新镜像
4. 多节点集群建议分批执行升级

9. 常见问题排查

Q: 升级后部分节点仍卡在旧版本 A: 检查节点上的system-upgrade服务状态：

journalctl -u system-upgrade-controller -f

Q: 镜像拉取速度慢导致超时 A: 可预先在节点上手动拉取镜像：

docker pull rancher/kubectl:v1.23.10

Q: 升级后API Server不可用 A: 检查控制平面节点资源使用情况，必要时扩展资源