ImagePullBackOff 是什么
镜像拉取失败后系统会退避重试，状态上就表现为拉取退避：首次失败与重试中的提示含义相同，区别只是第一次是立刻报错，之后进入等待重试。确切原因写在实例详情的事件里，常见的是认证失败、标签不存在、网络超时、证书不受信任与磁盘空间不足。私有仓库还需要额外提供拉取凭据。
基本信息
| 两种提示 | 首次失败与退避重试，含义相同，只是时机不同 |
|---|---|
| 原因速查 | 标签不存在、认证失败、连接超时、证书错误、磁盘不足 |
| 私有仓库 | 需要在工作负载里引用仓库凭据，否则无法通过认证 |
| 凭据范围 | 凭据属于命名空间级资源，每个环境都要单独创建 |
| 排查入口 | 实例详情的事件里会写明拉取失败的确切原因 |
| 复现方式 | 在节点上直接拉取镜像，可区分网络问题与配置问题 |
典型排查动作
- 读事件拿到确切原因：认证失败与标签不存在是完全不同的两条路
- 核对镜像名与标签拼写：仓库地址、命名空间、名称、标签缺一不可
- 确认标签是否真的推上去了：本地构建成功不等于已推送到仓库
- 检查拉取凭据：是否在当前命名空间创建，工作负载是否引用
- 验证网络：在节点上直接拉取同一镜像，区分网络不通与凭据问题
- 检查磁盘：节点磁盘空间不足时拉取会中断，事件里通常有相关提示
事件提示与处置
| 提示关键词 | 含义 | 处置 |
|---|---|---|
| 未授权或认证失败 | 没有凭据或凭据失效 | 创建或更新拉取凭据并在工作负载引用 |
| 仓库或标签不存在 | 镜像名或标签写错 | 核对名称与标签，确认已推送 |
| 连接超时 | 节点到仓库网络不通 | 检查网络策略与仓库地址可达性 |
| 证书错误 | 自签证书未被信任 | 在节点信任列表中加入仓库证书 |
| 磁盘空间不足 | 节点空间不够 | 清理无用镜像与日志后重试 |
排查与修复
排查与修复
kubectl describe pod web-1 | grep -A5 -i "pull\|back-off" # 拿到确切原因
kubectl get secret regcred -o jsonpath='{.type}' # 确认凭据类型
kubectl patch deploy web -p '{"spec":{"template":{"spec":{"imagePullSecrets":[{"name":"regcred"}]}}}}'
# 在节点上直接拉取同一镜像，可区分网络问题与认证问题
# 修完记得删除实例让控制器立刻重建拉取凭据是命名空间级资源：每个环境与命名空间都要各自创建，在一处创建后指望全局生效是最常见的误判。
标签漂移会带来隐性失败：长期使用最新标签又依赖清理策略时，旧镜像被删除后才发现拉不到，部署随即中断。
本地构建成功不代表能拉取：还要确认镜像确实推送到了目标仓库，且仓库地址与凭据匹配。
首次失败与退避重试的区别只是时间点：看到退避重试不要以为需要等，原因与第一次失败完全相同。
把镜像拉取纳入发布前置检查：发布前在目标节点试拉一次，可以提前暴露凭据与网络问题，而不是等到切换流量时才发现。
为镜像仓库准备备用地址：单点仓库故障时备用地址能让节点继续拉取，避免整批实例都卡在拉取阶段。