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。您需要其他需求才能使用此模块，有关详细信息，请参阅需求。

要在剧本中使用它，请指定： 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`，则模块不会检查 `project_src` 中是否存在 `compose.yaml`、`compose.yml`、`docker-compose.yaml` 或 `docker-compose.yml` 文件。如果使用包含 `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` 中的一个。
definition 字典 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 字符串	将命令的标准输入直接设置为指定的值。仅当`detach=false`时才能使用。
stdin_add_newline 布尔值	如果设置为`true`，则将换行符附加到`stdin`。选项 `false` `true` ← (默认)
strip_empty_ends 布尔值	从结果中去除标准输出/标准错误末尾的空行。选项 `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)

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

作者

资源链接