community.docker.docker_container 模块 – 管理 Docker 容器

注意

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

如果您使用的是 ansible 软件包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.docker。您需要其他要求才能使用此模块，有关详细信息，请参见 要求。

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

概要

• 管理 Docker 容器的生命周期。

• 支持检查模式。使用 --check 和 --diff 运行以查看配置差异和要采取的操作列表。

要求

执行此模块的主机需要以下要求。

• 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"
auto_remove 布尔值	启用在容器进程退出时在守护程序端自动删除容器。 如果 container_default_behavior=compatibility，则此选项的默认值为 false。 选项 false true
blkio_weight 整数	块 IO（相对权重），介于 10 和 1000 之间。
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。旧名称已添加为别名，仍然可以使用。
cap_drop 列表 / 元素=字符串	要从容器中删除的功能列表。
capabilities 列表 / 元素=字符串	要添加到容器的功能列表。 这相当于 docker run --cap-add 或 docker-compose 选项 cap_add。
cgroup_parent 字符串 在 community.docker 1.1.0 中添加	指定容器的父 cgroup。
cgroupns_mode 字符串 在 community.docker 3.0.0 中添加	指定容器的 cgroup 命名空间模式。 Docker CLI 将其简称为 cgroupns。 选项 主机 私有
清理 布尔值	与 detach=false 一起使用，可在成功执行后移除容器。 选项 false ← (默认) true
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 文件。
命令 任意	容器启动时要执行的命令。命令可以是字符串或列表。 2.4 版本之前，字符串按逗号分割。 请参阅 command_handling 了解字符串和列表处理方式的差异。
命令处理 字符串 在 community.docker 1.9.0 中添加	对于 command （作为列表提供）和 entrypoint 的默认行为是将它们转换为字符串，而不考虑 shell 引用规则。（为了比较幂等性，将考虑 shell 引用规则来分割生成的字符串。） 此外，将 command 设置为空字符串列表，并将 entrypoint 设置为空列表，将被视为未指定这些选项。这与其他容器配置相关选项的幂等性处理不同。 如果将其设置为 compatibility（在 community.docker 3.0.0 之前为默认值），则将保留当前行为。 如果将其设置为 correct，则这些选项将保留为列表，并且空值或空列表将被正确处理以进行幂等性检查。自 community.docker 3.0.0 以来，此为默认值。 选项 "compatibility" "correct" ← (默认)
比较 字典	允许指定如何将现有容器的属性与模块选项进行比较，以确定是否应重新创建/更新容器。 只能指定与 Docker 守护程序处理的容器状态相对应的选项，以及 networks。 必须是一个字典，为某个选项指定 strict、ignore 和 allow_more_present 键之一。 如果指定了 strict，则将测试值的相等性，并且更改始终会导致更新或重新启动。如果指定了 ignore，则忽略更改。 allow_more_present 仅允许用于列表、集合和字典。如果将其指定给列表或集合，则只有在模块选项包含容器选项中不存在的值时，才会更新或重新启动容器。如果为字典指定了此选项，则只有在模块选项包含容器选项中不存在的键，或者存在键的值不同时，才会更新或重新启动容器。 可以使用通配符选项 * 将默认值 strict 或 ignore 之一设置为所有未明确设置为其他值的比较。 请参阅示例了解详情。
容器默认行为 字符串	在此模块的早期版本中，各种模块选项过去具有默认值。这会导致使用这些选项的不同值的容器出现问题。 默认值现在为 no_defaults。要恢复旧的行为，请将其设置为 compatibility，这将确保在用户未明确指定值时使用默认值。 这会影响 auto_remove、detach、init、interactive、memory、paused、privileged、read_only 和 tty 选项。 选项 "compatibility" "no_defaults" ← (默认)
cpu_period 整数	限制 CPU CFS（完全公平调度程序）周期。 请参阅 cpus 了解更易于使用的替代方法。
cpu_quota 整数	限制 CPU CFS（完全公平调度程序）配额。 请参阅 cpus 了解更易于使用的替代方法。
cpu_shares 整数	CPU 份额（相对权重）。
cpus 浮点数	指定容器可以使用多少可用 CPU 资源。 值为 1.5 表示最多将使用一个半 CPU（核心）。
cpuset_cpus 字符串	允许执行的 CPU。 例如 1,3 或 1-3。
cpuset_mems 字符串	允许执行的内存节点 (MEM) 0-3 或 0,1。
调试 布尔值	调试模式 选项 false ← (默认) true
default_host_ip 字符串 在 community.docker 1.2.0 中添加	定义要使用的默认主机 IP。 必须为空字符串、IPv4 地址或 IPv6 地址。 对于 Docker 20.10.2 或更高版本，应将其设置为空字符串 ("")，以避免将端口绑定到没有显式 IP 地址的 IPv4。 默认情况下，模块将尝试从 bridge 网络的 com.docker.network.bridge.host_binding_ipv4 选项自动检测此值。如果无法自动检测到它，它将回退到 0.0.0.0。
分离 布尔值	启用分离模式，让容器在后台运行。 如果禁用，则任务将反映容器运行的状态（如果命令失败则失败）。 如果 container_default_behavior=compatibility，则此选项的默认值为 true。 选项 false true
device_cgroup_rules 列表 / 元素=字符串 在 community.docker 3.11.0 中添加	要应用于容器的 cgroup 规则列表。
device_read_bps 列表 / 元素=字典	设备路径和从设备读取速率（每秒字节）的列表。
路径 字符串 / 必需	容器中的设备路径。
速率 字符串 / 必需	设备读取限制，格式为 <number>[<unit>]。 Number 是一个正整数。Unit 可以是 B（字节）、K（Kibibyte，1024B）、M（Mebibyte）、G（Gibibyte）、T（Tebibyte）或 P（Pebibyte）。 省略单位默认为字节。
device_read_iops 列表 / 元素=字典	设备及其读取速率（每秒 I/O 次数）列表。
路径 字符串 / 必需	容器中的设备路径。
速率 整数 / 必需	设备读取限制。 必须是正整数。
device_requests 列表 / 元素=字典 在 community.docker 0.1.0 中添加	允许请求额外的资源，例如 GPU。
capabilities 列表 / 元素=列表	字符串列表的列表，用于请求功能。 顶级列表项通过 OR 组合，对于每个列表项，其包含的列表中的项通过 AND 组合。 驱动程序尝试满足其中一个子列表。 nvidia 驱动程序的可用功能可以在 https://github.com/NVIDIA/nvidia-container-runtime 中找到。
count 整数	要请求的设备数量。 设置为 -1 以请求所有可用设备。
device_ids 列表 / 元素=字符串	设备 ID 列表。
driver 字符串	为此设备使用的驱动程序。
options 字典	特定于驱动程序的选项。
device_write_bps 列表 / 元素=字典	设备及其写入速率（每秒字节数）列表。
路径 字符串 / 必需	容器中的设备路径。
速率 字符串 / 必需	设备读取限制，格式为 <number>[<unit>]。 Number 是一个正整数。Unit 可以是 B（字节）、K（Kibibyte，1024B）、M（Mebibyte）、G（Gibibyte）、T（Tebibyte）或 P（Pebibyte）。 省略单位默认为字节。
device_write_iops 列表 / 元素=字典	设备及其写入速率（每秒 I/O 次数）列表。
路径 字符串 / 必需	容器中的设备路径。
速率 整数 / 必需	设备读取限制。 必须是正整数。
devices 列表 / 元素=字符串	要添加到容器的主机设备绑定列表。 每个绑定都是以 <path_on_host>:<path_in_container>:<cgroup_permissions> 格式表达的映射。
dns_opts 列表 / 元素=字符串	DNS 选项列表。
dns_search_domains 列表 / 元素=字符串	自定义 DNS 搜索域列表。
dns_servers 列表 / 元素=字符串	自定义 DNS 服务器列表。
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"
domainname 字符串	容器域名。
entrypoint 列表 / 元素=字符串	覆盖镜像默认 ENTRYPOINT 的命令。 请参阅 command_handling 了解字符串和列表处理方式的差异。
env 字典	键值对字典。 YAML 解析器可能将某些值解析为数字、布尔值或其他类型，为了避免数据丢失，必须使用引号引起来（例如 "true"）。 请注意，如果您使用 Jinja2 模板传递值，例如 "{{ value }}"，则需要添加 | string 以防止 Ansible 将诸如 "true" 之类的字符串转换回布尔值。正确的方法是使用 "{{ value | string }}"。
env_file 路径	目标上存在的包含环境变量 FOO=BAR 的文件的路径。 如果变量也存在于 env 中，则 env 值将覆盖。
etc_hosts 字典	主机到 IP 映射的字典，其中每个主机名都是字典中的一个键。每个主机名都将添加到容器的 /etc/hosts 文件中。 除了 IP 地址外，还可以使用特殊值 host-gateway，它解析为主机的网关 IP，并允许容器连接到主机上运行的服务。
exposed_ports 别名：exposed, expose 列表 / 元素=字符串	其他容器端口列表，告知 Docker 容器在运行时侦听指定的网络端口。 如果端口已使用 Dockerfile 中的 EXPOSE 公开，则无需再次公开。
force_kill 别名：forcekill 布尔值	停止正在运行的容器时使用 kill 命令。 选项 false ← (默认) true
groups 列表 / 元素=字符串	容器进程将以其运行的其他组名和/或 ID 列表。
healthcheck 字典	配置运行的检查，以确定此服务的容器是否“健康”。 有关运行状况检查的工作方式的详细信息，请参阅 HEALTHCHECK Dockerfile 指令 的文档。 healthcheck.interval、healthcheck.timeout、healthcheck.start_period 和 healthcheck.start_interval 指定为持续时间。它们接受类似于 5h34m56s、1m30s 等等格式的持续时间字符串。支持的单位是 us、ms、s、m 和 h。 另请参阅 state=healthy。
interval 字符串	运行检查之间的时间。 Docker 守护程序使用的默认值为 30s。
retries 整数	报告不健康所需的连续失败次数。 Docker 守护程序使用的默认值为 3。
start_interval 字符串 在 community.docker 3.10.0 中添加	启动期间运行状况检查之间的时间。此选项需要 Docker Engine 版本 25.0 或更高版本。 Docker 守护程序使用的默认值为 5s。
start_period 字符串	容器在启动运行状况重试倒计时之前进行初始化的启动时间段。 Docker 守护程序使用的默认值为 0s。
test 任意	要运行的检查运行状况的命令。 必须是字符串或列表。如果是列表，则第一项必须是 NONE、CMD 或 CMD-SHELL 之一。
test_cli_compatible 布尔值 在 community.docker 3.10.0 中添加	如果设置为 true，则在提供 healthcheck 的同时省略 healthcheck.test 并不会禁用运行状况检查，而只是将镜像的值覆盖为 healthcheck 中指定的值。这是 Docker CLI 使用的行为。 如果设置为false，则省略healthcheck.test将禁用容器的健康检查。这是模块的经典行为，目前也是默认行为。 选项 false ← (默认) true
超时时间 (timeout) 字符串	允许单个检查运行的最长时间。 Docker 守护程序使用的默认值为 30s。
健康等待超时时间 (healthy_wait_timeout) 浮点数 在 community.docker 3.11.0 中添加	如果state=healthy，在等待容器变为健康状态时，此选项控制模块等待容器状态变为健康状态的时间长度。 超时时间以秒为单位指定。默认值为300，即5分钟。 将其设置为0或负值表示无限期等待。请注意，根据容器的不同，这可能导致模块无法终止。 默认值： 300.0
主机名 (hostname) 字符串	容器的主机名。
镜像 (image) 字符串	用于创建容器的仓库路径和标签。如果找不到镜像或pull为true，则将从注册表中拉取镜像。如果没有包含标签，则将使用latest。 也可以是镜像ID。如果是这种情况，则假定镜像在本地可用。pull选项在此情况下将被忽略。
镜像比较 (image_comparison) 字符串 在 community.docker 3.0.0 中添加	确定要用于依赖于镜像参数的幂等性检查的镜像。 默认值desired-image将使用通过image参数提供给模块的镜像。 current-image将使用容器当前正在使用的镜像（如果容器存在）。如果容器尚不存在，则回退到提供的镜像。 这会影响env、env_file、exposed_ports、labels和volumes选项。 选项 "desired-image" ← (默认) "current-image"
镜像标签不匹配 (image_label_mismatch) 字符串 在community.docker 2.6.0中添加	如何处理从镜像继承但未显式设置的标签。 当ignore时，在镜像中存在但在labels中未指定的标签将被忽略。这有助于避免必须在labels中指定镜像标签，同时保持标签comparisons strict。 当fail时，如果镜像中存在从labels未设置的标签，则模块将失败。这可以防止从基础镜像引入意外的标签。 警告：除非在comparisons选项中指定了labels: strict或*: strict，否则此选项将被忽略。 选项 "ignore" ← (默认) "fail"
镜像名称不匹配 (image_name_mismatch) 字符串 在community.docker 3.2.0中添加	如果镜像匹配，但容器配置中的镜像名称与提供给模块的镜像名称不匹配，则确定模块的行为。 如果在comparisons中设置了image: ignore，则此选项将被忽略。 如果设置为recreate（默认），则容器将被重新创建。 如果设置为ignore，则由于此原因，容器将不会被重新创建。它可能仍会因其他原因而被重新创建。长期以来，这是模块的默认行为，但这可能不是用户期望的行为。 在community.docker 4.0.0中，默认值从ignore更改为recreate。 选项 "recreate" ← (默认) "ignore"
初始化进程 (init) 布尔值	在容器内运行一个init进程，用于转发信号和回收进程。 如果 container_default_behavior=compatibility，则此选项的默认值为 false。 选项 false true
交互模式 (interactive) 布尔值	即使未附加，启动容器后也保持stdin打开。 如果 container_default_behavior=compatibility，则此选项的默认值为 false。 选项 false true
IPC模式 (ipc_mode) 字符串	设置容器的IPC模式。 可以是container:<name|id>（重用另一个容器的IPC命名空间）或host（在容器内使用主机的IPC命名空间）。
保留卷 (keep_volumes) 布尔值	保留与已删除容器关联的匿名卷。 选项 false true ← (默认)
内核内存 (kernel_memory) 字符串	内核内存限制，格式为<number>[<unit>]。数字是正整数。单位可以是B（字节）、K（KiB，1024B）、M（MiB）、G（GiB）、T（TiB）或P（PiB）。最小值为4M。 省略单位默认为字节。
终止信号 (kill_signal) 字符串	覆盖用于终止正在运行的容器的默认信号。
标签 (labels) 字典	键值对字典。
链接 (links) 列表 / 元素=字符串	以container_name:alias格式链接容器的名称别名列表。 设置此项将强制容器重启。
日志驱动 (log_driver) 字符串	指定日志驱动程序。Docker默认使用json-file。 有关可能的选项，请参阅Docker日志配置文档。
日志选项 (log_options) 别名：log_opt 字典	为所选log_driver指定的选项字典。 详情请参阅https://docs.docker.net.cn/engine/admin/logging/overview/。 即使使用默认的json-file驱动程序，也需要指定log_driver才能使log_options生效。
MAC地址 (mac_address) 字符串	容器MAC地址（例如，92:d0:c6:0a:29:33）。 请注意，自Docker API版本1.44起，全局容器范围的MAC地址已弃用且不再使用。 请改用networks[].mac_address。
内存 (memory) 字符串	内存限制，格式为<number>[<unit>]。数字是正整数。单位可以是B（字节）、K（KiB，1024B）、M（MiB）、G（GiB）、T（TiB）或P（PiB）。 省略单位默认为字节。 如果container_default_behavior=compatibility，此选项的默认值为"0"。
内存预留 (memory_reservation) 字符串	内存软限制，格式为 <number>[<unit>]。Number 为正整数。Unit 可以是 B（字节）、K（Kibibyte，1024B）、M（Mebibyte）、G（Gibibyte）、T（Tebibyte）或 P（Pebibyte）。 省略单位默认为字节。
memory_swap 字符串	总内存限制（内存 + 交换空间），格式为 <number>[<unit>]，或特殊值 unlimited 或 -1 表示交换空间使用无限制。Number 为正整数。Unit 可以是 B（字节）、K（Kibibyte，1024B）、M（Mebibyte）、G（Gibibyte）、T（Tebibyte）或 P（Pebibyte）。 省略单位默认为字节。
memory_swappiness 整数	调整容器的内存交换行为。接受 0 到 100 之间的整数。 如果未设置，如果容器存在则值将保持不变，如果容器被（重新）创建，则将从主机继承。
mounts 列表 / 元素=字典	要添加到容器的挂载点的规范。比 volumes 更强大的替代方案。
consistency 字符串	挂载点的一致性要求。 选项 "cached" "consistent" "default" "delegated"
标签 (labels) 字典	卷的用户定义名称和标签。仅对 volume 类型有效。
no_copy 布尔值	如果卷应该使用目标数据填充，则为 False。仅对 volume 类型有效。 默认值为 false。 选项 false true
propagation 字符串	传播模式。仅对 bind 类型有效。 选项 私有 "rprivate" "shared" "rshared" "slave" "rslave"
read_only 布尔值	挂载点是否应为只读。 选项 false true
source 字符串	挂载源。 例如，这可以是卷名称或主机路径。 当 mounts[].type=volume 未提供时，将创建一个匿名卷。
target 字符串 / 必需	容器内的路径。
tmpfs_mode 字符串	tmpfs 挂载点的权限模式。
tmpfs_size 字符串	tmpfs 挂载点的大小（以字节为单位），格式为 <number>[<unit>]。 Number 是一个正整数。Unit 可以是 B（字节）、K（Kibibyte，1024B）、M（Mebibyte）、G（Gibibyte）、T（Tebibyte）或 P（Pebibyte）。 省略单位默认为字节。
type 字符串	挂载类型。 请注意，npipe 仅受 Docker for Windows 支持。 选项 "bind" "npipe" "tmpfs" "volume" ← (默认)
volume_driver 字符串	指定卷驱动程序。仅对 volume 类型有效。 详情请参见 此处。
volume_options 字典	选择的 volume_driver 的特定选项字典。详情请参见 此处。
name 字符串 / 必需	为新容器分配名称或匹配现有容器。 在识别现有容器时，名称可以是名称或长或短的容器 ID。
network_mode 字符串	将容器连接到网络。选项包括 bridge、host、none、container:<name|id>、<network_name> 或 default。 从 community.docker 2.0.0 开始，如果 networks_cli_compatible=true 并且 networks 包含至少一个网络，则 network_mode 的默认值为 networks 列表中第一个网络的名称。可以通过显式指定 network_mode 的值来防止这种情况，例如默认值 default，如果未指定 network_mode，Docker 将使用此值。
networks 列表 / 元素=字典	容器所属的网络列表。 有关数据结构和用法的示例，请参见下面的示例。 要将容器从一个或多个网络中移除，请在 comparisons 选项中使用 networks: strict。 如果 networks_cli_compatible=false，并且通过 networks 选项向模块提供网络，则模块的行为与 docker run --network 不同：docker run --network other 将创建一个附加了网络 other 但未附加默认网络的容器。使用 networks 设置为 {name: other} 的此模块将创建一个同时附加了 default 和 other 的容器。如果在 comparisons 中设置了 networks: strict 或 *: strict，则随后将删除 default 网络。
aliases 列表 / 元素=字符串	此容器在此网络中的别名列表。这些名称可用于在网络中访问此容器。
ipv4_address 字符串	此容器在此网络中的 IPv4 地址。
ipv6_address 字符串	此容器在此网络中的 IPv6 地址。
链接 (links) 列表 / 元素=字符串	要链接到的容器列表。
MAC地址 (mac_address) 字符串 在 community.docker 3.6.0 中添加。	端点 MAC 地址（例如，92:d0:c6:0a:29:33）。 这仅适用于 Docker API 版本 1.44 及更高版本。 请注意，当创建后将容器附加到网络时，至少在某些情况下，Docker Daemon 目前会忽略此设置。在创建时传递此设置似乎效果更好。
name 字符串 / 必需	网络名称。
networks_cli_compatible 布尔值	如果 networks_cli_compatible=true（默认），此模块的行为将与 docker run --network 相同，并且如果指定了 networks，则**不会**添加默认网络。如果未指定 networks，则将附加默认网络。 当 networks_cli_compatible=false 且通过 networks 选项向模块提供网络时，模块的行为与 docker run --network 不同：docker run --network other 将创建一个附加了网络 other 但未附加默认网络的容器。使用 networks 设置为 {name: other} 的此模块将创建一个同时附加了 default 和 other 的容器。如果在 comparisons 中设置了 networks: strict 或 *: strict，则随后将删除 default 网络。 选项 false true ← (默认)
oom_killer 布尔值	是否禁用容器的 OOM Killer。 选项 false true
oom_score_adj 整数	一个整数，包含赋予容器的分数，以调整 OOM killer 优先级。
output_logs 布尔值	如果设置为 true，则将打印容器命令的输出。 仅当 log_driver 设置为 json-file、journald 或 local 时有效。 选项 false ← (默认) true
paused 布尔值	与 started 状态一起使用，暂停容器内的正在运行的进程。 如果 container_default_behavior=compatibility，则此选项的默认值为 false。 选项 false true
pid_mode 字符串	设置容器的 PID 命名空间模式。
pids_limit 整数	设置容器的PID限制。它接受一个整数值。 设置为-1表示无限制的PID。
平台 字符串 在 community.docker 3.0.0 中添加	容器的平台，格式为os[/arch[/variant]]。 请注意，从community.docker 3.5.0版本开始，该模块同时使用镜像的元数据和Docker守护进程的信息来规范化平台字符串，这与Docker本身的操作方式类似。如果您注意到幂等性问题，请在community.docker GitHub仓库中创建一个issue。对于较旧的community.docker版本，您可以使用comparisons选项，并设置platform: ignore来防止由于此问题而意外地重新创建容器。
特权 布尔值	赋予容器扩展权限。 如果 container_default_behavior=compatibility，则此选项的默认值为 false。 选项 false true
publish_all_ports 布尔值 community.docker 1.8.0版本中添加	将所有端口发布到主机。 当设置为true时，来自published_ports的任何指定的端口绑定将保持不变。 选项 false true
published_ports 别名：ports 列表 / 元素=字符串	要从容器发布到主机的端口列表。 使用Docker CLI语法：8000，9000:8000，或0.0.0.0:9000:8000，其中8000是容器端口，9000是主机端口，0.0.0.0是主机接口。 可以使用端口范围作为源端口和目标端口。如果指定了长度不同的两个范围，则将使用较短的范围。从community.general 0.2.0版本开始，如果源端口范围的长度为1，则端口不会分配给目标范围的第一个端口，而是分配给该范围内的空闲端口。这与docker命令行工具的行为相同。 绑定地址必须是IPv4或IPv6地址。不允许使用主机名。这与docker命令行工具不同。使用community.general.dig查找来解析主机名。 如果提供了networks参数，将检查每个网络以查看是否存在具有可选参数com.docker.network.bridge.host_binding_ipv4的桥接网络。如果找到这样的网络，则未指定主机IP地址的已发布端口将绑定到com.docker.network.bridge.host_binding_ipv4指向的主机IP。请注意，在networks列表中遇到的第一个具有com.docker.network.bridge.host_binding_ipv4值的桥接网络将被使用。 在早期版本的此模块中允许使用值all。community.docker 3.0.0版本中已删除对它的支持。请改用publish_all_ports选项。
拉取镜像 任意	如果设置为never，则永远不会尝试拉取镜像。如果Docker守护进程上没有该镜像，则会失败。 如果设置为missing或false，则只有在Docker守护进程上没有该镜像时才拉取镜像。这是默认行为。 如果设置为always或true，则始终尝试拉取镜像的最新版本。 注意：只有按名称指定时才会拉取镜像。如果镜像指定为镜像ID（哈希值），则无法拉取，并且会忽略此选项。 注意：值never，missing和always仅从community.docker 3.8.0版本开始可用。早期版本仅支持true和false。 选项 "never" "missing" ← (默认) "always" true false
pull_check_mode_behavior 字符串 community.docker 3.8.0版本中添加	允许在检查模式下调整pull=always或pull=true的行为。 由于Docker守护进程没有公开任何功能来测试拉取是否会导致镜像更改，因此默认情况下，模块的行为类似于pull=always，只有在镜像不存在时才会导致更改。 如果设置为image_not_present（默认值），则仅在镜像不存在时在检查模式下报告更改。 如果设置为always，则始终在检查模式下报告更改。 选项 "image_not_present" ← (默认) "always"
read_only 布尔值	以只读方式挂载容器的根文件系统。 如果 container_default_behavior=compatibility，则此选项的默认值为 false。 选项 false true
recreate 布尔值	与present和started状态一起使用，强制重新创建现有容器。 选项 false ← (默认) true
removal_wait_timeout 浮点数	删除现有容器时，Docker守护进程API调用在容器被安排删除后存在。删除通常非常快，但在高I/O负载期间，删除可能需要更长时间。默认情况下，模块将等待直到容器被删除后再尝试（重新）创建它，无论需要多长时间。 通过设置此选项，模块最多将等待这么多秒来删除容器。如果这么多秒后容器仍在删除阶段，则模块将失败。
重启 布尔值	与started状态一起使用，强制停止并重新启动匹配的容器。 选项 false ← (默认) true
restart_policy 字符串	容器重启策略。 在no选项周围加上引号。 选项 "no" "on-failure" "always" "unless-stopped"
restart_retries 整数	与重启策略一起使用，以控制最大重启尝试次数。
runtime 字符串	用于容器的运行时。
security_opts 列表 / 元素=字符串	安全选项列表，格式为"label:user:User"。
shm_size 字符串	/dev/shm的大小，格式为<number>[<unit>]。数字为正整数。单位可以是B（字节），K（KiB，1024B），M（MiB），G（GiB），T（TiB）或P（PiB）。 省略单位默认为字节。如果完全省略大小，Docker守护进程将使用64M。
状态 字符串	absent - 将停止并删除与指定名称匹配的容器。使用force_kill强制杀死容器，而不是停止它。使用keep_volumes保留与已删除容器关联的匿名卷。 present - 断言存在与名称和任何提供的配置参数匹配的容器。如果没有容器与名称匹配，则将创建一个容器。如果容器与名称匹配，但提供的配置不匹配，则将更新容器（如果可以）。如果无法更新，则将删除它并使用请求的配置重新创建它。 started - 断言容器首先present，然后如果容器未运行，则将其移至运行状态。使用restart强制停止并重新启动匹配的容器。 healthy - 断言容器present且started，并且实际上也是健康的。这意味着healthcheck中定义的条件（分别在镜像的HEALTHCHECK中（Docker关于HEALTHCHECK的参考））已满足。可以使用healthy_wait_timeout控制等待时间。此状态已在community.docker 3.11.0版本中添加。 stopped - 断言容器首先 present，然后如果容器正在运行，则将其置于停止状态。 要控制比较配置时将考虑哪些内容，请参阅 comparisons 选项。为避免考虑镜像版本，您也可以在 comparisons 选项中使用 image: ignore。 使用 recreate 选项始终强制重新创建匹配的容器，即使它正在运行。 如果需要停止容器以进行重新创建，或者因为 state 为 stopped，则应终止容器而不是停止它，请使用 force_kill 选项。使用 keep_volumes 保留与已删除容器关联的匿名卷。 使用 keep_volumes 保留与已删除容器关联的匿名卷。 选项 "absent" "present" "healthy" "stopped" "started" ← (默认)
stop_signal 字符串	覆盖用于停止容器的默认信号。
stop_timeout 整数	在发送 SIGKILL 之前等待容器停止的秒数。当此模块创建容器时，其 StopTimeout 配置将设置为该值。 当容器停止时，将用作停止容器的超时时间。如果容器具有自定义 StopTimeout 配置，则行为取决于 Docker 守护程序的版本。新版本的 Docker 守护程序将始终使用容器配置的 StopTimeout 值（如果已配置）。
storage_opts 字典 community.docker 1.3.0 版本中新增	此容器的存储驱动程序选项，作为键值映射。
sysctls 字典	键值对字典。
超时时间 (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 中已删除。
tmpfs 列表 / 元素=字符串	挂载 tmpfs 目录。
tty 布尔值	分配伪 TTY。 如果 container_default_behavior=compatibility，则此选项的默认值为 false。 选项 false true
ulimits 列表 / 元素=字符串	ulimit 选项列表。ulimit 指定为 nofile:262144:262144。
use_ssh_client 布尔值 community.docker 1.5.0 版本中新增	对于 SSH 传输，使用 ssh CLI 工具而不是 paramiko。 选项 false ← (默认) true
user 字符串	设置使用的用户名或 UID，以及可选的指定命令的组名或 GID。 可以采用以下形式：user、user:group、uid、uid:gid、user:gid 或 uid:group。
userns_mode 字符串	设置容器的用户命名空间模式。当前，唯一有效的值是 host 和空字符串 ("")。
uts 字符串	设置容器的 UTS 命名空间模式。
validate_certs 别名：tls_verify 布尔值	通过使用 TLS 连接到 API 并验证 Docker 主机服务器的真实性来保护连接。 如果任务中未指定该值，则将改用环境变量 DOCKER_TLS_VERIFY 的值。如果未设置环境变量，则将使用默认值。 选项 false ← (默认) true
volume_driver 字符串	容器卷驱动程序。
volumes 列表 / 元素=字符串	要在容器内挂载的卷列表。 使用 docker CLI 风格的语法：/host:/container[:mode] 挂载模式可以是各种模式的逗号分隔列表，例如 ro、rw、consistent、delegated、cached、rprivate、private、rshared、shared、rslave、slave 和 nocopy。请注意，Docker 守护程序可能不支持所有模式以及此类模式的组合。 SELinux 主机还可以额外使用 z 或 Z 来为卷使用共享或专用标签。 请注意，Ansible 2.7 及更早版本仅支持一种模式，该模式必须是 ro、rw、z 和 Z 之一。
volumes_from 列表 / 元素=字符串	要从中获取卷的容器名称或 ID 列表。
working_dir 字符串	工作目录的路径。

属性

属性	支持	描述
action_group	动作组： community.docker.docker、docker	在 module_defaults 中使用 group/docker 或 group/community.docker.docker 为此模块设置默认值。
check_mode	支持：部分 尝试拉取镜像时，模块假设在检查模式下镜像从不更改，除非 Docker 守护程序上不存在该镜像。 此行为可以使用 pull_check_mode_behavior 进行配置。	可以在 check_mode 下运行并返回已更改状态预测，而无需修改目标。
diff_mode	支持：完全	在差异模式下，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

备注

注意

• 对于大多数配置更改，都需要重新创建容器。这意味着必须销毁现有容器并创建一个新容器。这可能会导致意外的数据丢失和停机时间。您可以使用 comparisons 选项来防止这种情况。

• 如果模块需要重新创建容器，它将仅使用提供给模块的选项来创建新容器（image 除外）。因此，请始终指定与容器相关的所有选项。

• 当 restart 设置为 true 时，模块仅在未检测到配置更改时才重新启动容器。

• 可以通过为每个任务提供参数或定义环境变量来连接到 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 代码。

示例

- name: Create a data container
  community.docker.docker_container:
    name: mydata
    image: busybox
    volumes:
      - /data

- name: Re-create a redis container
  community.docker.docker_container:
    name: myredis
    image: redis
    command: redis-server --appendonly yes
    state: present
    recreate: true
    exposed_ports:
      - 6379
    volumes_from:
      - mydata

- name: Restart a container
  community.docker.docker_container:
    name: myapplication
    image: someuser/appimage
    state: started
    restart: true
    links:
     - "myredis:aliasedredis"
    devices:
     - "/dev/sda:/dev/xvda:rwm"
    ports:
     # Publish container port 9000 as host port 8080
     - "8080:9000"
     # Publish container UDP port 9001 as host port 8081 on interface 127.0.0.1
     - "127.0.0.1:8081:9001/udp"
     # Publish container port 9002 as a random host port
     - "9002"
     # Publish container port 9003 as a free host port in range 8000-8100
     # (the host port will be selected by the Docker daemon)
     - "8000-8100:9003"
     # Publish container ports 9010-9020 to host ports 7000-7010
     - "7000-7010:9010-9020"
    env:
        SECRET_KEY: "ssssh"
        # Values which might be parsed as numbers, booleans or other types by the YAML parser need to be quoted
        BOOLEAN_KEY: "yes"

- name: Container present
  community.docker.docker_container:
    name: mycontainer
    state: present
    image: ubuntu:14.04
    command: sleep infinity

- name: Stop a container
  community.docker.docker_container:
    name: mycontainer
    state: stopped

- name: Start 4 load-balanced containers
  community.docker.docker_container:
    name: "container{{ item }}"
    recreate: true
    image: someuser/anotherappimage
    command: sleep 1d
  with_sequence: count=4

- name: Remove container
  community.docker.docker_container:
    name: ohno
    state: absent

- name: Syslogging output
  community.docker.docker_container:
    name: myservice
    image: busybox
    log_driver: syslog
    log_options:
      syslog-address: tcp://my-syslog-server:514
      syslog-facility: daemon
      # NOTE: in Docker 1.13+ the "syslog-tag" option was renamed to "tag" for
      # older docker installs, use "syslog-tag" instead
      tag: myservice

- name: Create db container and connect to network
  community.docker.docker_container:
    name: db_test
    image: "postgres:latest"
    networks:
      - name: "{{ docker_network_name }}"

- name: Start container, connect to network and link
  community.docker.docker_container:
    name: sleeper
    image: ubuntu:14.04
    networks:
      - name: TestingNet
        ipv4_address: "172.16.1.100"
        aliases:
          - sleepyzz
        links:
          - db_test:db
      - name: TestingNet2

- name: Start a container with a command
  community.docker.docker_container:
    name: sleepy
    image: ubuntu:14.04
    command: ["sleep", "infinity"]

- name: Add container to networks
  community.docker.docker_container:
    name: sleepy
    networks:
      - name: TestingNet
        ipv4_address: 172.16.1.18
        links:
          - sleeper
      - name: TestingNet2
        ipv4_address: 172.16.10.20

- name: Update network with aliases
  community.docker.docker_container:
    name: sleepy
    networks:
      - name: TestingNet
        aliases:
          - sleepyz
          - zzzz

- name: Remove container from one network
  community.docker.docker_container:
    name: sleepy
    networks:
      - name: TestingNet2
    comparisons:
      networks: strict

- name: Remove container from all networks
  community.docker.docker_container:
    name: sleepy
    comparisons:
      networks: strict

- name: Start a container and use an env file
  community.docker.docker_container:
    name: agent
    image: jenkinsci/ssh-slave
    env_file: /var/tmp/jenkins/agent.env

- name: Create a container with limited capabilities
  community.docker.docker_container:
    name: sleepy
    image: ubuntu:16.04
    command: sleep infinity
    capabilities:
      - sys_time
    cap_drop:
      - all

- name: Finer container restart/update control
  community.docker.docker_container:
    name: test
    image: ubuntu:18.04
    env:
      arg1: "true"
      arg2: "whatever"
    volumes:
      - /tmp:/tmp
    comparisons:
      image: ignore   # do not restart containers with older versions of the image
      env: strict   # we want precisely this environment
      volumes: allow_more_present   # if there are more volumes, that's ok, as long as `/tmp:/tmp` is there

- name: Finer container restart/update control II
  community.docker.docker_container:
    name: test
    image: ubuntu:18.04
    env:
      arg1: "true"
      arg2: "whatever"
    comparisons:
      '*': ignore  # by default, ignore *all* options (including image)
      env: strict   # except for environment variables; there, we want to be strict

- name: Start container with healthstatus
  community.docker.docker_container:
    name: nginx-proxy
    image: nginx:1.13
    state: started
    healthcheck:
      # Check if nginx server is healthy by curl'ing the server.
      # If this fails or timeouts, the healthcheck fails.
      test: ["CMD", "curl", "--fail", "http://nginx.host.com"]
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 30s
      start_interval: 10s

- name: Remove healthcheck from container
  community.docker.docker_container:
    name: nginx-proxy
    image: nginx:1.13
    state: started
    healthcheck:
      # The "NONE" check needs to be specified
      test: ["NONE"]

- name: Create a tmpfs with a size and mode
  community.docker.docker_container:
    name: tmpfs test
    image: ubuntu:22.04
    state: started
    mounts:
      - type: tmpfs
        target: /cache
        tmpfs_mode: "1700" # only readable to the owner
        tmpfs_size: "16G"

- name: Start container with block device read limit
  community.docker.docker_container:
    name: test
    image: ubuntu:18.04
    state: started
    device_read_bps:
      # Limit read rate for /dev/sda to 20 mebibytes per second
      - path: /dev/sda
        rate: 20M
    device_read_iops:
      # Limit read rate for /dev/sdb to 300 IO per second
      - path: /dev/sdb
        rate: 300

- name: Start container with GPUs
  community.docker.docker_container:
    name: test
    image: ubuntu:18.04
    state: started
    device_requests:
      - # Add some specific devices to this container
        device_ids:
          - '0'
          - 'GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a'
      - # Add nVidia GPUs to this container
        driver: nvidia
        count: -1  # this means we want all
        capabilities:
          # We have one OR condition: 'gpu' AND 'utility'
          - - gpu
            - utility
          # See https://github.com/NVIDIA/nvidia-container-runtime#supported-driver-capabilities
          # for a list of capabilities supported by the nvidia driver

- name: Start container with storage options
  community.docker.docker_container:
    name: test
    image: ubuntu:18.04
    state: started
    storage_opts:
      # Limit root filesystem to 12 MB - note that this requires special storage backends
      # (https://fabianlee.org/2020/01/15/docker-use-overlay2-with-an-xfs-backing-filesystem-to-limit-rootfs-size/)
      size: 12m

返回值

常见的返回值已在此处 记录，以下是此模块特有的字段

键	描述
容器 字典	表示容器当前状态的事实。与 docker 检查输出匹配。 如果 state=absent，则为空。 如果 detach=false，则将包含 Output 属性，其中包含容器运行的任何输出。 返回：成功；或者当 state=started 和 detach=false 时，以及等待容器结果未失败时。 示例： "{ \"AppArmorProfile\": \"\", \"Args\": [], \"Config\": { \"AttachStderr\": false, \"AttachStdin\": false, \"AttachStdout\": false, \"Cmd\": [ \"/usr/bin/supervisord\" ], \"Domainname\": \"\", \"Entrypoint\": null, \"Env\": [ \"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\" ], \"ExposedPorts\": { \"443/tcp\": {}, \"80/tcp\": {} }, \"Hostname\": \"8e47bf643eb9\", \"Image\": \"lnmp_nginx:v1\", \"Labels\": {}, \"OnBuild\": null, \"OpenStdin\": false, \"StdinOnce\": false, \"Tty\": false, \"User\": \"\", \"Volumes\": { \"/tmp/lnmp/nginx-sites/logs/\": {} }, ... }"
状态 整数	如果容器在没有分离的情况下启动，则包含容器中进程的退出代码。 在 community.docker 1.1.0 之前，只有在非零时才会返回此值。 返回：当 state=started 和 detach=false 时，以及等待容器结果未失败时。 示例： 0

作者

• Cove Schneider (@cove)

• Joshua Conner (@joshuaconner)

• Pavel Antonov (@softzilla)

• Thomas Steinbach (@ThomasSteinbach)

• Philippe Jandot (@zfil)

• Daan Oosterveld (@dusdanig)

• Chris Houseknecht (@chouseknecht)

• Kassian Sun (@kassiansun)

• Felix Fontein (@felixfontein)

集合链接

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