Kubernetes ImagePullBackOff 排查全流程:私有仓库认证、tag 拼错与拉取限流逐层定位发布上线时 Pod 卡在ImagePullBackOff或ErrImagePull,大概率不是集群坏了,而是 kubelet 拉不到镜像。这类问题最烦的地方是「报错都一样,原因五花八门」:可能是 tag 写错、私有仓库没配 Secret、也可能是被 Docker Hub 限流。这篇按定位顺序把常见原因一次讲透。先看现象,再看事件kubectl get pod# NAME READY STATUS RESTARTS AGE# web-xxx 0/1 ImagePullBackOff 0 40sImagePullBackOff只是「拉取失败后在退避等待重试」的状态,真正的原因在事件里:kubectl describe pod web-xxx|sed-n/Events/,$p重点看Failed这行的 message。不同原因给出的文案完全不同,下面分三类对号入座。原因一:tag / 镜像名拼错message 里出现not found或manifest unknown:Failed to pull image myapp:latest: ... manifest for myapp:latest not found八成是 tag 打错,或者镜像根本没 push 上去。先在本地确认远端确实有这个 tag:# 直接问仓库要 manifest,不用真的 pulldockermanifest inspect registry.example.com/myapp:v1.2.3顺手排查两个高频低级错误:用了:latest但 CI 从没打过 latest,或推的是v1.2.3却写成1.2.3(少个 v)。imagePullPolicy: Always配合本地构建的镜像——节点上明明有,kubelet 却非要去远端拉,拉不到就炸。本地测试镜像应设成IfNotPresent。原因二:私有仓库没认证(401 / no basic auth)message 出现401 Unauthorized或no basic auth credentials,说明仓库要登录但 Pod 没带凭证。正确做法是建docker-registry类型的 Secret 再引用:kubectl create secret docker-registry regcred\--docker-serverregistry.example.com\--docker-usernamedeploy\--docker-password***\--docker-emailnoreplyexample.com然后在 Pod 里通过imagePullSecrets挂上——注意它是 Pod spec 的字段,不是 container 的,这是最常见的写错位置:spec:imagePullSecrets:-name:regcred# 和 containers 同级,别塞进 container 里containers:-name:webimage:registry.example.com/myapp:v1.2.3如果同一个命名空间下很多 Pod 都要拉私有镜像,与其每个 Deployment 写一遍,不如把 Secret 绑到 ServiceAccount 上,一次配置全命名空间生效:kubectl patch serviceaccount default\-p{imagePullSecrets:[{name:regcred}]}验证 Secret 内容是否真的正确(排查密码里有特殊字符被转义等问题):kubectl get secret regcred-ojsonpath{.data.\.dockerconfigjson}|base64-d原因三:Docker Hub 限流(toomanyrequests)message 出现toomanyrequests或You have reached your pull rate limit。Docker Hub 对匿名拉取按源 IP 限流(每 6 小时几百次),一个 NAT 出口后面几十个节点很容易撞上:Failed to pull image nginx:1.25: ... 429 Too Many Requests治标是给 kubelet 配一个登录用户(限额更高),治本是把公有基础镜像同步进公司内网 registry / mirror,业务镜像统一从内网拉,既避开限流又快。改 Deployment 里的 image 地址即可:# 拉限流的公网地址image:nginx:1.25# 改成走内网镜像仓库image:registry.internal/library/nginx:1.25一条命令快速判类不想逐个 describe 时,直接把失败原因捞出来集中看:kubectl get events --field-selectorreasonFailed\--sort-by.lastTimestamp-A|grep-ipull看到manifest unknown查 tag,401/no basic auth查 Secret,toomanyrequests查限流,三选一,不用瞎猜。小结ImagePullBackOff是结果不是原因,真正的线索永远在kubectl describe pod的 Events 里。按 message 关键词对号入座:manifest unknown→tag/镜像名错;401 / no basic auth→私有仓库缺imagePullSecrets;toomanyrequests→Docker Hub 限流。imagePullSecrets是Pod spec 级字段,不是 container 级;命名空间内共用可绑到 ServiceAccount。记忆点:先 describe 看事件,再按关键词分三类——名字错、没认证、被限流,顺序走一遍准能定位。