community.docker.docker_compose_v2 模块 – 使用 Docker Compose CLI 插件管理多容器 Docker 应用

注意

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

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

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

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

community.docker 3.6.0 中的新增功能

概要

• 使用 Docker Compose 启动或关闭服务。

要求

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

• Docker CLI，带有 Docker compose 插件 2.18.0 或更高版本

• 如果使用 definition，则需要 PyYAML

参数

参数	注释
api_version 别名: docker_api_version 字符串	在 Docker 主机上运行的 Docker API 版本。 默认为此集合和 Docker 守护程序支持的最新 API 版本。 如果在任务中未指定该值，则将改为使用环境变量 DOCKER_API_VERSION 的值。如果未设置环境变量，则将使用默认值。 默认: "auto"
build 字符串	是否在启动容器之前构建镜像。这在运行 docker compose up 时使用。 always 始终在启动容器之前构建。这等效于 docker compose up 的 --build 选项。 never 永远不在启动容器之前构建。这等效于 docker compose up 的 --no-build 选项。 policy 使用 Compose 文件中定义的策略。 选项 "always" "never" "policy" ← (默认)
ca_path 别名: ca_cert, tls_ca_cert, cacert_path 路径	通过提供 CA 证书文件的路径，在使用服务器验证时使用 CA 证书。 如果在任务中未指定该值，并且设置了环境变量 DOCKER_CERT_PATH，则将使用环境变量 DOCKER_CERT_PATH 中指定的目录中的 ca.pem 文件。
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 文件。
定义 字典 在 community.docker 3.9.0 中添加	描述一个或多个服务、网络和卷的 Compose 文件。 与 project_src 和 files 互斥。必须提供 project_src 和 definition 中的一个。 如果提供了此项，则此模块必须可以使用 PyYAML，并且必须指定 project_name。 请注意，使用此选项时，会创建一个临时目录，并在之后删除。
依赖关系 布尔值	当 state 为 present 或 restarted 时，指定是否包含链接的服务。 选项 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_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 互斥。
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 中的一个。
pull 字符串	是否在运行之前拉取镜像。这在运行 docker compose up 时使用。 always 确保始终拉取镜像，即使它们已经存在于 Docker 守护进程上。 missing 仅在它们不存在于 Docker 守护进程上时才拉取它们。 never 永不拉取镜像。如果它们不存在，则模块在尝试创建需要它们的容器时将失败。 policy 使用 Compose 文件中为服务定义的 pull_policy 来确定要执行的操作。 选项 "always" "missing" "never" "policy" ← (默认)
recreate 字符串	默认情况下，当容器的配置与服务定义不同时，将重新创建容器。 设置为 never 将忽略配置差异，并使现有容器保持不变。 设置为 always 将强制重新创建所有现有容器。 选项 "always" "never" "auto" ←（默认）
remove_images 字符串	与 state=absent 一起使用以删除所有镜像或仅删除本地镜像。 选项 "all" "local"
remove_orphans 布尔值	删除 Compose 文件中未定义的服务容器。 选项 false ←（默认） true
remove_volumes 布尔值	与 state=absent 一起使用以删除数据卷。 选项 false ←（默认） true
renew_anon_volumes 布尔值 在 community.docker 4.0.0 中添加	是否重新创建而不是重用以前容器中的匿名卷。 true 等效于 docker compose up 的 --renew-anon-volumes 选项。 选项 false ←（默认） true
scale 字典 在 community.docker 3.7.0 中添加	定义在运行 docker compose up 时如何扩展服务。 提供键/值对的字典，其中键是服务的名称，值是容器数量的整数计数。
services 列表 / 元素=字符串	指定要作为目标的服务的子集。
state 字符串	项目的所需状态。 present 等效于运行 docker compose up。 stopped 等同于运行 docker compose stop。 absent 等同于运行 docker compose down。 restarted 等同于运行 docker compose restart。 选项 “absent” “stopped” “restarted” "present" ←（默认）
timeout 整数	当附加到容器或容器已在运行时，容器关闭的超时时间（秒）。
tls 布尔值	通过使用 TLS 但不验证 Docker 主机服务器的真实性来保护与 API 的连接。请注意，如果 validate_certs 也设置为 true，则它将优先。 如果任务中未指定该值，则将使用环境变量 DOCKER_TLS 的值。如果未设置环境变量，则将使用默认值。 选项 false ←（默认） true
tls_hostname 字符串	在验证 Docker 主机服务器的真实性时，提供服务器的预期名称。 如果任务中未指定该值，则将使用环境变量 DOCKER_TLS_HOSTNAME 的值。如果未设置环境变量，则将使用默认值。
validate_certs 别名: tls_verify 布尔值	通过使用 TLS 并验证 Docker 主机服务器的真实性来保护与 API 的连接。 如果任务中未指定该值，则将使用环境变量 DOCKER_TLS_VERIFY 的值。如果未设置环境变量，则将使用默认值。 选项 false ←（默认） true
wait 布尔值 在 community.docker 3.8.0 中添加	在运行 docker compose up 时，传递 --wait 以等待服务运行/健康。 可以使用 wait_timeout 选项设置超时。 选项 false ←（默认） true
wait_timeout 整数 在 community.docker 3.8.0 中添加	当 wait=true 时，最多等待此秒数。

属性

属性	支持	描述
action_group	操作组： community.docker.docker、docker	在 module_defaults 中使用 group/docker 或 group/community.docker.docker 为此模块设置默认值。
check_mode	支持： 完全 在检查模式下，拉取镜像不会导致结果发生更改。	可以在 check_mode 中运行并返回更改的状态预测，而无需修改目标。
diff_mode	支持： 无	当处于差异模式时，将返回已更改（或可能需要在 check_mode 中更改）的详细信息。

注意

注意

• 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_pull

拉取 Docker compose 项目。

示例

# Examples use the django example at https://docs.docker.net.cn/compose/django. Follow it to create the
# flask directory

- name: Run using a project directory
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Tear down existing services
      community.docker.docker_compose_v2:
        project_src: flask
        state: absent

    - name: Create and start services
      community.docker.docker_compose_v2:
        project_src: flask
      register: output

    - name: Show results
      ansible.builtin.debug:
        var: output

    - name: Run `docker compose up` again
      community.docker.docker_compose_v2:
        project_src: flask
      register: output

    - name: Show results
      ansible.builtin.debug:
        var: output

    - ansible.builtin.assert:
        that: not output.changed

    - name: Stop all services
      community.docker.docker_compose_v2:
        project_src: flask
        state: stopped
      register: output

    - name: Show results
      ansible.builtin.debug:
        var: output

    - name: Verify that web and db services are not running
      ansible.builtin.assert:
        that:
          - web_container.State != 'running'
          - db_container.State != 'running'
      vars:
        web_container: >-
          {{ output.containers | selectattr("Service", "equalto", "web") | first }}
        db_container: >-
          {{ output.containers | selectattr("Service", "equalto", "db") | first }}

    - name: Restart services
      community.docker.docker_compose_v2:
        project_src: flask
        state: restarted
      register: output

    - name: Show results
      ansible.builtin.debug:
        var: output

    - name: Verify that web and db services are running
      ansible.builtin.assert:
        that:
          - web_container.State == 'running'
          - db_container.State == 'running'
      vars:
        web_container: >-
          {{ output.containers | selectattr("Service", "equalto", "web") | first }}
        db_container: >-
          {{ output.containers | selectattr("Service", "equalto", "db") | first }}

返回值

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

键	描述
actions 列表 / elements=字典	已应用的动作列表。 返回： 成功
id 字符串	已更改的资源的 ID。 返回： 成功 示例： "container"
status 字符串	发生的状态更改。 返回： 成功 只能返回 “启动中” “退出中” “重启中” “创建中” “停止中” “杀死中” “移除中” “重新创建中” “拉取中” “构建中” 示例： "Creating"
what 字符串	更改了哪种类型的资源。 返回： 成功 只能返回 “container” “image” “network” “service” “unknown” “volume” 示例： "container"
containers 列表 / elements=字典	与服务关联的容器列表。 返回： 成功
Command 任何	容器的命令。 返回： 成功
CreatedAt 字符串	创建容器的时间戳。 返回： 成功 示例： "2024-01-02 12:20:41 +0100 CET"
ExitCode 整数	容器的退出代码。 返回： 成功
Health 任何	容器的健康检查。 返回： 成功
ID 字符串	容器的 ID。 返回： 成功 示例： "44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135"
Image 字符串	容器的镜像。 返回： 成功
Labels 字典	此容器的标签。 返回： 成功
LocalVolumes 字符串	本地卷计数。 返回： 成功
Mounts 字符串	挂载。 返回： 成功
Name 字符串	容器的主名称。 返回： 成功
Names 列表 / 元素=字符串	容器的名称列表。 返回： 成功
Networks 列表 / 元素=字符串	附加到此容器的网络列表。 返回： 成功
Ports 字符串	端口分配的字符串列表。 返回： 成功
Publishers 列表 / elements=字典	端口分配列表。 返回： 成功
Protocol 字符串	协议。 返回： 成功 只能返回 “tcp” “udp”
PublishedPort 整数	发布的端口。 返回： 成功
TargetPort 整数	已发布的端口映射到的容器端口。 返回： 成功
URL 字符串	端口绑定到的接口。 返回： 成功
RunningFor 字符串	容器运行的时间。 返回： 成功
Service 字符串	服务的名称。 返回： 成功
Size 字符串	容器的大小。 返回： 成功 示例： "0B"
State 字符串	容器的状态。 返回： 成功 示例： "running"
Status 字符串	容器的状态。 返回： 成功 示例： "Up About a minute"
images 列表 / elements=字典	与服务关联的镜像列表。 返回： 成功
ContainerName 字符串	此镜像使用的容器名称。 返回： 成功
ID 字符串	镜像的 ID。 返回： 成功 示例： "sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1"
Repository 字符串	此镜像所属的仓库。 返回： 成功
Size 整数	镜像的大小（以字节为单位）。 返回： 成功
Tag 字符串	镜像的标签。 返回： 成功

作者

• Felix Fontein (@felixfontein)

集合链接

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