community.docker.docker_compose_v2_run 模块 – 在 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_run。

community.docker 3.13.0 中的新增功能

概要 

使用 Docker Compose 在服务的新的容器中运行命令。
这封装了 docker compose run。

需求 

以下需求是在执行此模块的主机上所需的。

带有 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` 是互斥的。
build 布尔值	启动容器之前构建镜像。请注意，构建可能会将信息插入 `stdout` 或 `stderr` 中。选项 `false` ← (默认) `true`
ca_path 别名：ca_cert, tls_ca_cert, cacert_path 路径	通过提供 CA 证书文件的路径来执行服务器验证时使用 CA 证书。如果任务中未指定此值并且设置了环境变量 `DOCKER_CERT_PATH`，则将使用环境变量 `DOCKER_CERT_PATH` 中指定的目录中的 `ca.pem` 文件。
cap_add 列表 / 元素=字符串	要添加到容器的 Linux 功能。
cap_drop 列表 / 元素=字符串	要从容器中删除的 Linux 功能。
chdir 字符串	在其中运行命令的目录。
check_files_existing 布尔值 community.docker 3.9.0 中添加	如果设置为 `false`，模块将不会检查`compose.yaml`、`compose.yml`、`docker-compose.yaml`或`docker-compose.yml`这些文件是否在`project_src`中存在，前提是未提供`files`。如果使用包含`COMPOSE_FILE`的环境文件来配置不同的文件名，这将非常有用。当前模块不会检查环境文件或当前环境中的`COMPOSE_FILE`。选项 `false` `true` ← (默认)
cleanup 布尔值	容器退出时自动删除。对应于`docker compose run`的`--rm`选项。选项 `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`。而是提供返回值`container_id`。选项 `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`。
entrypoint 字符串	覆盖容器镜像的入口点。
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`互斥。
interactive 布尔值	即使未附加，是否保持STDIN打开。选项 `false` `true` ← (默认)
labels 列表 / 元素=字符串	向容器添加或覆盖标签。
name 字符串	为容器分配名称。
no_deps 布尔值	不启动链接的服务。选项 `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`之一。
publish 列表 / 元素=字符串	将容器的端口发布到主机。
quiet_pull 布尔值	拉取镜像但不打印进度信息。请注意，拉取镜像可能会将信息写入`stdout`或`stderr`。选项 `false` ← (默认) `true`
remove_orphans 布尔值	删除Compose文件中未定义的服务对应的容器。选项 `false` ← (默认) `true`
service 字符串 / 必需	要运行命令的服务。
service_ports 布尔值	运行命令时启用所有服务的端口并映射到主机。选项 `false` ← (默认) `true`
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` ← (默认)
use_aliases 布尔值	在容器连接到的网络中使用服务的网络`useAliases`。选项 `false` ← (默认) `true`
user 字符串	如果指定，则使用该用户执行此命令。
validate_certs 别名：tls_verify 布尔值	使用TLS保护与API的连接并验证Docker主机服务器的真实性。如果任务中未指定此值，则将使用环境变量`DOCKER_TLS_VERIFY`的值。如果未设置环境变量，则将使用默认值。选项 `false` ← (默认) `true`
volumes 列表 / 元素=字符串	绑定挂载一个或多个卷。

属性 

属性	支持	描述
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_run:
    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_run:
    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

返回值 

常见返回值已在此处记录，以下是此模块特有的字段

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

作者

Felix Fontein (@felixfontein)

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

作者

集合链接