community.docker.docker_compose_v2_exec 模块 – 在 Compose 服务的容器中运行命令

注意

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

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

要安装它，请使用：ansible-galaxy collection install community.docker。您需要进一步的要求才能使用此模块，请参阅 要求 了解详细信息。

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

community.docker 3.13.0 中的新功能

概要

• 使用 Docker Compose 在服务的容器中运行命令。

• 这可以用于在现有服务的容器中运行一次性命令，并封装 docker compose exec。

要求

以下要求需要在执行此模块的主机上满足。

• 带有 Docker Compose 插件 2.18.0 或更高版本的 Docker CLI

• 如果使用 definition，则需要 PyYAML

参数

参数	注释
api_version 别名: docker_api_version 字符串	在 Docker 主机上运行的 Docker API 版本。 默认为此集合和 Docker 守护程序支持的最新 API 版本。 如果在任务中未指定该值，则将使用环境变量 DOCKER_API_VERSION 的值。如果未设置环境变量，则将使用默认值。 默认值: "auto"
argv 列表 / 元素=字符串	要执行的命令。 由于这是一个参数列表，因此无需引号。 必须指定 argv 或 command 中的一个。
ca_path 别名: ca_cert, tls_ca_cert, cacert_path 路径	通过提供 CA 证书文件的路径，在执行服务器验证时使用 CA 证书。 如果在任务中未指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定的目录中的 ca.pem 文件。
chdir 字符串	运行命令的目录。
check_files_existing 布尔值 在 community.docker 3.9.0 中添加	如果设置为 false，则当未提供 files 时，模块将不会检查 compose.yaml、 compose.yml、 docker-compose.yaml 或 docker-compose.yml 中的任何一个文件是否存在于 project_src 中。 如果使用带有 COMPOSE_FILE 的环境文件来配置不同的文件名，这将很有用。该模块目前不检查环境文件或当前环境中的 COMPOSE_FILE。 选项 false true ← (默认)
cli_context 字符串	要使用的 Docker CLI 上下文。 与 docker_host 互斥。
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 字符串	要执行的命令。 必须指定 argv 或 command 中的一个。
定义 字典 在 community.docker 3.9.0 中添加	描述一个或多个服务、网络和卷的 Compose 文件。 与 project_src 和 files 互斥。必须提供 project_src 和 definition 中的一个。 如果提供，PyYAML 必须可用于此模块，并且必须指定 project_name。 请注意，使用此选项时，将创建一个临时目录，并在之后删除。
detach 布尔值	是否同步运行命令（detach=false，默认）或异步运行命令（detach=true）。 如果设置为 true，则不能提供 stdin，并且不会返回返回值 stdout、 stderr 和 rc。 选项 false ← (默认) true
docker_cli 路径	Docker CLI 的路径。如果未提供，将在 PATH 上搜索 Docker CLI。
docker_host 别名: docker_url 字符串	用于连接 Docker API 的 URL 或 Unix 套接字路径。要连接到远程主机，请提供 TCP 连接字符串。例如，tcp://192.0.2.23:2376。如果使用 TLS 加密连接，模块会自动将连接 URL 中的 tcp 替换为 https。 如果任务中未指定该值，则将使用环境变量 DOCKER_HOST 的值。如果未设置环境变量，则将使用默认值。 与 cli_context 互斥。如果未提供 docker_host 和 cli_context，则使用值 unix:///var/run/docker.sock。
env 字典	环境变量及其各自值的字典，这些值将传递给容器内运行的命令。 YAML 解析器可能会将值解析为数字、布尔值或其他类型，因此必须用引号引起来（例如 "true"），以避免数据丢失。 请注意，如果要使用 Jinja2 模板传递值，例如 "{{ value }}"，则需要添加 | string，以防止 Ansible 将诸如 "true" 之类的字符串转换回布尔值。正确的方法是使用 "{{ value | string }}"。
env_files 列表 / 元素=路径	默认情况下，环境变量文件从位于 project_src 目录下的 .env 文件加载。 可以使用 env_files 来指定一个或多个自定义环境变量文件的路径。 路径是相对于 project_src 目录的。
files 列表 / 元素=路径 在 community.docker 3.7.0 中添加	相对于 project_src 的 Compose 文件名列表，用于代替主 Compose 文件（compose.yml、 compose.yaml、 docker-compose.yml 或 docker-compose.yaml）。 文件会按照给定的顺序加载和合并。 与 definition 互斥。
index 整数	如果服务有多个副本，则是在其中运行命令的容器的索引。
privileged 布尔值	是否向进程授予扩展权限。 选项 false ← (默认) true
profiles 列表 / 元素=字符串	启动服务时要启用的配置文件列表。 等效于 docker compose --profile。
project_name 字符串	提供项目名称。如果未提供，则项目名称取自 project_src 的基本名称。 当提供了 definition 时，此项为必需。
project_src 路径	包含 Compose 文件的目录路径（compose.yml、compose.yaml、docker-compose.yml 或 docker-compose.yaml）。 如果提供了 files，则会在此目录中查找这些文件。 与 definition 互斥。必须提供 project_src 和 definition 中的一个。
service 字符串 / 必需	要在其中运行命令的服务。
stdin 字符串	将命令的 stdin 直接设置为指定的值。 只有在 detach=false 时才能使用。
stdin_add_newline 布尔值	如果设置为 true，则会在 stdin 末尾附加一个换行符。 选项 false true ← (默认)
strip_empty_ends 布尔值	从结果中删除 stdout/stderr 末尾的空行。 选项 false true ← (默认)
tls 布尔值	使用 TLS 安全连接到 API，但不验证 Docker 主机服务器的真实性。请注意，如果 validate_certs 也设置为 true，则以后者为准。 如果在任务中未指定该值，则会改用环境变量 DOCKER_TLS 的值。如果未设置环境变量，则会使用默认值。 选项 false ← (默认) true
tls_hostname 字符串	在验证 Docker 主机服务器的真实性时，提供服务器的预期名称。 如果在任务中未指定该值，则会改用环境变量 DOCKER_TLS_HOSTNAME 的值。如果未设置环境变量，则会使用默认值。
tty 布尔值	是否分配 TTY。 选项 false true ← (默认)
user 字符串	如果指定，则使用该用户执行此命令。
validate_certs 别名：tls_verify 布尔值	使用 TLS 并验证 Docker 主机服务器的真实性，从而安全连接到 API。 如果在任务中未指定该值，则会改用环境变量 DOCKER_TLS_VERIFY 的值。如果未设置环境变量，则会使用默认值。 选项 false ← (默认) true

属性

属性	支持	描述
action_group	操作组： community.docker.docker, docker	在 module_defaults 中使用 group/docker 或 group/community.docker.docker 为此模块设置默认值。
check_mode	支持：无	可以在 check_mode 中运行，并返回更改状态预测，而不会修改目标。
diff_mode	支持：无	当处于差异模式时，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

注释

注意

• 如果您需要在 command 或 argv 中评估容器的环境变量，则需要通过 shell 传递命令，例如 command=/bin/sh -c "echo $ENV_VARIABLE"。

• Docker compose CLI 插件没有稳定的输出格式（例如，请参阅 https://github.com/docker/compose/issues/10872），对于主要操作也没有机器友好的输出格式。该模块尝试通过各种依赖于版本的行为调整以及测试旧版本和较新版本的 Docker compose CLI 插件来解决此问题。目前，该模块已使用 2.18.1 到 2.23.3 之间的多个插件版本进行了测试。插件版本的确切列表将随时间变化。Docker compose CLI 插件的新版本可能随时会破坏此模块。

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

另请参阅

另请参阅

community.docker.docker_compose_v2

使用 Docker Compose CLI 插件管理多容器 Docker 应用程序。

示例

- name: Run a simple command (command)
  community.docker.docker_compose_v2_exec:
    service: foo
    command: /bin/bash -c "ls -lah"
    chdir: /root
  register: result

- name: Print stdout
  ansible.builtin.debug:
    var: result.stdout

- name: Run a simple command (argv)
  community.docker.docker_compose_v2_exec:
    service: foo
    argv:
      - /bin/bash
      - "-c"
      - "ls -lah > /dev/stderr"
    chdir: /root
  register: result

- name: Print stderr lines
  ansible.builtin.debug:
    var: result.stderr_lines

返回值

通用返回值记录在此处，以下是此模块特有的字段

键	描述
rc 整数	命令的退出代码。 返回：成功和 detach=false 示例： 0
stderr 字符串	容器命令的标准错误输出。 返回：成功和 detach=false
stdout 字符串	容器命令的标准输出。 返回：成功和 detach=false

作者

• Felix Fontein (@felixfontein)

集合链接

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