Kubernetes ImagePullBackOff：按层级拆解的排查手册（入门版）

ImagePullBackOff 是 Kubernetes 用户最常遇到的噪音之一。好消息是它通常归类清晰：镜像引用错误、凭证缺失、权限不足、Registry 不可达、镜像不存在。坏消息是：日志片段常常看起来像「网络问题」，需要分层验证。

1. 先看 Pod Events：错误字段通常直指方向

从 kubectl describe pod 的事件里优先提取关键字：pull、denied、not found、timeout。它们对应的路径不一样：

• not found / manifest unknown：镜像名、tag、架构不匹配优先怀疑
• unauthorized / forbidden：凭据、镜像拉取 Secret、Registry 权限优先怀疑
• timeout / tls：网络路径优先怀疑

2. 核对镜像引用是否与集群运行时一致

常见问题包括：

• 写了集群节点访问不到的 Registry（需要镜像分发或代理）
• Tag 实际不存在（你以为存在，但 Registry 上已被删除或改名）
• 多架构镜像在特定节点架构无法解析到可用 manifest

建议在集群外部（同一网络平面）用可控工具先行验证镜像可达性；不要在集群里盲目试错。

3. imagePullSecrets：配置对了也不一定生效

检查点包括：

• Secret 是否在正确的命名空间
• Pod 是否引用到了 Secret（或默认 ServiceAccount 是否配置了默认 pull secret）
• 凭证是否是 robot account / token 过期 / 权限边界错误

4. imagePullPolicy：不是玄学，但会带来错觉

当策略导致频繁尝试重新拉取时，你可能看到一个 Tag「看似没变」，但实际 Registry 行为发生了变化（少数场景）。策略应与发布节奏匹配。

5. 运行时视角：containerd / CRI-O 日志在哪里

不同运行时日志位置不同，但在规模化集群里，统一日志采集与错误聚合会比单机 grep 更有效。

6. 小结

ImagePullBackOff 绝大多数可以用「清单式排查」解决。先把镜像引用与权限两件事做对，再讨论网络优化；否则你只是更快地把错误镜像拉下来失败而已。