使用Ansible拉取私有仓库Docker镜像失败求助

1. 确认模块参数的正确性 #

不管用community.docker.docker_image_pull还是docker_image，完整镜像名必须包含仓库域名，不能只填路径部分。很多人容易漏写前面的example.com，导致模块默认走Docker Hub。

• 正确参数写法示例：
  使用docker_image模块：

  - name: 拉取指定镜像
    community.docker.docker_image:
      name: example.com/some/path/to/image:sometag
      source: pull
      force_source: yes
  

  使用docker_image_pull模块：

  - name: 拉取指定镜像
    community.docker.docker_image_pull:
      name: example.com/some/path/to/image:sometag
  

  注意：name字段必须是完整的镜像引用，包含registry域名、路径、标签三者。

2. 检查远程主机的Docker配置 #

本地能拉取不代表远程主机配置没问题：

• 远程主机是否登录过example.com私有仓库？未登录的话，要么手动执行docker login example.com，要么在Ansible里用community.docker.docker_login模块提前完成登录。
• 如果example.com是自签名证书的私有仓库，需要在远程主机的/etc/docker/daemon.json中添加 insecure registry 配置：

  {
    "insecure-registries": ["example.com"]
  }
  

  配置后重启Docker服务：systemctl restart docker

3. 升级Ansible Docker模块版本 #

旧版本的docker_image模块存在参数解析bug，可能会错误处理带域名的镜像名：

• 执行命令升级community.docker集合到最新版：

  ansible-galaxy collection install community.docker --upgrade
  

4. 开启调试模式查看实际执行逻辑 #

加上-vvv参数运行playbook，查看模块实际调用的Docker API请求细节：

ansible-playbook your_playbook.yml -vvv

从调试输出里可以确认模块传递给Docker的镜像名是否正确，是否漏掉了example.com前缀。

5. 直接在远程主机验证命令 #

先排除Ansible的干扰，在远程主机手动执行docker pull example.com/some/path/to/image:sometag：

• 如果远程执行也报错，说明问题出在远程主机的Docker配置，和Ansible无关；
• 如果远程执行正常，再回到Ansible模块的参数和版本排查。

内容的提问来源于stack exchange，提问作者ulatedym