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>]`。数字为正整数。单位可以是 `B`（字节）、`K`（KiB，1024B）、`M`（MiB）、`G`（GiB）、`T`（TiB）或 `P`（PiB）。省略单位默认为字节。在 community.docker 3.6.0 之前，不允许使用单位。
memswap 字符串	构建的总内存限制（内存 + 交换），格式为 `<number>[<unit>]`，或者特殊值 `unlimited` 或 `-1` 表示无限交换使用。数字为正整数。单位可以是 `B`（字节）、`K`（KiB，1024B）、`M`（MiB）、`G`（GiB）、`T`（TiB）或 `P`（PiB）。省略单位默认为字节。在 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 请求的超时时间。请提供一个正整数，表示秒数。
标签字典在 community.docker 3.6.0 中添加	键值对字典。
网络字符串	用于 `RUN` 构建指令的网络。
nocache 布尔值	构建镜像时不使用缓存。选项 `false` ← (默认) `true`
路径路径 / 必需	与 state ‘present’ 一起使用以构建镜像。将是包含构建镜像的上下文和 Dockerfile 的目录的路径。
平台字符串在 community.docker 1.1.0 中添加	格式为 `os[/arch[/variant]]` 的平台。
pull 布尔值	构建镜像时，下载 Dockerfile 中 FROM 镜像的任何更新。选项 `false` ← (默认) `true`
rm 布尔值	构建后移除中间容器。选项 `false` `true` ← (默认)
shm_size 字符串在 community.docker 3.6.0 中添加	`/dev/shm` 的大小，格式为 `<number>[<unit>]`。数字为正整数。单位可以是 `B`（字节）、`K`（Kibibyte，1024B）、`M`（Mebibyte）、`G`（Gibibyte）、`T`（Tebibyte）或 `P`（Pebibyte）。省略单位默认为字节。如果完全省略大小，Docker 守护程序将使用 `64M`。
target 字符串	构建镜像时，指定中间构建阶段的名称作为最终镜像的最终阶段。
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` 文件。
debug 布尔值	调试模式选项 `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 字符串 / 必需	镜像名称。名称格式之一：`name`、`repository/name`、`registry_server:port/name`。推送或拉取镜像时，可以通过附加 `:tag_name` 来可选地包含标签。请注意，镜像 ID（哈希值）仅支持 `state=absent`，对于 `state=present` 和 `source=load`，以及对于 `state=present` 和 `source=local`。
pull 字典在 community.docker 1.3.0 中添加	指定用于拉取镜像的选项。
平台字符串	拉取镜像时，请求此特定平台。请注意，此值不用于确定是否需要拉取镜像。不过，这将来可能会在次要版本中更改。
push 布尔值	将镜像推送到注册表。将注册表指定为 `name` 或 `repository` 参数的一部分。选项 `false` ← (默认) `true`
repository 字符串	与 `state=present` 一起使用以标记镜像。预期格式为 `repository:tag`。如果没有提供标签，将使用 `tag` 参数的值或 `latest`。如果 `push=true`，`repository` 必须包含注册表，否则将假定它属于默认注册表（Docker Hub）。
source 字符串	确定模块将尝试从中检索镜像的位置。使用 `build` 从 `Dockerfile` 构建镜像。使用此值时，必须指定 `build.path`。使用 `load` 从 `.tar` 文件加载镜像。使用此值时，必须指定 `load_path`。使用 `pull` 从注册表拉取镜像。使用 `local` 确保镜像已存在于本地 Docker 守护进程中。这意味着模块不会尝试构建、拉取或加载镜像。选项 `"build"` `"load"` `"pull"` `"local"`
state 字符串	对镜像的状态进行断言。当 `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` 命令行工具而不是 paramiko。选项 `false` ← (默认) `true`
validate_certs 别名：tls_verify 布尔值	使用 TLS 加密与 API 的连接并验证 Docker 主机服务器的真实性。如果任务中未指定此值，则将使用环境变量 `DOCKER_TLS_VERIFY` 的值。如果未设置环境变量，则将使用默认值。选项 `false` ← (默认) `true`

属性 

属性	支持	描述
action_group	操作组： community.docker.docker, docker	在 `module_defaults` 中使用 `group/docker` 或 `group/community.docker.docker` 为此模块设置默认值。
check_mode	支持：部分尝试拉取镜像时，模块假定在检查模式下始终已更改。	可以在 `check_mode` 下运行并返回更改状态预测，而无需修改目标。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在 `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)

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

作者

集合链接