周一的告警通道里突然涌入一批 ImagePullBackOff 通知全部来自系统升级控制器所在的命名空间。打开关联的 Pod 列表二三十个 Job 子 Pod 整整齐齐停在 Init 状态任何重试都没用。标题里说的“错误的 kubectl 图像”其实就是升级控制器创建 Job 时注入的那个 kubectl 容器镜像 tag 不对导致拉取失败或者拉到的内容根本不是预期版本。这篇文章的读者应该是这样一群人手里跑着 Rancher Prime v2.13.1纳管了一批下游 Kubernetes 集群并且用系统升级计划做过节点滚动升级。如果你碰到过升级计划忽然全部卡住、Job Pod 一直在拉镜像失败的场景这篇至少能帮你省半天排查时间。我会把这次问题的表象、根因、排查链和修复方式完整记一遍顺带总结几条防再犯的检查项。1. 表面现象升级计划全体卡在 Preparing不是网络问题是镜像错1.1 看到的第一批异常 Pod先说现场。我们有一个下游集群Kubernetes 版本是 1.29 系列通过 Rancher Prime v2.13.1 纳管。节点上安装了系统升级控制器之后我创建了一个 Plan用于滚动更新节点操作系统内核并顺带清理长期运行的旧容器。Plan 提交之后大概两三分钟第一批 Job 正常生成紧接着所有 Job 的 Pod 都停在了 Init:ImagePullBackOff。用 kubectl describe pod 去看事件信息其实很明确事件里写着 Failed to pull image registry.internal/base/kubectl:v1.27.5错误码要么是 manifest unknown要么是 tag does not exist部分节点还报了 digest 校验失败这里有一个非常关键的细节Job 里拉取的镜像和我当时在 Plan 里写的镜像完全不是一回事。因为我在 Plan 里根本没有指定 kubectl 镜像所以这个镜像是系统升级控制器自己带出来的默认值。也就是说控制器内部替我们决定了一个“它认为应该用的 kubectl 镜像”而这个镜像跟集群实际状态、镜像仓库实际内容都对不上。1.2 为什么第一反应会误判成网络问题这类问题最有迷惑性的地方在于错误信息长得非常像基础设施故障。ImagePullBackOff 这个词很多人看到之后第一反应都是 registry 不通、DNS 解析失败、证书过期、镜像太大拉取超时。我也不例外先做了三个常规动作在节点上手动 docker pull 同一个镜像发现节点本身访问 registry.internal 是通的检查 containerd 配置和私有仓库 mirror配置正常手动重启了几个 Job Pod重试后还是同样结果直到我在节点上手动执行 docker pull 时看到 manifest unknown才确定问题不在网络而是镜像地址或 tag 本身在仓库里不存在。再往下一层看真正的问题是控制器解析出来的镜像 tag 和仓库里实际存在的 tag 不一致。这次还有一个值得记录的细节同一个 Rancher Prime v2.13.1 管理的另一个下游集群因为它使用的系统升级计划版本刚好依赖另一个可用 tag所以没有出现同样问题。这也解释了为什么“全体卡住”的现象只出现在部分集群——问题不是全局性的而是 tag 解析和仓库内容之间的匹配问题。2. 控制器内部的镜像解析机制默认 kubectl 镜像是怎么被选出来的2.1 system-upgrade-controller 为什么需要 kubectl 镜像系统升级控制器的本职工作不是直接跑升级脚本而是负责三件事监听用户定义的 Plan 对象根据节点的版本标签和选择器挑选出需要升级的节点为这些节点创建 JobJob 内跑用户指定的升级命令同时在 Job 里塞入一个辅助 kubectl 容器用来完成节点标记、排水、解封等控制面操作那个辅助容器需要一个 kubectl 二进制而容器里的 kubectl 自然来自一个镜像。这就是“kubectl 镜像”的用途。它跟真正执行系统升级的镜像比如内核升级脚本是两回事但两者都会被写进同一个 Job 的 Pod 模板中。理解这个分工很重要升级脚本负责在节点上做实际工作kubectl 容器负责跟 API Server 打交道二者各管一段。2.2 默认镜像的选择路径控制器决定用哪个 kubectl 镜像时优先级大致是Plan 里显式指定的 kubectl 配置前提是当前 CRD 版本支持控制器启动参数或环境变量传入的默认值代码内置的兜底默认值在 Rancher Prime v2.13.1 里由于整个控制器是以附加组件形式安装的安装时 Helm values 通常会填充一个默认 kubectl 镜像。这个默认值指向的 tag 一般跟随发布主版本定死比如这次发布决定用 v1.27.5下一次可能改成 v1.28.7。问题就出在这里如果下游集群的 Kubernetes 版本比这个默认 tag 对应的版本高控制器通常还能正常工作因为 kubectl 向后兼容能力比较强但如果下游集群版本比较老或者默认 tag 在新版本发布之后被仓库清理、覆盖、转移就会出现拉取失败更隐蔽的是tag 存在但 digest 变了拉下来的 kubectl 是旧版本与集群 API Server 的 RBAC、CRD 版本协商出现兼容问题形成“镜像拉到了但行为是错的”从原理上说kubectl 与 API Server 之间走的是版本化协议。kubectl 版本如果比集群版本差太多可能发现不了某些资源类型也可能因为 --subresource 等 HTTP 路径变化导致操作返回 404。这类问题不会显示在镜像拉取阶段而是在升级流程执行到一半才暴露排查难度更大。2.3 一个容易忽略的前提Plan 的镜像拉取策略控制器创建 Pod 时辅助 kubectl 容器的 imagePullPolicy 默认是 IfNotPresent。这意味着如果节点上曾经因为某个历史计划拉取过相同 tag 的镜像之后即使仓库里该 tag 的 digest 已经更新节点也不会重新拉取继续使用旧镜像。这个行为在基于 tag 而不是 digest 引用镜像时尤其容易埋雷。下一次升级再跑你以为用的是新镜像实际上节点还在用旧的。用一句话类比你让翻译带着“词典最新版”去接待外宾但他手里拿的是三个月前的旧版书皮一样内容已经大改这就是“tag 还在、digest 变了”造成的错误镜像。提示要判断控制器实际注入的镜像不要只看 Plan 文档直接看 Job 的 Pod spec 里包含的容器定义这是最真实的事实来源。3. 从告警到根因一次完整的定位路径3.1 第一步核对 Plan 里有没有覆盖 kubectl 镜像我们先把出问题的 Plan 导出 YAML 检查重点看是否有 kubectl 相关字段。像我们用的 Plan 只是填了 upgrade 容器、version 号、节点选择器等没有显式给 kubectl 容器指定镜像于是嫌疑落到控制器默认值上。这一步要特别认真。有些人在 Plan 里写了 concurrency、drain 参数就会误以为自己“看到了全部配置”实际上 kubectl 容器配置在 Plan 的 Spec 里通常是比较隐蔽的需要打开对应字段才能看到。如果你用的系统升级控制器版本较新可以通过 kubectl explain plan.spec 查看当前 CRD 支持的字段确认是否存在显式覆盖 kubectl 镜像的入口。3.2 第二步看控制器创建的 Job 和 Pod 模板通过 kubectl get job -n system-upgrade 找到对应 Job然后看 Job 中 Pod template 的容器列表。会看到除了用户定义的升级容器之外还有一个由控制器注入的 init 容器或者辅助容器里面就带有 image 字段比如 registry.internal/base/kubectl:v1.27.5。这一步已经可以确认“错误 kubectl 镜像”到底长什么样。接下来要回答的是为什么偏偏是 v1.27.5。注意到这个 tag 既不匹配我们集群的版本也不匹配控制器部署时感觉上应该使用的版本——一个看起来像是“某个历史版本”的 tag。3.3 第三步追踪控制器配置来源我们查看了命名空间里系统升级控制器的 Deployment发现它的启动参数里确实带了一个 kubectl 镜像相关的参数值恰好就是 registry.internal/base/kubectl:v1.27.5。再回头看安装这个组件时使用的 Helm values 文件发现安装时把 kubectl 镜像写成了一个当时最新的 tag但下游集群的版本一直停留在 1.29 系列而仓库里的镜像 tag 早在几个月前因为清理策略被移除了。两边一对照问题就很清楚控制器配置的默认镜像已经指向一个仓库中不存在的 tag任何新 Job 都会在拉镜像阶段失败。这是我们完整定位过程的第三步也是最接近根因的一步。3.4 第四步验证镜像仓库的真实状态为了最终坐实根因我们做了两步验证在私有镜像仓库的 API 或网页界面确认 kubectl 镜像现在存在哪些 tag发现只有 v1.27.6、v1.28.2 等几个没有 v1.27.5用 skopeo inspect 或 docker manifest inspect 查看指定 digest确认 manifest 确实丢失如果节点上跑的是 containerd还可以用 ctr images check 看节点已缓存镜像的 digest。通过对比 Job 引用的 tag 与节点缓存的 digest就能判断是纯粹的不存在还是存在但实际内容错误。这一步的结论对后续选择修复路径很重要如果只是 tag 不存在重新指向现有 tag 即可如果 tag 存在但 digest 不一致则需要考虑镜像仓库同步逻辑的问题。我把四步排查总结成一张表方便对照执行排查层命令或动作判断目标Plan 层kubectl get plan -o yaml是否显式覆盖了 kubectl 镜像Job 层kubectl get job -n system-upgrade -o yaml控制器实际注入的镜像地址与 tag控制器层kubectl get deploy -n system-upgrade -o yaml默认 kubectl 镜像参数来源仓库层skopeo inspect / registry APItag 和 digest 是否存在、是否被替换3.5 第五步别忽略镜像仓库代理的坑我们集群的 containerd 配置了 mirror所有镜像都优先走内部代理缓存。如果代理往上游同步时因为 tag 不存在而返回了另一个同名 tag 的缓存问题就会更诡异。我们这次排查时专门检查了代理缓存的 metadata确认不是这个原因但如果你也遇到“节点能拉到镜像但行为不对”的情况一定要多看这一层。尤其要注意一些镜像代理组件会在 tag 不存在时使用通配规则拼接地址导致下游拉取的镜像虽然是同一个 URL实际内容却是完全不同的构建产物。这种“错”比“不存在”更隐蔽因为镜像能拉下来但会在后续升级步骤里出现莫名其妙的权限错误或资源类型错误。4. 三种修复路径改 Plan、改控制器默认值、换产品版本4.1 最短路径在 Plan 里显式指定正确的 kubectl 镜像如果只是临时要让某个系统升级计划跑起来最快的办法是在 Plan 里把 kubectl 镜像写成实际可用的 tag。示意配置类似下面这样具体字段以你安装的 CRD 版本为准apiVersion: upgrade.cattle.io/v1 kind: Plan metadata: name: node-upgrade namespace: system-upgrade spec: version: 1.29.6 nodeSelector: matchLabels: upgrade.cattle.io/node: true tolerations: - key: node-role.kubernetes.io/control-plane operator: Exists effect: NoSchedule upgrade: image: registry.internal/os-upgrader:v2.3.0 command: [/upgrade.sh] concurrency: 2 # 当前控制器版本如果支持显式指定 kubectl 镜像可以这样覆盖 kubectl: image: registry.internal/base/kubectl:v1.29.6需要说明的是不同版本对 kubectl 容器配置的字段命名不一样有些是 Plan spec 下的 kubectl有些是通过环境变量传入有些则只能靠控制器参数控制。写之前一定要用 kubectl explain plan.spec 看当前 CRD 支持哪些字段避免 apply 时被 API Server 直接拒绝。我们当时用的控制器版本恰好支持显式覆盖所以改完重新 apply 之后新 Job 直接拉到了正确镜像整个升级计划恢复流转。4.2 治本路径改控制器默认镜像参数Plan 里手动指定适合解决单个计划但如果你的环境里有很多 Plan每个都要写一遍显然不现实。更合适的做法是从源头改掉控制器的默认 kubectl 镜像。找到 system-upgrade-controller 的 Deployment修改启动参数或者环境变量把默认镜像 tag 指向仓库中真实存在的版本。如果当初是用 Helm 安装的直接改 values 再更新组件即可。示意 values根据实际 chart 结构调整controller: kubectlImage: repository: registry.internal/base/kubectl tag: v1.29.6 imagePullPolicy: IfNotPresent改完之后确认 Deployment 滚动更新完成旧的 Job 可以手工清理掉让控制器重新协调生成新 Job。这个动作在系统升级控制器的设计里是幂等的控制器会持续比对 Plan 期望状态和实际状态重新生成缺失的 Job。这里我建议压一下 concurrency先让一个节点跑通再放开避免大批节点同时开始升级导致误操作扩散。哪怕只是镜像 tag 修复也要给节点上实际的升级脚本留出验证时间。4.3 如果有官方补丁升级 Rancher Prime 补丁版本Rancher Prime 的 v2.13.1 如果后续发布了补丁版本并且 Release Notes 里明确提到修正了默认 kubectl 镜像的设置那升级产品可能是最干净的解决方式。升级前记得看变更日志确认要动的组件版本和下游集群兼容。我们当时评估后没有立刻升级产品因为生产环境里产品版本变更影响面太大最终选择了改控制器默认值。如果你对升级影响面有顾虑先改镜像参数止损之后再规划产品版本升级是更稳妥的节奏。产品升级的好处是后续新增集群时不会再次踩到同样的默认值问题属于一次修复、全部生效。4.4 验证与回滚修复后按顺序验证kubectl get plan 状态显示 completed而不是一直处于 preparingJob 的 Pod 状态从 Init 错误变成 Completed节点上的升级标记被正确清除节点进入 Ready 状态如果发现新的镜像依然有问题回滚路径也很明确把 Plan 里的 kubectl 镜像字段还原或把控制器参数还原重新 apply控制器会再次协调。要注意系统升级控制器对 Plan 的变更不总是立刻生效必要时删掉挂起的 Job或重启控制器 Pod 强制重新协调。我个人的习惯是改完之后等 30 秒执行 kubectl get pods -n system-upgrade -w 观察新 Pod 的创建情况。如果控制器迟迟没有生成新 Job大概率是参数没生效或者 Deployment 没滚动完不要干等直接查控制器日志。5. 复盘这类错镜像问题在 Rancher 运维中的防控清单5.1 升级前先做镜像“体检”任何一次 Rancher Prime 或系统升级控制器版本变更之前先把目标版本的默认镜像列表拉出来跟仓库实际存在的 tag 对一遍。用脚本检查会比人肉可靠得多。核心检查项默认 kubectl 镜像 tag 在仓库里真实存在tag 对应的 digest 与上游一致防止私有仓库替换过内容下游集群的 Kubernetes 版本与默认 kubectl 版本差异在安全区间私有仓库代理的缓存没有被历史同名 tag 污染如果你们内部有多个团队共用一个镜像仓库还要注意 tag 清理策略。很多仓库默认只保留最近 N 个版本系统升级控制器默认值里的 tag 可能在一个月前就被清理了。像我们这次就是因为仓库清理策略太激进把控制器依赖的 tag 清掉了。5.2 把引用从 tag 改成 digest 的思路这里想多说一句。这次问题的根源是 tagtag 是可变引用。如果你已经把仓库管控做到一定水平建议在 Plan、Helm values 里用 digest 引用镜像比如controller: kubectlImage: repository: registry.internal/base/kubectl digest: sha256:5c3c3c1a9f1a5f6b7d2b9e3f2a1c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c好处是无论如何都不会发生“tag 移花接木”导致的行为漂移。缺点是需要手动跟着上游版本更新 digest更适合内部有自动化镜像同步脚本的团队。如果你现在还没条件全面转 digest至少针对控制器这类关键组件先转。5.3 配置监控和告警系统升级控制器创建 Job 失败时默认事件不会主动告警。我们后来加了一条规则对 system-upgrade 命名空间下 Job 的 ImagePullBackOff 事件做实时告警同时每 15 分钟检查一次 Plan 的 condition。这类事件往往是升级计划的“前哨战”早十分钟发现就能避免问题扩大到整个集群。告警规则里建议包含命名空间、Job 名称、事件类型三个维度。因为同一时间可能有一批 Job 同时失败直接把 Job 名称做分组聚合避免告警轰炸。实际效果是这次如果再发生类似问题我们会在第一批 Pod 失败后的两分钟内收到通知而不是等用户反馈集群异常。5.4 记录一份内部的版本-镜像映射表内部运维文档里维护一张映射表Rancher Prime 版本、集成的控制器版本、默认 kubectl 镜像、兼容的下游集群版本区间。这次排查之后我们把这张表补全了后续升级前先查表不再每次靠翻日志找原因。映射表示例产品版本控制器默认 kubectl 镜像兼容集群版本建议备注v2.13.1registry.internal/base/kubectl:v1.27.51.25 - 1.29需在升级前确认 tag 存在v2.13.1修复后registry.internal/base/kubectl:v1.29.61.27 - 1.31手工覆盖默认值这张表的价值在于让后来接手的人一眼看清当前环境的实际状态而不是靠回忆和历史告警猜。对于 Rancher 这类组件依赖比较深的环境文档里的“版本与镜像对应关系”比任何流程文档都实用。最后再分享一个小经验这次折腾下来最耗时的其实不是改镜像而是确认“控制器真正用哪个镜像”这个事实。人很容易根据文档或者配置推断“应该是哪个镜像”但系统实际跑起来的往往和你以为的不一样。我现在遇到升级计划异常时第一件事永远是把控制器创建的 Job YAML 拖出来看它到底要拉什么镜像、从哪个仓库拉。把事实摆出来再谈修复方案问题通常会清晰一半。希望这篇踩坑记录能给同样在用 Rancher Prime v2.13.1 的同行一些参考。
周一的告警通道里突然涌入一批 ImagePullBackOff 通知全部来自系统升级控制器所在的命名空间。打开关联的 Pod 列表二三十个 Job 子 Pod 整整齐齐停在 Init 状态任何重试都没用。标题里说的“错误的 kubectl 图像”其实就是升级控制器创建 Job 时注入的那个 kubectl 容器镜像 tag 不对导致拉取失败或者拉到的内容根本不是预期版本。这篇文章的读者应该是这样一群人手里跑着 Rancher Prime v2.13.1纳管了一批下游 Kubernetes 集群并且用系统升级计划做过节点滚动升级。如果你碰到过升级计划忽然全部卡住、Job Pod 一直在拉镜像失败的场景这篇至少能帮你省半天排查时间。我会把这次问题的表象、根因、排查链和修复方式完整记一遍顺带总结几条防再犯的检查项。1. 表面现象升级计划全体卡在 Preparing不是网络问题是镜像错1.1 看到的第一批异常 Pod先说现场。我们有一个下游集群Kubernetes 版本是 1.29 系列通过 Rancher Prime v2.13.1 纳管。节点上安装了系统升级控制器之后我创建了一个 Plan用于滚动更新节点操作系统内核并顺带清理长期运行的旧容器。Plan 提交之后大概两三分钟第一批 Job 正常生成紧接着所有 Job 的 Pod 都停在了 Init:ImagePullBackOff。用 kubectl describe pod 去看事件信息其实很明确事件里写着 Failed to pull image registry.internal/base/kubectl:v1.27.5错误码要么是 manifest unknown要么是 tag does not exist部分节点还报了 digest 校验失败这里有一个非常关键的细节Job 里拉取的镜像和我当时在 Plan 里写的镜像完全不是一回事。因为我在 Plan 里根本没有指定 kubectl 镜像所以这个镜像是系统升级控制器自己带出来的默认值。也就是说控制器内部替我们决定了一个“它认为应该用的 kubectl 镜像”而这个镜像跟集群实际状态、镜像仓库实际内容都对不上。1.2 为什么第一反应会误判成网络问题这类问题最有迷惑性的地方在于错误信息长得非常像基础设施故障。ImagePullBackOff 这个词很多人看到之后第一反应都是 registry 不通、DNS 解析失败、证书过期、镜像太大拉取超时。我也不例外先做了三个常规动作在节点上手动 docker pull 同一个镜像发现节点本身访问 registry.internal 是通的检查 containerd 配置和私有仓库 mirror配置正常手动重启了几个 Job Pod重试后还是同样结果直到我在节点上手动执行 docker pull 时看到 manifest unknown才确定问题不在网络而是镜像地址或 tag 本身在仓库里不存在。再往下一层看真正的问题是控制器解析出来的镜像 tag 和仓库里实际存在的 tag 不一致。这次还有一个值得记录的细节同一个 Rancher Prime v2.13.1 管理的另一个下游集群因为它使用的系统升级计划版本刚好依赖另一个可用 tag所以没有出现同样问题。这也解释了为什么“全体卡住”的现象只出现在部分集群——问题不是全局性的而是 tag 解析和仓库内容之间的匹配问题。2. 控制器内部的镜像解析机制默认 kubectl 镜像是怎么被选出来的2.1 system-upgrade-controller 为什么需要 kubectl 镜像系统升级控制器的本职工作不是直接跑升级脚本而是负责三件事监听用户定义的 Plan 对象根据节点的版本标签和选择器挑选出需要升级的节点为这些节点创建 JobJob 内跑用户指定的升级命令同时在 Job 里塞入一个辅助 kubectl 容器用来完成节点标记、排水、解封等控制面操作那个辅助容器需要一个 kubectl 二进制而容器里的 kubectl 自然来自一个镜像。这就是“kubectl 镜像”的用途。它跟真正执行系统升级的镜像比如内核升级脚本是两回事但两者都会被写进同一个 Job 的 Pod 模板中。理解这个分工很重要升级脚本负责在节点上做实际工作kubectl 容器负责跟 API Server 打交道二者各管一段。2.2 默认镜像的选择路径控制器决定用哪个 kubectl 镜像时优先级大致是Plan 里显式指定的 kubectl 配置前提是当前 CRD 版本支持控制器启动参数或环境变量传入的默认值代码内置的兜底默认值在 Rancher Prime v2.13.1 里由于整个控制器是以附加组件形式安装的安装时 Helm values 通常会填充一个默认 kubectl 镜像。这个默认值指向的 tag 一般跟随发布主版本定死比如这次发布决定用 v1.27.5下一次可能改成 v1.28.7。问题就出在这里如果下游集群的 Kubernetes 版本比这个默认 tag 对应的版本高控制器通常还能正常工作因为 kubectl 向后兼容能力比较强但如果下游集群版本比较老或者默认 tag 在新版本发布之后被仓库清理、覆盖、转移就会出现拉取失败更隐蔽的是tag 存在但 digest 变了拉下来的 kubectl 是旧版本与集群 API Server 的 RBAC、CRD 版本协商出现兼容问题形成“镜像拉到了但行为是错的”从原理上说kubectl 与 API Server 之间走的是版本化协议。kubectl 版本如果比集群版本差太多可能发现不了某些资源类型也可能因为 --subresource 等 HTTP 路径变化导致操作返回 404。这类问题不会显示在镜像拉取阶段而是在升级流程执行到一半才暴露排查难度更大。2.3 一个容易忽略的前提Plan 的镜像拉取策略控制器创建 Pod 时辅助 kubectl 容器的 imagePullPolicy 默认是 IfNotPresent。这意味着如果节点上曾经因为某个历史计划拉取过相同 tag 的镜像之后即使仓库里该 tag 的 digest 已经更新节点也不会重新拉取继续使用旧镜像。这个行为在基于 tag 而不是 digest 引用镜像时尤其容易埋雷。下一次升级再跑你以为用的是新镜像实际上节点还在用旧的。用一句话类比你让翻译带着“词典最新版”去接待外宾但他手里拿的是三个月前的旧版书皮一样内容已经大改这就是“tag 还在、digest 变了”造成的错误镜像。提示要判断控制器实际注入的镜像不要只看 Plan 文档直接看 Job 的 Pod spec 里包含的容器定义这是最真实的事实来源。3. 从告警到根因一次完整的定位路径3.1 第一步核对 Plan 里有没有覆盖 kubectl 镜像我们先把出问题的 Plan 导出 YAML 检查重点看是否有 kubectl 相关字段。像我们用的 Plan 只是填了 upgrade 容器、version 号、节点选择器等没有显式给 kubectl 容器指定镜像于是嫌疑落到控制器默认值上。这一步要特别认真。有些人在 Plan 里写了 concurrency、drain 参数就会误以为自己“看到了全部配置”实际上 kubectl 容器配置在 Plan 的 Spec 里通常是比较隐蔽的需要打开对应字段才能看到。如果你用的系统升级控制器版本较新可以通过 kubectl explain plan.spec 查看当前 CRD 支持的字段确认是否存在显式覆盖 kubectl 镜像的入口。3.2 第二步看控制器创建的 Job 和 Pod 模板通过 kubectl get job -n system-upgrade 找到对应 Job然后看 Job 中 Pod template 的容器列表。会看到除了用户定义的升级容器之外还有一个由控制器注入的 init 容器或者辅助容器里面就带有 image 字段比如 registry.internal/base/kubectl:v1.27.5。这一步已经可以确认“错误 kubectl 镜像”到底长什么样。接下来要回答的是为什么偏偏是 v1.27.5。注意到这个 tag 既不匹配我们集群的版本也不匹配控制器部署时感觉上应该使用的版本——一个看起来像是“某个历史版本”的 tag。3.3 第三步追踪控制器配置来源我们查看了命名空间里系统升级控制器的 Deployment发现它的启动参数里确实带了一个 kubectl 镜像相关的参数值恰好就是 registry.internal/base/kubectl:v1.27.5。再回头看安装这个组件时使用的 Helm values 文件发现安装时把 kubectl 镜像写成了一个当时最新的 tag但下游集群的版本一直停留在 1.29 系列而仓库里的镜像 tag 早在几个月前因为清理策略被移除了。两边一对照问题就很清楚控制器配置的默认镜像已经指向一个仓库中不存在的 tag任何新 Job 都会在拉镜像阶段失败。这是我们完整定位过程的第三步也是最接近根因的一步。3.4 第四步验证镜像仓库的真实状态为了最终坐实根因我们做了两步验证在私有镜像仓库的 API 或网页界面确认 kubectl 镜像现在存在哪些 tag发现只有 v1.27.6、v1.28.2 等几个没有 v1.27.5用 skopeo inspect 或 docker manifest inspect 查看指定 digest确认 manifest 确实丢失如果节点上跑的是 containerd还可以用 ctr images check 看节点已缓存镜像的 digest。通过对比 Job 引用的 tag 与节点缓存的 digest就能判断是纯粹的不存在还是存在但实际内容错误。这一步的结论对后续选择修复路径很重要如果只是 tag 不存在重新指向现有 tag 即可如果 tag 存在但 digest 不一致则需要考虑镜像仓库同步逻辑的问题。我把四步排查总结成一张表方便对照执行排查层命令或动作判断目标Plan 层kubectl get plan -o yaml是否显式覆盖了 kubectl 镜像Job 层kubectl get job -n system-upgrade -o yaml控制器实际注入的镜像地址与 tag控制器层kubectl get deploy -n system-upgrade -o yaml默认 kubectl 镜像参数来源仓库层skopeo inspect / registry APItag 和 digest 是否存在、是否被替换3.5 第五步别忽略镜像仓库代理的坑我们集群的 containerd 配置了 mirror所有镜像都优先走内部代理缓存。如果代理往上游同步时因为 tag 不存在而返回了另一个同名 tag 的缓存问题就会更诡异。我们这次排查时专门检查了代理缓存的 metadata确认不是这个原因但如果你也遇到“节点能拉到镜像但行为不对”的情况一定要多看这一层。尤其要注意一些镜像代理组件会在 tag 不存在时使用通配规则拼接地址导致下游拉取的镜像虽然是同一个 URL实际内容却是完全不同的构建产物。这种“错”比“不存在”更隐蔽因为镜像能拉下来但会在后续升级步骤里出现莫名其妙的权限错误或资源类型错误。4. 三种修复路径改 Plan、改控制器默认值、换产品版本4.1 最短路径在 Plan 里显式指定正确的 kubectl 镜像如果只是临时要让某个系统升级计划跑起来最快的办法是在 Plan 里把 kubectl 镜像写成实际可用的 tag。示意配置类似下面这样具体字段以你安装的 CRD 版本为准apiVersion: upgrade.cattle.io/v1 kind: Plan metadata: name: node-upgrade namespace: system-upgrade spec: version: 1.29.6 nodeSelector: matchLabels: upgrade.cattle.io/node: true tolerations: - key: node-role.kubernetes.io/control-plane operator: Exists effect: NoSchedule upgrade: image: registry.internal/os-upgrader:v2.3.0 command: [/upgrade.sh] concurrency: 2 # 当前控制器版本如果支持显式指定 kubectl 镜像可以这样覆盖 kubectl: image: registry.internal/base/kubectl:v1.29.6需要说明的是不同版本对 kubectl 容器配置的字段命名不一样有些是 Plan spec 下的 kubectl有些是通过环境变量传入有些则只能靠控制器参数控制。写之前一定要用 kubectl explain plan.spec 看当前 CRD 支持哪些字段避免 apply 时被 API Server 直接拒绝。我们当时用的控制器版本恰好支持显式覆盖所以改完重新 apply 之后新 Job 直接拉到了正确镜像整个升级计划恢复流转。4.2 治本路径改控制器默认镜像参数Plan 里手动指定适合解决单个计划但如果你的环境里有很多 Plan每个都要写一遍显然不现实。更合适的做法是从源头改掉控制器的默认 kubectl 镜像。找到 system-upgrade-controller 的 Deployment修改启动参数或者环境变量把默认镜像 tag 指向仓库中真实存在的版本。如果当初是用 Helm 安装的直接改 values 再更新组件即可。示意 values根据实际 chart 结构调整controller: kubectlImage: repository: registry.internal/base/kubectl tag: v1.29.6 imagePullPolicy: IfNotPresent改完之后确认 Deployment 滚动更新完成旧的 Job 可以手工清理掉让控制器重新协调生成新 Job。这个动作在系统升级控制器的设计里是幂等的控制器会持续比对 Plan 期望状态和实际状态重新生成缺失的 Job。这里我建议压一下 concurrency先让一个节点跑通再放开避免大批节点同时开始升级导致误操作扩散。哪怕只是镜像 tag 修复也要给节点上实际的升级脚本留出验证时间。4.3 如果有官方补丁升级 Rancher Prime 补丁版本Rancher Prime 的 v2.13.1 如果后续发布了补丁版本并且 Release Notes 里明确提到修正了默认 kubectl 镜像的设置那升级产品可能是最干净的解决方式。升级前记得看变更日志确认要动的组件版本和下游集群兼容。我们当时评估后没有立刻升级产品因为生产环境里产品版本变更影响面太大最终选择了改控制器默认值。如果你对升级影响面有顾虑先改镜像参数止损之后再规划产品版本升级是更稳妥的节奏。产品升级的好处是后续新增集群时不会再次踩到同样的默认值问题属于一次修复、全部生效。4.4 验证与回滚修复后按顺序验证kubectl get plan 状态显示 completed而不是一直处于 preparingJob 的 Pod 状态从 Init 错误变成 Completed节点上的升级标记被正确清除节点进入 Ready 状态如果发现新的镜像依然有问题回滚路径也很明确把 Plan 里的 kubectl 镜像字段还原或把控制器参数还原重新 apply控制器会再次协调。要注意系统升级控制器对 Plan 的变更不总是立刻生效必要时删掉挂起的 Job或重启控制器 Pod 强制重新协调。我个人的习惯是改完之后等 30 秒执行 kubectl get pods -n system-upgrade -w 观察新 Pod 的创建情况。如果控制器迟迟没有生成新 Job大概率是参数没生效或者 Deployment 没滚动完不要干等直接查控制器日志。5. 复盘这类错镜像问题在 Rancher 运维中的防控清单5.1 升级前先做镜像“体检”任何一次 Rancher Prime 或系统升级控制器版本变更之前先把目标版本的默认镜像列表拉出来跟仓库实际存在的 tag 对一遍。用脚本检查会比人肉可靠得多。核心检查项默认 kubectl 镜像 tag 在仓库里真实存在tag 对应的 digest 与上游一致防止私有仓库替换过内容下游集群的 Kubernetes 版本与默认 kubectl 版本差异在安全区间私有仓库代理的缓存没有被历史同名 tag 污染如果你们内部有多个团队共用一个镜像仓库还要注意 tag 清理策略。很多仓库默认只保留最近 N 个版本系统升级控制器默认值里的 tag 可能在一个月前就被清理了。像我们这次就是因为仓库清理策略太激进把控制器依赖的 tag 清掉了。5.2 把引用从 tag 改成 digest 的思路这里想多说一句。这次问题的根源是 tagtag 是可变引用。如果你已经把仓库管控做到一定水平建议在 Plan、Helm values 里用 digest 引用镜像比如controller: kubectlImage: repository: registry.internal/base/kubectl digest: sha256:5c3c3c1a9f1a5f6b7d2b9e3f2a1c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c好处是无论如何都不会发生“tag 移花接木”导致的行为漂移。缺点是需要手动跟着上游版本更新 digest更适合内部有自动化镜像同步脚本的团队。如果你现在还没条件全面转 digest至少针对控制器这类关键组件先转。5.3 配置监控和告警系统升级控制器创建 Job 失败时默认事件不会主动告警。我们后来加了一条规则对 system-upgrade 命名空间下 Job 的 ImagePullBackOff 事件做实时告警同时每 15 分钟检查一次 Plan 的 condition。这类事件往往是升级计划的“前哨战”早十分钟发现就能避免问题扩大到整个集群。告警规则里建议包含命名空间、Job 名称、事件类型三个维度。因为同一时间可能有一批 Job 同时失败直接把 Job 名称做分组聚合避免告警轰炸。实际效果是这次如果再发生类似问题我们会在第一批 Pod 失败后的两分钟内收到通知而不是等用户反馈集群异常。5.4 记录一份内部的版本-镜像映射表内部运维文档里维护一张映射表Rancher Prime 版本、集成的控制器版本、默认 kubectl 镜像、兼容的下游集群版本区间。这次排查之后我们把这张表补全了后续升级前先查表不再每次靠翻日志找原因。映射表示例产品版本控制器默认 kubectl 镜像兼容集群版本建议备注v2.13.1registry.internal/base/kubectl:v1.27.51.25 - 1.29需在升级前确认 tag 存在v2.13.1修复后registry.internal/base/kubectl:v1.29.61.27 - 1.31手工覆盖默认值这张表的价值在于让后来接手的人一眼看清当前环境的实际状态而不是靠回忆和历史告警猜。对于 Rancher 这类组件依赖比较深的环境文档里的“版本与镜像对应关系”比任何流程文档都实用。最后再分享一个小经验这次折腾下来最耗时的其实不是改镜像而是确认“控制器真正用哪个镜像”这个事实。人很容易根据文档或者配置推断“应该是哪个镜像”但系统实际跑起来的往往和你以为的不一样。我现在遇到升级计划异常时第一件事永远是把控制器创建的 Job YAML 拖出来看它到底要拉什么镜像、从哪个仓库拉。把事实摆出来再谈修复方案问题通常会清晰一半。希望这篇踩坑记录能给同样在用 Rancher Prime v2.13.1 的同行一些参考。
