K8s无法拉取本地Docker镜像报ImagePullBackOff错误解决方法

问题根因 #

报错核心是两个操作/配置不匹配问题：

1. 多数新版K8s默认使用containerd作为容器运行时，kubelet直接读取containerd的镜像存储，之前执行docker load把镜像导入的是Docker的本地存储，containerd完全感知不到这个镜像。
2. 配置里写的镜像名myapp:1.0没有带仓库地址，kubelet会自动把它补全为docker.io/library/myapp:1.0，即使镜像存在于本地运行时存储，如果镜像的完整标签和补全后的地址不匹配，kubelet还是会判定本地无镜像，去远端公共仓库拉取。

操作步骤 #

1. 确认集群容器运行时 #

执行命令查看节点运行时类型：

kubectl get nodes -o wide

查看输出中CONTAINER-RUNTIME字段值：

• 字段值前缀为containerd://：运行时为containerd，需要重新导入镜像到containerd存储
• 字段值前缀为docker://：运行时为Docker，跳过镜像导入步骤，直接做标签修正

2. 导入镜像到对应运行时存储（仅containerd环境需要） #

如果有原始的myapp.tar.gz包，直接执行导入命令，注意必须指定k8s.io命名空间，否则kubelet无法识别镜像：

ctr -n k8s.io images import myapp.tar.gz

如果原始tar包已经删除，先把Docker里的镜像导出再导入：

docker save myapp:1.0 -o myapp-1.0.tar
ctr -n k8s.io images import myapp-1.0.tar

导入完成后执行命令验证：

ctr -n k8s.io images ls | grep myapp

输出中存在docker.io/library/myapp:1.0相关记录即为导入成功。

3. 修正镜像标签匹配kubelet解析规则 #

为了匹配kubelet自动补全的镜像地址，需要给本地镜像打对应标签：

• containerd环境：

ctr -n k8s.io images tag myapp:1.0 docker.io/library/myapp:1.0

• Docker环境：

docker tag myapp:1.0 docker.io/library/myapp:1.0

确认Helm values配置中的imagePullPolicy字段值为IfNotPresent，不需要修改为其他值。

4. 重建Pod验证结果 #

删除之前状态为ImagePullBackOff的故障Pod，Deployment会自动拉起新Pod：

kubectl delete pod -n cs1 myapp-7589554bd4-4pprj

等待10秒后查看Pod状态：

kubectl get pods -n cs1

Pod状态变为Running即为修复完成。

避坑说明 #

• 后续加载本地镜像时，如果集群运行时是containerd，统一使用ctr -n k8s.io images import <镜像包路径>命令导入，不要用docker load。
• 镜像拉取策略保持IfNotPresent即可，禁止配置为Always，该策略会强制kubelet每次启动Pod都去远端校验镜像，忽略本地已存在的镜像文件。
• 单节点集群只需要在当前主节点操作镜像导入即可，多节点集群需要在所有可能调度该Pod的节点上都完成镜像导入。

内容的提问来源于stack exchange，提问作者mcqueenvh