3. 镜像拉取流程详解：从 kubelet 到容器运行时（containerd/docker）的完整链路

当 Pod 被调度到节点后，kubelet 负责执行 Pod 生命周期管理，其中最关键的一步就是拉取容器镜像。理解从 kubelet 发起请求到容器运行时（CRI）最终完成镜像下载的完整链路，是定位“镜像拉取失败”类问题的核心基础。本节将拆解这一链路中的每个环节，并指出常见的故障点。

3.1 链路总览：四个关键阶段

镜像拉取请求从 kubelet 发出到最终写入本地存储，依次经过以下四个阶段：

1. kubelet 同步循环（SyncLoop）：kubelet 通过 List/Watch 机制感知 Pod 变更，触发 Pod 创建流程。
2. Pod 工作队列与状态管理：kubelet 将待创建的 Pod 加入工作队列，调用容器运行时接口（CRI）。
3. CRI shim 层（containerd/docker）：CRI shim 将 kubelet 的 gRPC 请求转换为容器运行时内部调用。
4. 镜像拉取引擎：容器运行时根据镜像名称、认证信息、镜像仓库地址执行拉取操作，最终解压并存储到本地。

3.2 阶段一：kubelet SyncLoop 与 Pod 创建触发

kubelet 的核心组件 SyncLoop 通过以下机制感知 Pod 变化：

• List/Watch API Server：kubelet 启动时通过 List 获取全量 Pod 列表，之后通过 Watch 持续监听增量变更。
• Pod 状态更新：当 Pod 被调度到当前节点（spec.nodeName == nodeName），kubelet 将其加入内部 Pod 缓存。
• SyncHandler 触发：SyncLoop 定期（默认 1 秒）检查待同步 Pod 列表，调用 syncPod() 方法。

在 syncPod() 中，kubelet 会依次执行：创建 Pod 沙箱（Sandbox）、配置网络、挂载卷、拉取业务容器镜像、启动容器。镜像拉取请求在此阶段被封装为 CRI 调用。

3.3 阶段二：CRI gRPC 调用与请求封装

kubelet 通过 CRI（Container Runtime Interface） 与容器运行时通信。CRI 是基于 gRPC 的协议，kubelet 作为客户端，容器运行时作为服务端。关键调用接口如下：

当 kubelet 调用 PullImage 时，会传入以下关键信息：

// PullImageRequest 简化结构
message PullImageRequest {
  // 镜像名称，如 "nginx:1.25"
  ImageSpec image = 1;
  // 认证信息，来自 imagePullSecrets
  AuthConfig auth = 2;
  // Pod 沙箱配置，用于传递代理等环境
  PodSandboxConfig sandbox_config = 3;
}

3.4 阶段三：CRI shim 层——containerd 与 docker 的差异

CRI shim 是 kubelet 与容器运行时之间的适配层。不同容器运行时的实现方式不同：

以 containerd 为例，CRI 请求到达后的处理流程如下：

1. containerd 的 CRI 插件接收 gRPC 请求。
2. CRI 插件调用 containerd 的 Image Service（images API）。
3. Image Service 检查本地镜像缓存（/var/lib/containerd/io.containerd.snapshotter.v1.overlayfs）。
4. 如果本地不存在，则触发远程拉取流程。

3.5 阶段四：镜像拉取引擎——下载、解压与存储

当容器运行时确认本地无缓存镜像后，进入远程拉取流程。该流程包含以下子步骤：

在 containerd 中，镜像层默认存储在 /var/lib/containerd/io.containerd.snapshotter.v1.overlayfs/ 目录下。每个镜像层对应一个子目录，通过 overlayfs 实现联合挂载。

3.6 链路故障排查命令速查表

以下命令覆盖了从 kubelet 到容器运行时的每个环节，用于快速定位镜像拉取失败的原因：