4. ImageService 接口详解：PullImage、ListImages、RemoveImage 等核心方法

在 CRI（Container Runtime Interface）架构中，ImageService 是负责容器镜像全生命周期管理的 gRPC 服务接口。kubelet 通过该接口与容器运行时（如 containerd、CRI-O）交互，完成镜像的拉取、查询、删除和状态检查。本章将深入剖析 ImageService 的核心方法，包括其请求/响应结构、关键字段语义以及实现中的常见陷阱。

4.1 ImageService 接口定义与整体流程

ImageService 定义在 kubelet/cri/pkg/apis/runtime/v1 的 image_service.proto 中。它包含以下 5 个核心 RPC 方法：

下图展示了 kubelet 通过 ImageService 与容器运行时交互的完整调用链路：

4.2 PullImage：镜像拉取的完整契约

PullImage 是 ImageService 中最核心、最复杂的写入方法。它负责从远程仓库下载镜像层并解包到本地存储。其请求和响应结构如下：

// PullImageRequest 定义了拉取镜像的请求参数
message PullImageRequest {
  // 镜像的完整引用，如 "docker.io/library/nginx:1.25"
  ImageSpec image = 1;

  // 认证信息，用于访问私有仓库
  AuthConfig auth = 2;

  // Pod 沙箱配置，用于确定拉取策略（如镜像拉取超时）
  PodSandboxConfig sandbox_config = 3;
}

// PullImageResponse 返回拉取后的镜像唯一标识
message PullImageResponse {
  // 镜像的引用字符串，通常为包含 digest 的规范格式
  string image_ref = 1;
}

4.3 ListImages：镜像缓存清单的获取

ListImages 用于获取节点上所有已拉取到本地的镜像列表。kubelet 的镜像垃圾回收器（Image GC）依赖此接口计算磁盘使用量并决定删除哪些镜像。

// ListImagesRequest 支持按过滤器筛选
message ListImagesRequest {
  // 可选过滤器，按镜像名称或标签筛选
  ImageFilter filter = 1;
}

// ListImagesResponse 返回镜像列表
message ListImagesResponse {
  repeated Image images = 1;
}

// Image 结构体描述单个镜像的详细信息
message Image {
  // 镜像的唯一 ID（通常为层哈希）
  string id = 1;

  // 镜像的所有引用（tag 列表）
  repeated string repo_tags = 2;

  // 镜像的所有 digest 引用
  repeated string repo_digests = 3;

  // 镜像大小（字节）
  uint64 size = 4;

  // 镜像的 manifest 或 index 的 digest
  string spec = 5;

  // 镜像的 pinned 状态（是否被标记为不可删除）
  bool pinned = 6;
}

4.4 RemoveImage：镜像删除的原子性要求

RemoveImage 用于从本地存储中删除指定镜像。该操作必须保证原子性——要么完全删除所有关联层，要么在失败时回滚到一致状态。

// RemoveImageRequest 指定要删除的镜像
message RemoveImageRequest {
  // 镜像引用（支持 ID、tag 或 digest）
  ImageSpec image = 1;
}

// RemoveImageResponse 为空，成功即表示删除完成
message RemoveImageResponse {}

4.5 ImageFsInfo：磁盘容量监控接口

ImageFsInfo 是 ImageService 中用于监控镜像存储文件系统使用情况的接口。kubelet 的节点压力驱逐（Node Pressure Eviction）和镜像 GC 阈值计算都依赖此接口。

// ImageFsInfoRequest 请求文件系统信息
message ImageFsInfoRequest {}

// ImageFsInfoResponse 返回文件系统使用详情
message ImageFsInfoResponse {
  repeated FilesystemUsage image_filesystems = 1;
}

// FilesystemUsage 描述单个文件系统的使用情况
message FilesystemUsage {
  // 挂载点或设备标识
  string mountpoint = 1;

  // 存储容量信息
  FilesystemCapacity capacity = 2;

  // 已使用的字节数
  uint64 used_bytes = 3;

  // 可用的 inode 数
  uint64 inodes_used = 4;
}

message FilesystemCapacity {
  uint64 available_bytes = 1;  // 可用空间
  uint64 capacity_bytes = 2;   // 总容量
  uint64 used_bytes = 3;       // 已用空间
}

4.6 核心方法对比与选型建议