现象：明明镜像就在本地，为什么Pod拉取失败？

近期不少Kubernetes初学者甚至资深开发者都遇到一个令人困惑的问题：在本地使用docker build成功构建了一个镜像，并打上了明确的标签（如my-app:latest），随后在同一个节点上启动Pod，却反复进入ImagePullBackOff状态。kubectl describe pod给出的错误信息往往是“Failed to pull image ...: rpc error: code = NotFound”。开发者不禁疑惑：“镜像标签明明与本地的Docker daemon中的完全一致，为什么Kubernetes就是找不到它？”

这一现象在单节点开发环境（如Minikube、Kind或Docker Desktop自带的Kubernetes）中尤为常见，其背后反映的是Kubernetes镜像拉取机制与本地Docker缓存之间的根本差异。

核心误解：Kubernetes并不直接使用Docker daemon中的镜像

许多开发者的直觉是：Kubernetes既然运行在Docker之上（针对使用Docker作为容器运行时的场景），那么本地docker images列出的镜像应该自然可供Pod使用。然而，这一假设并不成立。Kubernetes的kubelet在调度Pod时，会依据容器的image字段向配置的镜像仓库（Registry）发起拉取请求，而不是查询本地Docker daemon的缓存。即便镜像存在于本地，kubelet仍然会尝试从仓库下载，除非显式告知它“不要拉取”。

具体来说，有三个关键因素决定了Pod的行为：

  1. imagePullPolicy：默认为IfNotPresent或Always（取决于镜像标签是否为:latest）。当策略为Always（:latest默认策略）时，kubelet每次都会尝试拉取最新版本，而不会检查本地是否存在。
  2. 镜像仓库地址：如果image字段写的是my-app:latest（无仓库前缀），kubelet会默认从Docker Hub拉取；若本地镜像并未上传至任何远程仓库，便会拉取失败。
  3. 节点上的运行时缓存：即便策略为IfNotPresent，kubelet也只会检查该节点上容器运行时（如containerd或CRI-O）自己的镜像缓存，而非用户Docker CLI的缓存。两者可能并不相同。

深入分析：为什么“同一个标签”不等于同一个镜像？

问题的另一层根源在于“标签的模糊性”。本地docker build -t my-app:latest将镜像存储于Docker daemon的本地命名空间中。而Kubernetes默认的镜像拉取行为是向公共Registry查询。即便开发者尝试使用imagePullPolicy: Never强制使用本地镜像，容器运行时（如containerd）的镜像列表也可能与Docker daemon的列表不同步。尤其在Docker Desktop环境中，Kubernetes使用的容器运行时并不是直接调用docker命令，而是通过独立的CRI实现。

此外，常见的开发工具如Minikube在启动时为节点创建了一个独立的虚拟机环境。在该虚拟机中运行的是containerd或CRI-O，而不是宿主机上的Docker daemon。所以docker build构建的镜像并不会自动“同步”到Minikube的节点内部。同样，Kind（Kubernetes in Docker）也是通过Docker容器模拟节点，节点的容器运行时并不直接访问宿主机的Docker镜像。

解决方案：三步走策略

1. 正确设置imagePullPolicy

对于本地开发，推荐使用imagePullPolicy: IfNotPresent或Never，并确保标签不含:latest（或显式设置策略为IfNotPresent）。例如：

containers:
- name: my-app
  image: my-app:dev-123
  imagePullPolicy: IfNotPresent

2. 将镜像导入到Kubernetes节点

  • 使用Minikube：执行minikube image load my-app:latest，将本地镜像加载到Minikube的容器运行时中。
  • 使用Kind：执行kind load docker-image my-app:latest，将镜像注入到Kind集群节点。
  • 使用Docker Desktop：通常Docker Desktop会自动同步，但若遇到问题，可尝试重启Kubernetes或使用docker save与ctr命令手动导入。

3. 使用本地私有Registry

对于团队协作或持续集成场景，更推荐在本地运行一个私有Registry（如docker run -d -p 5000:5000 registry:2），将镜像推送到该Registry，然后Pod的image字段指向localhost:5000/my-app。这样既保持了拉取逻辑的一致性，又无需反复手动导入。

总结：理解Kubernetes的拉取哲学

ImagePullBackOff本质上是一个信号，它告诉开发者：Kubernetes认为镜像不在它所能访问的任何仓库中，且它不会主动去“借用”本地Docker的缓存。这一设计保证了生产环境的一致性——所有节点都从同一仓库拉取，避免“我的节点上有镜像，你的节点没有”造成的版本漂移。

对于本地开发而言，掌握镜像加载与拉取策略的配置是绕过此坑的关键。开发者应抛弃“Docker命令行即全局”的思维，转而理解Kubernetes以容器运行时为中心、以仓库为镜像来源的架构。当再次遇到ImagePullBackOff时，不妨先检查imagePullPolicy、确认镜像是否真正存在于节点运行时中，而非仅存在于Docker CLI的images列表里。

记住：“本地”对于Docker daemon和对于Kubernetes节点，往往是两个截然不同的世界。