如何用Ansible原生模块管理containerd、容器及镜像？

API 探路者

2026-7-25

关于Ansible管理containerd的方案说明

核心结论

Ansible目前没有专门针对containerd的原生模块，你使用community.docker.docker_host_info模块失败的原因是：该模块依赖Docker Engine API，而containerd提供的是独立的GRPC API，两者协议不兼容，直接连接containerd的socket必然出现连接重置报错。

除nerdctl/自定义实现外的可行方案

使用containerd官方CLI工具ctr：通过Ansible的command或shell模块直接调用ctr命令管理容器、镜像，这是最直接的官方方案，无需额外安装依赖，功能覆盖容器生命周期、镜像管理、快照操作等核心场景，示例：
```
- name: 列出所有containerd容器
  command: ctr containers list -a
  register: containerd_containers
```
部署Docker兼容层（containerd-shim-docker-v2）：如果需要继续复用Ansible Docker模块，可以部署Docker兼容的shim组件，让containerd模拟Docker API的行为。配置完成后，Docker模块可以像连接Docker socket一样连接兼容层的socket，但注意该方案仅支持部分Docker API功能，需要额外配置环境。
GRPC API直接调用（进阶场景）：使用Ansible的command模块配合grpcurl工具，直接调用containerd的GRPC API。这种方式需要熟悉containerd的API定义，处理请求相对繁琐，适合有定制化需求的场景，示例：
```
- name: 获取containerd版本信息
  command: grpcurl -unix /run/containerd/containerd.sock containerd.services.version.v1.VersionService/Version
  register: containerd_version
```