Golang中的容器运行时(CRI)调用技巧 Go语言自动化管理Containerd/Docker

containerd的CRI接口不能直接用client.NewClient，因其调用的是containerd自有API而非Kubernetes定义的CRI协议；CRI需通过k8s.io/cri-api生成gRPC client连接CRI endpoint（如/run/containerd/containerd.sock），使用insecure credentials和WithBlock，并确保版本与集群一致。

containerd 的 CRI 接口为什么不能直接用 client.NewClient？

因为 containerd 官方 client（containerd/client.NewClient）走的是 containerd 自有 API，不是 CRI；CRI 是 Kubernetes 定义的抽象接口，由 cri-containerd 或 containerd 内置的 CRI 插件实现，监听在 Unix socket（如 /run/containerd/containerd.sock）或 gRPC 端口上，但协议是 runtime.v1（Kubernetes v1.24+ 用 runtime.v1，旧版是 runtime.v1alpha2）。

• 直接调 containerd/client.NewClient 只能管理 containerd 原生命令（如 ctr 能干的事），无法创建 PodSandbox、拉镜像给 kubelet 用、设置 sandbox config 中的 PodAnnotations 等 CRI 特有字段
• CRI client 必须用 k8s.io/cri-api/pkg/apis/runtime/v1 生成的 gRPC client，连的是 CRI endpoint，不是 containerd daemon endpoint
• 常见错误：用 containerd/client 尝试调 RunPodSandbox → 报 method not found 或连接成功但返回空响应

如何用 Go 正确构造 CRI gRPC client 连接 containerd？

核心是用 grpc.Dial 连 CRI socket，并指定正确的 WithTransportCredentials 和 WithBlock —— containerd 的 CRI 插件默认不启用 TLS，所以必须用 credentials.NewInsecure()，否则 dial 会卡住或报 connection refused。

• socket 地址通常是 /run/containerd/containerd.sock，但要确认 containerd 配置中 [plugins."io.containerd.grpc.v1.cri"] 下的 endpoint 是否被显式改过
• 必须加 grpc.WithBlock()，否则 grpc.Dial 异步建连，后续调 RuntimeServiceClient.ListContainers 可能 panic："client is nil"
• 版本对齐很关键：k8s.io/cri-api 的 module 版本必须和集群实际 CRI 版本一致（比如 k8s 1.27 集群就得用 k8s.io/cri-api v0.27.0），否则 ListContainersResponse 字段缺失或类型不匹配

conn, err := grpc.Dial("/run/containerd/containerd.sock",
    grpc.WithTransportCredentials(insecure.NewCredentials()),
    grpc.WithBlock(),
)
if err != nil {
    log.Fatal(err)
}
client := runtimev1.NewRuntimeServiceClient(conn)

Docker 作为运行时还能用 CRI 吗？

不能。Docker 自 2020 年底起已移除内置 CRI 实现，dockerd 不再提供 /run/dockershim.sock；kubeadm 1.24+ 默认禁用 dockershim，Kubernetes 彻底弃用 Docker 作为 CRI 运行时。

Joker AIx

一站式AI创意生产平台，覆盖图像、视频、音频、文案全品类创作

下载

• 如果你看到代码里还 import k8s.io/cri-api/pkg/apis/runtime/v1alpha2 并连 /var/run/dockershim.sock，那基本是遗留项目，跑在 kubelet --container-runtime=docker 的老集群上，且已不可迁移至新版 Kubernetes
• 想用 Docker 引擎又需要 CRI 能力？唯一可行路径是套一层 shim，比如 cri-dockerd（独立维护的桥接组件），但它只支持到 k8s 1.26，且需手动安装、配置 kubelet 的 --container-runtime-endpoint
• 生产环境建议直接切 containerd：它原生支持 CRI，启动快、资源占用低，crictl 命令行为与 docker 高度兼容

用 crictl 调试时发现 ListContainers 返回空，但容器明明在跑？

大概率是 RuntimeServiceClient.ListContainers 的 filter 参数没设对。CRI 的 list 默认只返回 CONTAINER_CREATED 和 CONTAINER_RUNNING 状态的容器，但 crictl ps 默认显示所有状态（包括 CONTAINER_EXITED），而 crictl ps -a 才等价于 CRI 的全量查询。

立即学习“go语言免费学习笔记（深入）”；

• Go 里若想查全部容器，得显式传 &runtimev1.ContainerFilter{State: &runtimev1.ContainerStateValue{State: runtimev1.ContainerState_CONTAINER_UNKNOWN}}
• 另一个常见坑：filter 中的 Id 或 PodSandboxId 是完整 hash（64 字符），不是 crictl ps 输出的短 ID；传错就过滤掉全部结果
• containerd 的 CRI 插件默认每 5 分钟清理一次已退出容器（maxContainerLogSize 和 containerdConfig.gc 相关），所以 CONTAINER_EXITED 容器可能根本不在 list 结果里，哪怕你用了 CONTAINER_UNKNOWN