imagepullbackoff

Kubernetes ImagePullBackOff 的定位与修复

现象

Pod 状态为 ErrImagePull 或 ImagePullBackOff，容器没有启动。describe 的 Events 里会显示拉取失败的具体原因。

快速定位

kubectl describe pod <pod> -n <ns>
kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -20
kubectl get pod <pod> -n <ns> -o jsonpath='{.spec.containers[*].image}'
kubectl get pod <pod> -n <ns> -o jsonpath='{.spec.imagePullSecrets}'

在节点上验证：

crictl pull <image>
docker pull <image>
curl -I https://<registry>/v2/

常见根因

镜像名或 tag 拼写错误，或 tag 不存在。
私有仓库未配置 imagePullSecrets，或 secret 无效/过期。
节点无法访问 registry：DNS、网络、代理或防火墙。
registry 限流或认证失败。
镜像架构与节点架构不匹配（amd64/arm64）。
节点磁盘或镜像存储空间不足。

修复

先看 describe 的 Events，区分 not found、unauthorized、timeout。
修正镜像名/tag；确认 registry 中确实存在该镜像。
创建并绑定正确的 imagePullSecrets，检查 secret 的 dockerconfigjson。
在节点上手动 crictl pull，验证网络、DNS 和认证。
多架构集群确认镜像支持对应平台，或使用 manifest list。
清理节点磁盘和旧镜像，检查 kubelet 日志。

相关命令

kubectl — Pod 事件与配置
crictl — 节点侧镜像拉取
docker — registry 连通性验证

读完自测

合上页面，先回答，再展开对照。

Pod 处于 ImagePullBackOff 时，第一步应查什么来区分拉取失败的具体原因？
节点上如何验证镜像拉取能力与 registry 连通性？
修复私有仓库认证问题后，应如何确认配置生效？

答案

先看 kubectl describe pod 的 Events（及命名空间事件），区分 not found、unauthorized、timeout。
在节点上用 crictl pull <image>（或 docker pull）手动拉取，并用 curl -I https://<registry>/v2/ 验证 registry 连通性。
创建并绑定正确的 imagePullSecrets，检查 secret 的 dockerconfigjson，再在节点手动 crictl pull 验证认证与网络。