community.docker.docker_api 连接 – 在 Docker 容器中运行任务

注意

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

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

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

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

community.docker 1.1.0 中的新功能

概要

  • 运行命令或将/获取文件到现有的 Docker 容器。

  • 使用 requests 库 直接与 Docker 守护进程交互，而不是使用 Docker CLI。如果您想使用 Docker CLI，请使用 community.docker.docker 连接插件。

要求

以下要求需要在执行此连接的本地控制节点上满足。

  • requests

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

  • paramiko（当使用 SSH 和 use_ssh_client=false 时）

  • pyOpenSSL（当使用 TLS 时）

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

参数

参数

注释

api_version

别名：docker_api_version

字符串

Docker 主机上运行的 Docker API 版本。

默认为此集合和 Docker 守护进程支持的最新 API 版本。

如果未在任务中指定该值，则将使用环境变量 DOCKER_API_VERSION 的值。如果未设置环境变量，则将使用默认值。

默认值： "auto"

配置

  • 变量：ansible_docker_api_version

ca_path

别名：ca_cert, tls_ca_cert, cacert_path

路径

通过提供 CA 证书文件的路径，在执行服务器验证时使用 CA 证书。

如果未在任务中指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定的目录中的文件 ca.pem。

此选项在 community.docker 3.6.0 中被称为 ca_cert，并重命名为 ca_path。旧名称已添加为别名，仍然可以使用。

配置

  • 变量：ansible_docker_ca_cert

  • 变量：ansible_docker_ca_path

    在 community.docker 3.6.0 中添加

client_cert

别名：tls_client_cert, cert_path

路径

客户端 TLS 证书文件的路径。

如果在任务中未指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 指定的目录中的文件 cert.pem。

配置

  • 变量：ansible_docker_client_cert

client_key

别名：tls_client_key, key_path

路径

客户端 TLS 密钥文件的路径。

如果在任务中未指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 指定的目录中的文件 key.pem。

配置

  • 变量：ansible_docker_client_key

container_timeout

整数

控制在执行开始后，我们可以等待多长时间来访问容器的读取输出。

默认值： 10

配置

  • INI 条目

    [defaults]
timeout = 10

    [docker_connection]
timeout = 10

    在 community.docker 2.2.0 中添加

  • 环境变量：ANSIBLE_TIMEOUT

  • 环境变量：ANSIBLE_DOCKER_TIMEOUT

    在 community.docker 2.2.0 中添加

  • 变量：ansible_docker_timeout

    在 community.docker 2.2.0 中添加

  • 命令行参数：–timeout

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"

配置

  • 变量：ansible_docker_docker_host

extra_env

字典

在 community.docker 3.12.0 中添加

提供在 Docker 容器中运行命令时设置的额外环境变量。

由于 ansible-core 配置管理器的限制，此选项目前只能作为 Ansible 变量提供。

配置

  • 变量：ansible_docker_extra_env

privileged

布尔值

在 community.docker 3.12.0 中添加

是否应以扩展的权限运行命令。

请注意，这允许命令潜在地突破容器。请谨慎使用！

选择

  • false ←（默认）

  • true

配置

  • INI 条目

    [docker_connection]
privileged = false

  • 环境变量：ANSIBLE_DOCKER_PRIVILEGED

  • 变量：ansible_docker_privileged

remote_addr

字符串

您要访问的容器的名称。

默认值： "inventory_hostname"

配置

  • 变量：inventory_hostname

  • 变量：ansible_host

  • 变量：ansible_docker_host

remote_user

字符串

在容器内执行的用户。

配置

  • INI 条目

    [defaults]
remote_user = VALUE

  • 环境变量：ANSIBLE_REMOTE_USER

  • 变量：ansible_user

  • 变量：ansible_docker_user

  • 关键字：remote_user

  • 命令行参数：–user

timeout

整数

等待 API 响应的最大时间（秒）。

如果在任务中未指定该值，则将使用环境变量 DOCKER_TIMEOUT 的值。如果未设置环境变量，则将使用默认值。

默认值： 60

配置

  • 变量：ansible_docker_timeout

tls

布尔值

使用 TLS 来保护与 API 的连接，而不验证 Docker 主机服务器的真实性。请注意，如果 validate_certs 也设置为 true，它将优先。

如果在任务中未指定该值，则将使用环境变量 DOCKER_TLS 的值。如果未设置环境变量，则将使用默认值。

选择

  • false ←（默认）

  • true

配置

  • 变量：ansible_docker_tls

tls_hostname

字符串

验证 Docker 主机服务器的真实性时，提供服务器的预期名称。

如果在任务中未指定该值，则将使用环境变量 DOCKER_TLS_HOSTNAME 的值。如果未设置环境变量，则将使用默认值。

请注意，此选项在旧版本中的默认值为 localhost。它在 community.docker 3.0.0 中已删除。

配置

  • 变量：ansible_docker_tls_hostname

use_ssh_client

布尔值

在 community.docker 1.5.0 中添加

对于 SSH 传输，使用 ssh 命令行工具而不是 paramiko。

选择

  • false ←（默认）

  • true

validate_certs

别名：tls_verify

布尔值

使用 TLS 并验证 Docker 主机服务器的真实性来保护与 API 的连接。

如果在任务中未指定该值，则将使用环境变量 DOCKER_TLS_VERIFY 的值。如果未设置环境变量，则将使用默认值。

选择

  • false ←（默认）

  • true

配置

  • 变量：ansible_docker_validate_certs

working_dir

字符串

在 community.docker 3.12.0 中添加

在容器中运行命令的目录。

需要 Docker API 版本 1.35 或更高版本。

配置

  • INI 条目

    [docker_connection]
working_dir = VALUE

  • 环境变量：ANSIBLE_DOCKER_WORKING_DIR

  • 变量：ansible_docker_working_dir

注意

注意

作者

  • Felix Fontein (@felixfontein)

提示

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