community.docker.docker_containers 清单 – 用于 Docker 容器的 Ansible 动态清单插件

注意

此清单插件是 community.docker 集合（版本 4.1.0）的一部分。

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

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

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

community.docker 1.1.0 中的新增功能

概要

• 从 Docker API 读取清单。

• 使用以 docker.(yml|yaml) 结尾的 YAML 配置文件。

要求

本地控制器节点上需要以下要求才能执行此清单。

• requests

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

• paramiko（当使用 SSH 时，且 use_ssh_client=false)

• pyOpenSSL（当使用 TLS 时）

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

参数

参数	注释
add_legacy_groups 布尔值	添加与 docker 清单脚本相同的组。这些是以下内容 <容器 ID>：包含此 ID 的容器。 <容器名称>：包含具有此名称的容器。 <容器短 ID>：包含具有此短 ID 的容器（ID 的前 13 个字母）。 image_<镜像名称>：包含具有镜像 <镜像名称> 的容器。 stack_<堆栈名称>：包含属于堆栈 <堆栈名称> 的容器。 service_<服务名称>：包含属于服务 <服务名称> 的容器 <docker_host>：包含属于 Docker 守护进程 docker_host 的容器。如果针对多个 Docker 守护进程运行此插件，则非常有用。 running：包含所有正在运行的容器。 stopped：包含所有未运行的容器。 如果未将其设置为 true，则应使用键控组将容器添加到组中。有关如何执行此操作，请参见示例。 选择 false ← (默认) true
api_version 别名: docker_api_version 字符串	Docker 主机上运行的 Docker API 版本。 默认为此集合和 docker 守护进程支持的最新 API 版本。 如果在任务中未指定该值，则将使用环境变量 DOCKER_API_VERSION 的值。如果未设置环境变量，则将使用默认值。 默认值: "auto"
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 文件。
compose 字典	从 Jinja2 表达式创建变量。 默认值: {}
configure_docker_daemon 布尔值 在 community.docker 1.8.0 中添加	是否将所有 Docker 守护进程配置从清单插件传递到连接插件。 仅当 connection_type=docker-api 时使用。 选择 false true ← (默认)
connection_type 字符串	要使用容器的连接类型。 连接容器的一种方法是使用 SSH (ssh)。为此，使用 default_ip 和 private_ssh_port 选项。 这要求 SSH 守护进程在容器内部运行。 或者，docker-cli 选择 community.docker.docker 连接插件，docker-api (默认) 选择 community.docker.docker_api 连接插件。 当使用 docker-api 时，所有 Docker 守护进程配置值都从清单插件传递到连接插件。这可以通过 configure_docker_daemon 来控制。 请注意，community.docker.docker_api 不适用于 TCP TLS 套接字！有关更多信息，请参阅 https://github.com/ansible-collections/community.docker/issues/605。 选择 "ssh" "docker-cli" "docker-api" ← (默认)
debug 布尔值	调试模式 选择 false ← (默认) true
default_ip 字符串	当容器的 SSH 端口映射到接口 “0.0.0.0” 时，要分配给 ansible_host 的 IP 地址。 仅当 connection_type 为 ssh 时使用。 默认值: "127.0.0.1"
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"
filters 列表 / 元素=字典 在 community.docker 3.5.0 中添加	一个包含/排除过滤器的列表，允许为此清单选择/取消选择主机。 过滤器按顺序处理，直到找到第一个匹配的过滤器 filters[].exclude 或 filters[].include。 如果 filters[].exclude 匹配，则排除主机，如果 filters[].include 匹配，则包含主机。 如果没有过滤器匹配，则包含主机。
exclude 字符串	一个 Jinja2 条件。 如果它匹配主机，则该主机被排除。 只能指定 filters[].exclude 和 filters[].include 中的一个。
include 字符串	一个 Jinja2 条件。 如果它匹配主机，则该主机被包含。 只能指定 filters[].exclude 和 filters[].include 中的一个。
groups 字典	根据 Jinja2 条件将主机添加到组。 默认值: {}
keyed_groups 列表 / 元素=字典	根据变量的值将主机添加到组。 默认值: []
default_value 字符串 在 ansible-core 2.12 中添加	当主机变量的值为空字符串时的默认值。 此选项与 keyed_groups[].trailing_separator 互斥。
key 字符串	用于生成组的输入字典中的键。
parent_group 字符串	键控组的父组。
prefix 字符串	键控组名称将以此前缀开头。 默认值: ""
separator 字符串	用于构建键控组名称的分隔符。 默认值: "_"
trailing_separator 布尔值 在 ansible-core 2.12 中添加	将此选项设置为 false 可在值为空字符串时省略主机变量后的 keyed_groups[].separator。 此选项与 keyed_groups[].default_value 互斥。 选择 false true ← (默认)
leading_separator 布尔值 在 ansible-core 2.11 中添加	与 keyed_groups 结合使用。 默认情况下，没有提供前缀或分隔符的键控组的名称将以下划线开头。 这是因为默认前缀为 ""，默认分隔符为 "_"。 如果未给出前缀，请将此选项设置为 false 以省略前导下划线（或其他分隔符）。 如果组名派生自映射，则分隔符仍用于连接各个项。 要完全不在组名中使用分隔符，请将键控组的分隔符设置为空字符串。 选择 false true ← (默认)
plugin string / 必需	此插件的名称，应始终设置为 community.docker.docker_containers，以便此插件识别它自身。 选择 "community.docker.docker_containers"
private_ssh_port integer	容器用于 SSH 的端口。 仅当 connection_type 为 ssh 时使用。 默认值: 22
strict 布尔值	如果设置为 yes，则将无效条目视为致命错误，否则跳过并继续。 由于可以在表达式中使用 facts，它们可能并非总是可用，因此默认情况下我们会忽略这些错误。 选择 false ← (默认) true
timeout integer	等待 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_extra_vars 布尔值 在 ansible-core 2.11 中添加	将额外变量合并到可用于组合的变量中（优先级最高）。 选择 false ← (默认) true 配置 INI 条目 [inventory_plugins] use_extra_vars = false 环境变量：ANSIBLE_INVENTORY_USE_EXTRA_VARS
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
verbose_output 布尔值	切换以（不）包含所有可用的检查元数据。 请注意，所有顶级键都将转换为 docker_xxx 格式。例如，HostConfig 将转换为 docker_hostconfig。 如果此值为 false，则这些值只能在 compose、groups 和 keyed_groups 期间使用。 docker 清单脚本始终会添加这些变量，为了兼容性，请将其设置为 true。 选择 false ← (默认) true

注释

注意

• 配置文件必须是 YAML 文件，其文件名以 docker.yml 或 docker.yaml 结尾。不接受其他文件名。

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

示例

# Minimal example using local Docker daemon
plugin: community.docker.docker_containers
docker_host: unix:///var/run/docker.sock

# Minimal example using remote Docker daemon
plugin: community.docker.docker_containers
docker_host: tcp://my-docker-host:2375

# Example using remote Docker daemon with unverified TLS
plugin: community.docker.docker_containers
docker_host: tcp://my-docker-host:2376
tls: true

# Example using remote Docker daemon with verified TLS and client certificate verification
plugin: community.docker.docker_containers
docker_host: tcp://my-docker-host:2376
validate_certs: true
ca_path: /somewhere/ca.pem
client_key: /somewhere/key.pem
client_cert: /somewhere/cert.pem

# Example using constructed features to create groups
plugin: community.docker.docker_containers
docker_host: tcp://my-docker-host:2375
strict: false
keyed_groups:
  # Add containers with primary network foo to a network_foo group
  - prefix: network
    key: 'docker_hostconfig.NetworkMode'
  # Add Linux hosts to an os_linux group
  - prefix: os
    key: docker_platform

# Example using SSH connection with an explicit fallback for when port 22 has not been
# exported: use container name as ansible_ssh_host and 22 as ansible_ssh_port
plugin: community.docker.docker_containers
connection_type: ssh
compose:
  ansible_ssh_host: ansible_ssh_host | default(docker_name[1:], true)
  ansible_ssh_port: ansible_ssh_port | default(22, true)

# Only consider containers which have a label 'foo', or whose name starts with 'a'
plugin: community.docker.docker_containers
filters:
  # Accept all containers which have a label called 'foo'
  - include: >-
      "foo" in docker_config.Labels
  # Next accept all containers whose inventory_hostname starts with 'a'
  - include: >-
      inventory_hostname.startswith("a")
  # Exclude all containers that didn't match any of the above filters
  - exclude: true

作者

• Felix Fontein (@felixfontein)

提示

每个条目类型的配置条目都具有从低到高的优先级顺序。例如，列表中较低的变量将覆盖较高的变量。

集合链接

• 问题跟踪器
• 存储库 (Sources)
• 寻求帮助 (Docker)
• 寻求帮助 (Docker Compose)
• 寻求帮助 (Docker Swarm)
• 提交错误报告
• 请求功能
• 交流