镜像拉取失败是什么
拉取镜像失败时对象会经历两个状态：第一次失败时给出错误提示，随后进入按退避节奏重试的等待状态。它表示节点没能把镜像取下来，原因集中在三处：镜像引用的名称或标签不对、私有仓库的凭据缺失或无效、节点到仓库的网络与证书有问题。三者从错误文本上可以区分。
为什么换个环境就好了
本地能拉通而集群里拉不动，常见原因是凭据只配置在本机、或者节点无法访问内网仓库、或者私有仓库证书不被节点信任。反过来，在集群里手工拉通也不代表工作负载能成功——如果只在临时对象上验证，而模板里没有写凭据，新副本依然会失败。
基本信息
| 适用环境 | 任何 Kubernetes 发行版，涉及节点与镜像仓库之间的通信 |
|---|---|
| 两个状态 | 首次失败提示与重试等待状态 |
| 凭据方式 | 创建仓库类型密钥对象并在模板里引用 |
| 作用范围 | 凭据按命名空间隔离，必须与被引用的对象同命名空间 |
| 证书要求 | 私有仓库的证书需要被节点信任 |
| 排查入口 | 对象事件里的错误文本与节点侧手工拉取测试 |
典型使用场景
- 私有仓库接入：新环境首次部署时需要配置拉取凭据
- 凭据过期：镜像仓库口令轮换后旧凭据失效，新副本开始拉取失败
- 标签写错：镜像标签拼写错误或版本不存在
- 网络不通：节点无法访问仓库地址，常见于网络策略或出口限制
- 证书信任：自建仓库使用自签证书，节点未导入信任链
- 仓库限流：拉取过于频繁被拒绝，表现为间歇性失败
排查命令
排查命令
kubectl describe pod web-x | sed -n '/Events:/,$p' # 看拉取失败的完整错误
kubectl get secret regcred -n prod -o jsonpath='{.type}' # 确认凭据类型正确
kubectl get deploy web -o jsonpath='{.spec.template.spec.imagePullSecrets}' # 模板是否引用凭据
crictl pull registry.example.com/app:1.26.0 # 在节点上手工验证（只做拉取测试）错误文本对照
| 错误特征 | 指向的问题 | 处理方向 |
|---|---|---|
| 未授权或拒绝访问 | 凭据无效、过期或未授权 | 核对密钥内容与权限 |
| 清单或标签不存在 | 名称、路径或标签写错 | 核对镜像地址与版本 |
| 证书相关报错 | 仓库证书不被节点信任 | 导入信任链或调整仓库配置 |
| 连接超时或拒绝 | 节点到仓库网络不通 | 检查路由、策略与仓库可达性 |
密钥对象按命名空间隔离，建在了其他命名空间时引用不到，表现为凭据已配置却依然拉取失败。
手工拉取成功不等于工作负载能成功：模板里的凭据引用与命名空间必须与验证环境一致。