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清单脚本相同的组。这些组如下： <container id>：包含此ID的容器。 <container name>：包含此名称的容器。 <container short id>：包含具有此短ID（ID的前13个字母）的容器。 image_<image name>：包含具有镜像<image name>的容器。 stack_<stack name>：包含属于堆栈<stack name>的容器。 service_<service name>：包含属于服务<service name>的容器。 <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 字符串 / 必需	此插件的名称，对于此插件将其识别为其自身，应始终设置为community.docker.docker_containers。 选项 "community.docker.docker_containers"
private_ssh_port 整数	容器用于SSH的端口。 仅当connection_type为ssh时使用。 默认值： 22
strict 布尔值	如果yes使无效条目成为致命错误，否则跳过并继续。 由于可以在表达式中使用事实，因此它们可能并不总是可用，因此我们默认忽略这些错误。 选项 false ← (默认值) true
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_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 命令行工具而不是 paramiko。 选项 false ← (默认值) true
validate_certs 别名：tls_verify 布尔值	使用 TLS 加密与 API 的连接，并验证 Docker 主机服务器的身份。 如果任务中未指定此值，则将使用环境变量 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)

提示

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

集合链接

• 问题追踪器
• 代码仓库
• 寻求帮助 (Docker)
• 寻求帮助 (Docker Compose)
• 寻求帮助 (Docker Swarm)
• 提交错误报告
• 请求功能
• 沟通