community.docker.docker_image 模块 – 管理 Docker 镜像

注意

此模块是 community.docker 集合 (版本 4.1.0) 的一部分。

如果您正在使用 ansible 包，您可能已经安装了这个集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.docker。您需要进一步的要求才能使用此模块，请参阅 要求 了解详细信息。

要在 playbook 中使用它，请指定：community.docker.docker_image。

概要

• 构建、加载或拉取镜像，使镜像可用于创建容器。还支持标记镜像、推送镜像以及将镜像存档到 .tar 文件。

要求

以下要求需要在执行此模块的主机上满足。

• Docker API >= 1.25

• backports.ssl_match_hostname（在 Python 2 上使用 TLS 时）

• paramiko（当使用 SSH 和 use_ssh_client=false 时）

• pyOpenSSL（当使用 TLS 时）

• pywin32（当在 Windows 32 上使用命名管道时）

• requests

参数

参数	注释
api_version 别名：docker_api_version 字符串	在 Docker 主机上运行的 Docker API 版本。 默认为此集合和 Docker 守护进程支持的最新 API 版本。 如果任务中未指定该值，则将使用环境变量 DOCKER_API_VERSION 的值。如果未设置环境变量，则将使用默认值。 默认值： "auto"
archive_path 路径	与 state=present 一起使用，将镜像存档到 .tar 文件。
build 字典	指定用于构建镜像的选项。
args 字典	提供一个 key:value 构建参数的字典，该字典映射到 Dockerfile ARG 指令。 Docker 期望该值为字符串。为了方便起见，任何非字符串值都将转换为字符串。
cache_from 列表 / 元素=字符串	要作为缓存源考虑的镜像名称列表。
container_limits 字典	应用于构建过程创建的每个容器的限制字典。
cpusetcpus 字符串	允许执行的 CPU。 例如，0-3 或 0,1。
cpushares 整数	CPU 份额（相对权重）。
memory 字符串	构建的内存限制，格式为 <number>[<unit>]。Number 是一个正整数。Unit 可以是 B (字节)、K (千字节，1024B)、M (兆字节)、G (吉字节)、T (太字节) 或 P (拍字节)。 省略单位则默认为字节。 在 community.docker 3.6.0 之前，不允许使用单位。
memswap 字符串	构建的总内存限制（内存 + 交换空间），格式为 <number>[<unit>]，或者特殊值 unlimited 或 -1，表示无限制交换空间使用。Number 是一个正整数。Unit 可以是 B (字节)、K (千字节，1024B)、M (兆字节)、G (吉字节)、T (太字节) 或 P (拍字节)。 省略单位则默认为字节。 在 community.docker 3.6.0 之前，不允许使用单位，也不允许使用特殊值 unlimited。
dockerfile 字符串	与 state=present 和 source=build 一起使用，以提供在构建镜像时要使用的 Dockerfile 的替代名称。 这还可以包含相对路径（相对于 build.path）。
etc_hosts 字典	添加到构建容器中的 /etc/hosts 的额外主机，作为主机名到 IP 地址的映射。 除了 IP 地址之外，还可以使用特殊值 host-gateway，该值解析为主机的网关 IP，并允许构建容器连接到主机上运行的服务。
http_timeout 整数	镜像构建操作期间 HTTP 请求的超时时间。为秒数提供一个正整数值。
labels 字典 在 community.docker 3.6.0 中添加	键值对的字典。
network 字符串	用于 RUN 构建指令的网络。
nocache 布尔值	构建镜像时不使用缓存。 选项 false ← (默认) true
路径 路径 / 必需	与状态 ‘present’ 一起使用以构建镜像。将是包含构建镜像的上下文和 Dockerfile 的目录的路径。
平台 字符串 在 community.docker 1.1.0 中添加	格式为 os[/arch[/variant]] 的平台。
拉取 布尔值	构建镜像时，下载 Dockerfile 中 FROM 镜像的任何更新。 选项 false ← (默认) true
rm 布尔值	构建后移除中间容器。 选项 false true ← (默认)
shm_size 字符串 在 community.docker 3.6.0 中添加	/dev/shm 的大小，格式为 <数字>[<单位>]。数字为正整数。单位可以是 B (字节), K (千字节，1024B), M (兆字节), G (吉字节), T (太字节) 或 P (拍字节)。 省略单位则默认为字节。如果完全省略大小，Docker 守护程序将使用 64M。
目标 字符串	构建镜像时，按名称指定一个中间构建阶段作为最终镜像的阶段。
use_config_proxy 布尔值	如果设置为 true 并且在 docker 客户端配置中指定了代理配置（默认为 $HOME/.docker/config.json），则会在正在构建的容器中设置相应的环境变量。 选项 false true
ca_path 别名: ca_cert, tls_ca_cert, cacert_path 路径	通过提供 CA 证书文件的路径，在执行服务器验证时使用 CA 证书。 如果未在任务中指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定目录下的文件 ca.pem。 此选项之前名为 ca_cert，并在 community.docker 3.6.0 中重命名为 ca_path。旧名称已添加为别名，仍然可以使用。
client_cert 别名: tls_client_cert, cert_path 路径	客户端 TLS 证书文件的路径。 如果未在任务中指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定目录下的文件 cert.pem。
client_key 别名: tls_client_key, key_path 路径	客户端 TLS 密钥文件的路径。 如果未在任务中指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定目录下的文件 key.pem。
调试 布尔值	调试模式 选项 false ← (默认) true
docker_host 别名: docker_url 字符串	用于连接 Docker API 的 URL 或 Unix 套接字路径。要连接到远程主机，请提供 TCP 连接字符串。例如，tcp://192.0.2.23:2376。如果使用 TLS 加密连接，则模块会自动将连接 URL 中的 tcp 替换为 https。 如果未在任务中指定该值，则将改为使用环境变量 DOCKER_HOST 的值。如果未设置环境变量，则将使用默认值。 默认值: "unix:///var/run/docker.sock"
force_absent 布尔值	与 state=absent 一起使用，以取消标记并删除所有与指定名称匹配的镜像。 选项 false ← (默认) true
force_source 布尔值	与 state=present 一起使用，以在镜像已存在时构建、加载或拉取镜像（取决于 source 选项的值）。 选项 false ← (默认) true
force_tag 布尔值	与 state=present 一起使用，以强制标记镜像。 选项 false ← (默认) true
load_path 路径	与 state=present 一起使用，以从 .tar 文件加载镜像。 如果要加载镜像，请设置 source=load。
名称 字符串 / 必需	镜像名称。名称格式将是以下之一：name, repository/name, registry_server:port/name。推送或拉取镜像时，名称可以选择性地包含标签，方法是附加 :tag_name。 请注意，仅对于 state=absent、state=present 且 source=load 以及 state=present 且 source=local 才支持镜像 ID（哈希）。
拉取 字典 在 community.docker 1.3.0 中添加	指定用于拉取镜像的选项。
平台 字符串	拉取镜像时，请求此特定平台。 请注意，此值不用于确定是否需要拉取镜像。但这可能会在未来的次要版本中更改。
推送 布尔值	将镜像推送到注册表。将注册表指定为 name 或 repository 参数的一部分。 选项 false ← (默认) true
仓库 字符串	与 state=present 一起使用以标记镜像。 期望格式为 repository:tag。如果未提供标签，将使用 tag 参数的值或 latest。 如果 push=true，则 repository 必须包含注册表，否则将假定属于默认注册表（Docker Hub）。
来源 字符串	确定模块将尝试从何处检索镜像。 使用 build 从 Dockerfile 构建镜像。使用此值时，必须指定 build.path。 使用 load 从 .tar 文件加载镜像。使用此值时，必须指定 load_path。 使用 pull 从注册表拉取镜像。 使用 local 确保镜像已在本地 docker 守护程序上可用。这意味着该模块不会尝试构建、拉取或加载镜像。 选项 "build" "load" "pull" "local"
状态 字符串	对镜像的状态进行断言。 当 absent 时，将移除镜像。使用 force 选项取消标记并删除所有与提供的名称匹配的镜像。 当 present 时，使用提供的名称和标签检查镜像是否存在。如果未找到镜像或使用了 force 选项，则将根据 source 选项拉取、构建或加载镜像。 选项 "absent" "present" ← (默认)
tag 字符串	用于在拉取时选择镜像。将在推送、标记或构建时添加到镜像。默认为 latest。 如果 name 参数格式为 name:tag，则 name 中的 tag 值将优先。 默认值: "latest"
timeout 整数	等待 API 响应的最大时长（秒）。 如果任务中未指定该值，则将使用环境变量 DOCKER_TIMEOUT 的值。如果未设置环境变量，则将使用默认值。 默认值: 60
tls 布尔值	通过使用 TLS 来保护与 API 的连接，而不验证 Docker 主机服务器的真实性。请注意，如果 validate_certs 也设置为 true，则它将优先。 如果任务中未指定该值，则将使用环境变量 DOCKER_TLS 的值。如果未设置环境变量，则将使用默认值。 选项 false ← (默认) true
tls_hostname 字符串	在验证 Docker 主机服务器的真实性时，提供服务器的预期名称。 如果任务中未指定该值，则将使用环境变量 DOCKER_TLS_HOSTNAME 的值。如果未设置环境变量，则将使用默认值。 请注意，此选项在旧版本中的默认值为 localhost。它已在 community.docker 3.0.0 中删除。
use_ssh_client 布尔值 在 community.docker 1.5.0 中添加	对于 SSH 传输，使用 ssh CLI 工具而不是 paramiko。 选项 false ← (默认) true
validate_certs 别名：tls_verify 布尔值	通过使用 TLS 并验证 Docker 主机服务器的真实性来保护与 API 的连接。 如果任务中未指定该值，则将使用环境变量 DOCKER_TLS_VERIFY 的值。如果未设置环境变量，则将使用默认值。 选项 false ← (默认) true

属性

属性	支持	描述
action_group	操作组: community.docker.docker, docker	在 module_defaults 中使用 group/docker 或 group/community.docker.docker 为此模块设置默认值。
check_mode	支持: 部分支持 尝试拉取镜像时，模块假定这在 check 模式下始终会更改。	可以在 check_mode 中运行并返回更改的状态预测，而无需修改目标。
diff_mode	支持: 不支持	当处于 diff 模式时，将返回有关已更改（或可能需要在 check_mode 中更改）的内容的详细信息。

备注

注意

• 构建镜像使用 Docker 守护程序的 API 完成。无法以这种方式使用 BuildKit / buildx。使用 community.docker.docker_image_build 使用 BuildKit 构建镜像。

• 通过为每个任务提供参数或定义环境变量来连接到 Docker 守护程序。您可以定义 DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS, DOCKER_TLS_VERIFY 和 DOCKER_TIMEOUT。如果您正在使用 docker machine，请运行产品附带的脚本来设置环境。它将为您设置这些变量。有关更多详细信息，请参阅 https://docs.docker.net.cn/machine/reference/env/。

• 此模块不使用 Docker SDK for Python 与 Docker 守护程序通信。它使用来自 Docker SDK 或 Python 的代码，该代码包含在此集合中。

另请参阅

另请参阅

community.docker.docker_image_build

使用 Docker buildx 构建 Docker 镜像。

community.docker.docker_image_export

导出（存档）Docker 镜像。

community.docker.docker_image_info

检查 Docker 镜像。

community.docker.docker_image_load

从存档加载 Docker 镜像。

community.docker.docker_image_pull

从注册表拉取 Docker 镜像。

community.docker.docker_image_push

将 Docker 镜像推送到注册表。

community.docker.docker_image_remove

移除 Docker 镜像。

community.docker.docker_image_tag

使用新名称和/或标签标记 Docker 镜像。

示例

- name: Pull an image
  community.docker.docker_image:
    name: pacur/centos-7
    source: pull
    # Select platform for pulling. If not specified, will pull whatever docker prefers.
    pull:
      platform: amd64

- name: Tag and push to docker hub
  community.docker.docker_image:
    name: pacur/centos-7:56
    repository: dcoppenhagan/myimage:7.56
    push: true
    source: local

- name: Tag and push to local registry
  community.docker.docker_image:
    # Image will be centos:7
    name: centos
    # Will be pushed to localhost:5000/centos:7
    repository: localhost:5000/centos
    tag: 7
    push: true
    source: local

- name: Add tag latest to image
  community.docker.docker_image:
    name: myimage:7.1.2
    repository: myimage:latest
    # As 'latest' usually already is present, we need to enable overwriting of existing tags:
    force_tag: true
    source: local

- name: Remove image
  community.docker.docker_image:
    state: absent
    name: registry.ansible.com/chouseknecht/sinatra
    tag: v1

- name: Build an image and push it to a private repo
  community.docker.docker_image:
    build:
      path: ./sinatra
    name: registry.ansible.com/chouseknecht/sinatra
    tag: v1
    push: true
    source: build

- name: Archive image
  community.docker.docker_image:
    name: registry.ansible.com/chouseknecht/sinatra
    tag: v1
    archive_path: my_sinatra.tar
    source: local

- name: Load image from archive and push to a private registry
  community.docker.docker_image:
    name: localhost:5000/myimages/sinatra
    tag: v1
    push: true
    load_path: my_sinatra.tar
    source: load

- name: Build image and with build args
  community.docker.docker_image:
    name: myimage
    build:
      path: /path/to/build/dir
      args:
        log_volume: /var/log/myapp
        listen_port: 8080
    source: build

- name: Build image using cache source
  community.docker.docker_image:
    name: myimage:latest
    build:
      path: /path/to/build/dir
      # Use as cache source for building myimage
      cache_from:
        - nginx:latest
        - alpine:3.8
    source: build

返回值

此处记录了常见的返回值 此处，以下是此模块独有的字段

键	描述
image 字典	受影响镜像的镜像检查结果。 返回: 成功 示例: {}
stdout 字符串 在 community.docker 1.0.0 中添加	构建镜像时 Docker 的构建输出。 返回: 成功 示例: ""

作者

• Pavel Antonov (@softzilla)

• Chris Houseknecht (@chouseknecht)

• Sorin Sbarnea (@ssbarnea)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助 (Docker)
• 寻求帮助 (Docker Compose)
• 寻求帮助 (Docker Swarm)
• 提交错误报告
• 请求功能
• 沟通