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。您需要其他要求才能使用此模块，请参阅 要求 以了解详情。

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

community.docker 3.6.0 中新增

概要

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

要求

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

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

• 如果使用 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，模块将不检查 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 文件。
定义 字典 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 保护与 API 的连接，无需验证 Docker 主机服务器的身份。请注意，如果validate_certs也设置为true，则它将优先。 如果任务中未指定此值，则将使用环境变量DOCKER_TLS的值。如果未设置环境变量，则将使用默认值。 选项 false ← (默认) true
tls_hostname 字符串	验证 Docker 主机服务器身份时，请提供服务器的预期名称。 如果任务中未指定此值，则将使用环境变量DOCKER_TLS_HOSTNAME的值。如果未设置环境变量，则将使用默认值。
validate_certs 别名：tls_verify 布尔值	使用 TLS 保护与 API 的连接并验证 Docker 主机服务器的身份。 如果任务中未指定此值，则将使用环境变量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 列表 / 元素=字典	已应用操作的列表。 返回：成功
id 字符串	已更改资源的 ID。 返回：成功 示例："container"
status 字符串	发生的狀態更改。 返回：成功 只能返回 "Starting" "Exiting" "Restarting" "Creating" "Stopping" "Killing" "Removing" "Recreating" "Pulling" "Building" 示例："Creating"
what 字符串	更改了哪种类型的资源。 返回：成功 只能返回 "container" "image" "network" "service" "unknown" "volume" 示例："container"
containers 列表 / 元素=字典	与服务关联的容器列表。 返回：成功
Command 任意	容器的命令。 返回：成功
CreatedAt 字符串	创建容器的时间戳。 返回：成功 示例："2024-01-02 12:20:41 +0100 CET"
ExitCode 整数	容器的退出代码。 返回：成功
Health 任意	容器的健康检查。 返回：成功
ID 字符串	容器的 ID。 返回：成功 示例："44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135"
Image 字符串	容器的镜像。 返回：成功
Labels 字典	此容器的标签。 返回：成功
LocalVolumes 字符串	本地卷的数量。 返回：成功
Mounts 字符串	挂载点。 返回：成功
Name 字符串	容器的主要名称。 返回：成功
Names 列表 / 元素=字符串	容器名称列表。 返回：成功
Networks 列表 / 元素=字符串	附加到此容器的网络列表。 返回：成功
Ports 字符串	端口分配的字符串列表。 返回：成功
Publishers 列表 / 元素=字典	端口分配列表。 返回：成功
Protocol 字符串	协议。 返回：成功 只能返回 "tcp" "udp"
PublishedPort 整数	发布的端口。 返回：成功
TargetPort 整数	发布的端口映射到的容器端口。 返回：成功
URL 字符串	端口绑定的接口。 返回：成功
RunningFor 字符串	容器运行的时间量。 返回：成功
Service 字符串	服务的名称。 返回：成功
Size 字符串	容器的大小。 返回：成功 示例："0B"
State 字符串	容器的状态。 返回：成功 示例："running"
Status 字符串	容器的状态。 返回：成功 示例："Up About a minute"
images 列表 / 元素=字典	与服务关联的镜像列表。 返回：成功
ContainerName 字符串	此镜像所使用的容器的名称。 返回：成功
ID 字符串	镜像的 ID。 返回：成功 示例："sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1"
Repository 字符串	此镜像所属的仓库。 返回：成功
Size 整数	镜像的大小（字节）。 返回：成功
Tag 字符串	镜像的标签。 返回：成功

作者

• Felix Fontein (@felixfontein)

资源链接

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