面向初级运维，使用 Linux 节点和稳定 Kubernetes API。命令按 Bash 编写。本文为教学故障场景，日志及结果为示意，不冒充生产实测；执行前确认 context、命名空间和权限。
一、遭遇情况：Pod 反复显示 ImagePullBackOff
部署后容器还没开始运行，kubectl logs 也读不到应用日志。状态先是 ErrImagePull，过一会儿变成 ImagePullBackOff。
这表示镜像拉取失败后进入退避重试，并不是新的根因。本篇案例设定为镜像标签拼错；同样的展示状态也可能来自仓库认证、网络、证书或架构问题。
二、原因分析：谁在拉镜像
Pod 分配到节点后，由节点侧 kubelet 与容器运行时协调镜像准备。跳板机上能拉取，不能证明目标节点出口正常；在某台机器执行 docker login，也不等于集群所有节点的 containerd 已获得凭据。
不同集群采用不同运行时与凭据集成。不要先修改 Docker daemon 配置，更不要把 Docker 系列里的所有修复命令直接照搬到 Kubernetes 节点。
三、排查思路：先拿到真实拉取错误
kubectl get pod 目标Pod -n 目标命名空间 -o wide
kubectl describe pod 目标Pod -n 目标命名空间
kubectl get pod 目标Pod -n 目标命名空间 -o jsonpath='{.spec.containers[*].image}{"\n"}{.spec.imagePullSecrets[*].name}{"\n"}'
把名称替换为实际值，读取 Events 中最初的 Failed 消息，而不只读最后的 BackOff。
| 拉取错误线索 | 下一步 |
|---|---|
| manifest unknown / not found | 仓库路径和标签是否存在 |
| unauthorized / denied | 拉取身份、仓库权限与凭据引用 |
| timeout / lookup | 目标节点 DNS、出口、代理 |
| x509 | 节点运行时的仓库信任配置和时间 |
| no matching manifest | 节点平台与镜像提供的平台 |
节点信息读取需要相应权限。核查运行时时使用集群文档指定的 CRI endpoint 和工具，crictl 的手动测试仍不自动复用 Pod 的所有拉取凭据。
四、实践：故意引用一个不存在的镜像标签
保存 kt04-image.yaml，只在测试集群应用：
apiVersion: v1
kind: Namespace
metadata:
name: kt04
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
namespace: kt04
spec:
replicas: 1
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: nginx:kt04-tag-that-does-not-exist
kubectl apply -f kt04-image.yaml
kubectl describe pod -n kt04 -l app=web
kubectl get pods -n kt04
在节点能够访问仓库的前提下，预期错误指向标签不存在。若先遇到网络超时或限流，说明环境还存在更前面的阻碍，不能声称已复现单纯标签错误。
修正实验 Deployment：
kubectl set image deployment/web web=nginx:stable-alpine -n kt04
kubectl rollout status deployment/web -n kt04 --timeout=180s
kubectl get pods -n kt04 -o wide
这是演示用的可读标签。生产发布应记录经过测试的版本或 digest，避免可变标签让同一部署定义对应不同内容。
五、私有仓库的修复不能只停在登录成功
若根因是私有仓库认证，检查 imagePullSecrets 是否指向同一命名空间的有效 Secret，类型是否适合镜像仓库认证，仓库地址是否与镜像引用匹配。Secret 只存在于另一个命名空间时，不能直接跨命名空间引用。
可以使用组织批准的凭据分发流程，将 Docker 配置型 Secret 放到目标命名空间。下面是结构片段，approved-regcred 是需要事先准备的名字，不含真实密码：
apiVersion: v1
kind: Pod
metadata:
name: private-image-reference
namespace: kt04
spec:
imagePullSecrets:
- name: approved-regcred
containers:
- name: app
image: registry.example.test/team/app:approved-version
此片段只演示引用关系，不是可直接拉取的公共镜像实验。不要把真实 token 放到博客、命令截图或公开 YAML；也不要通过关闭证书验证来“修复”私有仓库信任问题。
六、验证与总结
确认新的事件已完成拉取与启动、容器 Ready，并检查实际镜像信息是否符合发布目标。若只是本节点命中缓存，也不能据此证明所有节点以后都能从仓库正常拉取。
ImagePullBackOff 的闭环是：读首次具体错误 → 确认目标镜像与节点 → 修正对应的仓库、凭据或连接层 → 等待容器创建 → 验证版本与业务。应用还没启动时，缺少应用日志是合理现象。