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。 选项 "host" "private"
cleanup 布尔值	与 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文件。
command 任意	容器启动时执行的命令。命令可以是字符串或列表。 2.4 版本之前，字符串按逗号分割。 有关字符串和列表的处理方式差异，请参阅command_handling。
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" ← (默认)
comparisons 字典	允许指定如何将现有容器的属性与模块选项进行比较，以确定是否应重新创建/更新容器。 只能指定与 Docker 守护程序处理的容器状态相对应的选项，以及networks。 必须是一个字典，为一个选项指定strict、ignore和allow_more_present键之一。 如果指定了strict，则将测试值的相等性，并且更改始终会导致更新或重启。如果指定了ignore，则会忽略更改。 allow_more_present仅允许用于列表、集合和字典。如果将其指定为列表或集合，则只有当模块选项包含容器选项中不存在的值时，才会更新或重新启动容器。如果为字典指定了该选项，则只有当模块选项包含容器选项中不存在的键，或者现有键的值不同时，才会更新或重新启动容器。 可以使用通配符选项*将默认值strict或ignore之一设置为所有未显式设置为其他值的比较。 有关详细信息，请参阅示例。
container_default_behavior 字符串	在此模块的早期版本中，各种模块选项曾经具有默认值。这会导致使用这些选项的不同值的容器出现问题。 现在的默认值为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。
debug 布尔值	调试模式 选项 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。
detach 布尔值	启用分离模式以使容器在后台运行。 如果禁用，则任务将反映容器运行的状态（如果命令失败则失败）。 如果container_default_behavior=compatibility，则此选项的默认值为true。 选项 false true
device_cgroup_rules 列表 / 元素=字符串 在 community.docker 3.11.0 中添加	要应用于容器的 cgroup 规则列表。
device_read_bps 列表 / 元素=字典	设备路径和从设备读取速率（每秒字节数）的列表。
路径 字符串 / 必需	容器中的设备路径。
rate 字符串 / 必需	设备读取限制，格式为<number>[<unit>]。 数字是正整数。单位可以是B（字节）、K（Kibibyte，1024B）、M（Mebibyte）、G（Gibibyte）、T（Tebibyte）或P（Pebibyte）。 省略单位默认为字节。
device_read_iops 列表 / 元素=字典	设备和从设备读取速率（每秒 I/O 次数）的列表。
路径 字符串 / 必需	容器中的设备路径。
rate 整数 / 必需	设备读取限制。 必须是正整数。
device_requests 列表 / 元素=字典 在 community.docker 0.1.0 中添加	允许请求其他资源，例如 GPU。
capabilities 列表 / 元素=列表	字符串列表的列表，用于请求功能。 顶级列表条目通过 OR 组合，对于每个列表条目，它包含的列表中的条目通过 AND 组合。 驱动程序尝试满足其中一个子列表。 可在https://github.com/NVIDIA/nvidia-container-runtime找到nvidia驱动程序的可用功能。
count 整数	要请求的设备数量。 设置为-1以请求所有可用设备。
device_ids 列表 / 元素=字符串	设备 ID 列表。
driver 字符串	要为此设备使用的驱动程序。
options 字典	特定于驱动程序的选项。
device_write_bps 列表 / 元素=字典	设备和写入速率（每秒字节数）到设备的列表。
路径 字符串 / 必需	容器中的设备路径。
rate 字符串 / 必需	设备读取限制，格式为<number>[<unit>]。 数字是正整数。单位可以是B（字节）、K（Kibibyte，1024B）、M（Mebibyte）、G（Gibibyte）、T（Tebibyte）或P（Pebibyte）。 省略单位默认为字节。
device_write_iops 列表 / 元素=字典	设备列表及其写入速率（每秒 I/O 次数）。
路径 字符串 / 必需	容器中的设备路径。
rate 整数 / 必需	设备读取限制。 必须是正整数。
设备 列表 / 元素=字符串	要添加到容器的主机设备绑定列表。 每个绑定都是一个以 <主机路径>:<容器路径>:<cgroup权限> 格式表达的映射。
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_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.dockerd.com.cn/engine/admin/logging/overview/。 即使使用默认的 json-file 驱动程序，也需要指定 log_driver，才能使 log_options 生效。
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>]。数字为正整数。单位可以是 B（字节）、K（KiB，1024B）、M（MiB）、G（GiB）、T（TiB）或 P（PiB）。 省略单位默认为字节。
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 类型有效。 选项 "private" "rprivate" "shared" "rshared" "slave" "rslave"
read_only 布尔值	挂载点是否应为只读。 选项 false true
source 字符串	挂载源。 例如，这可以是卷名称或主机路径。 当 mounts[].type=volume 未提供时，将创建一个匿名卷。
target 字符串 / 必需	容器内的路径。
tmpfs_mode 字符串	tmpfs 挂载点的权限模式。
tmpfs_size 字符串	tmpfs 挂载点的大小，以字节为单位，格式为 <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 ... 的行为不同。在这种情况下，需要在 comparisons 中显式使用 networks: strict 来强制移除默认网络（以及 networks 中未显式提及的所有其他网络）。
aliases 列表 / 元素=字符串	此网络中此容器的别名列表。这些名称可用于网络以访问此容器。
ipv4_address 字符串	此网络中容器的 IPv4 地址。
ipv6_address 字符串	此网络中容器的 IPv6 地址。
links 列表 / 元素=字符串	要链接到的容器列表。
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。
platform 字符串 在 community.docker 3.0.0 中添加	容器的平台，格式为os[/arch[/variant]]。 请注意，从community.docker 3.5.0版本开始，该模块使用镜像的元数据和Docker守护进程的信息来规范化平台字符串，这与Docker本身的做法类似。如果您注意到幂等性问题，请在community.docker GitHub仓库中创建一个问题。对于较旧的community.docker版本，您可以使用带有platform: ignore的comparisons选项来防止由于此问题意外重新创建容器。
privileged 布尔值	赋予容器扩展权限。 如果 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选项。
pull 任意	如果设置为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负载下，删除可能需要更长时间。默认情况下，模块将等待容器被删除后再尝试（重新）创建它，无论需要多长时间。 通过设置此选项，模块最多将等待这么多秒来删除容器。如果这么多秒后容器仍处于删除阶段，则模块将失败。
restart 布尔值	与started状态一起使用，强制停止并重新启动匹配的容器。 选项 false ← (默认) true
restart_policy 字符串	容器重启策略。 在no选项周围添加引号。 选项 "no" "on-failure" "always" "unless-stopped"
restart_retries 整数	与restart policy一起使用，控制最大重启尝试次数。
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。
state 字符串	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.dockerd.com.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)
• 提交错误报告
• 请求功能
• 沟通