community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose CLI plugin
Note
This module is part of the community.docker collection (version 4.8.1).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.docker.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.docker.docker_compose_v2.
New in community.docker 3.6.0
Synopsis
Uses Docker Compose to start or shutdown services.
Requirements
The below requirements are needed on the host that executes this module.
Docker CLI with Docker compose plugin 2.18.0 or later
PyYAML if
definitionis used
Parameters
Parameter |
Comments |
|---|---|
The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by this collection and the docker daemon. If the value is not specified in the task, the value of environment variable Default: |
|
When Right now a prompt is asked whenever a non-matching volume should be re-created. This option is only available on Docker Compose 2.32.0 or newer. Choices:
|
|
Whether to build images before starting containers. This is used when
Choices:
|
|
Use a CA certificate when performing server verification by providing the path to a CA certificate file. If the value is not specified in the task and the environment variable |
|
If set to This can be useful if environment files with Choices:
|
|
The Docker CLI context to use. Mutually exclusive with |
|
Path to the client’s TLS certificate file. If the value is not specified in the task and the environment variable |
|
Path to the client’s TLS key file. If the value is not specified in the task and the environment variable |
|
Compose file describing one or more services, networks and volumes. Mutually exclusive with If provided, PyYAML must be available to this module, and Note that a temporary directory will be created and deleted afterwards when using this option. |
|
When Choices:
|
|
Path to the Docker CLI. If not provided, will search for Docker CLI on the |
|
The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example, If the value is not specified in the task, the value of environment variable Mutually exclusive with |
|
By default environment files are loaded from a
The path is relative to the |
|
List of Compose file names relative to Files are loaded and merged in the order given. Mutually exclusive with |
|
Ignores image building events for change detection. If Note that Docker Compose 2.31.0 is the first Compose 2.x version to emit build events. For older versions, the behavior is always as if Choices:
|
|
List of profiles to enable when starting services. Equivalent to |
|
Provide a project name. If not provided, the project name is taken from the basename of Required when |
|
Path to a directory containing a Compose file ( If Mutually exclusive with |
|
Whether to pull images before running. This is used when
Choices:
|
|
By default containers will be recreated when their configuration differs from the service definition. Setting to Setting to Choices:
|
|
Remove containers for services not defined in the Compose file. Choices:
|
|
Whether to recreate instead of reuse anonymous volumes from previous containers.
Choices:
|
|
Define how to scale services when running Provide a dictionary of key/value pairs where the key is the name of the service and the value is an integer count for the number of containers. |
|
Specifies a subset of services to be targeted. |
|
Desired state of the project.
Choices:
|
|
Timeout in seconds for container shutdown when attached or when containers are already running. |
|
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if If the value is not specified in the task, the value of environment variable Choices:
|
|
When verifying the authenticity of the Docker Host server, provide the expected name of the server. If the value is not specified in the task, the value of environment variable |
|
Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. If the value is not specified in the task, the value of environment variable Choices:
|
|
When running A timeout can be set with the Choices:
|
|
When |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Action groups: community.docker.docker, docker |
Use |
|
Support: full In check mode, pulling the image does not result in a changed result. |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
|
Support: partial If |
When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. This assumes that the system controlled/queried by the module has not changed in a relevant way. |
Notes
Note
The Docker compose CLI plugin has no stable output format (see for example https://github.com/docker/compose/issues/10872), and for the main operations also no machine friendly output format. The module tries to accomodate this with various version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin. Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define
DOCKER_HOST,DOCKER_TLS_HOSTNAME,DOCKER_API_VERSION,DOCKER_CERT_PATH,DOCKER_TLS,DOCKER_TLS_VERIFYandDOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docs.docker.com/machine/reference/env/ for more details.This module does not use the Docker SDK for Python to communicate with the Docker daemon. It directly calls the Docker CLI program.
See Also
See also
- community.docker.docker_compose_v2_pull
Pull a Docker compose project.
Examples
---
# Examples use the django example at https://docs.docker.com/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 }}
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
A list of actions that have been applied. Returned: success |
|
The ID of the resource that was changed. Returned: success Sample: |
|
The status change that happened. Returned: success Can only return:
Sample: |
|
What kind of resource was changed. Returned: success Can only return:
Sample: |
|
A list of containers associated to the service. Returned: success |
|
The container’s command. Returned: success |
|
The timestamp when the container was created. Returned: success Sample: |
|
The container’s exit code. Returned: success |
|
The container’s health check. Returned: success |
|
The container’s ID. Returned: success Sample: |
|
The container’s image. Returned: success |
|
Labels for this container. Returned: success |
|
The local volumes count. Returned: success |
|
Mounts. Returned: success |
|
The container’s primary name. Returned: success |
|
List of names of the container. Returned: success |
|
List of networks attached to this container. Returned: success |
|
List of port assignments as a string. Returned: success |
|
List of port assigments. Returned: success |
|
The protocol. Returned: success Can only return:
|
|
The port that is published. Returned: success |
|
The container’s port the published port maps to. Returned: success |
|
Interface the port is bound to. Returned: success |
|
Amount of time the container runs. Returned: success |
|
The name of the service. Returned: success |
|
The container’s size. Returned: success Sample: |
|
The container’s state. Returned: success Sample: |
|
The container’s status. Returned: success Sample: |
|
A list of images associated to the service. Returned: success |
|
Name of the conainer this image is used by. Returned: success |
|
The image’s ID. Returned: success Sample: |
|
The repository where this image belongs to. Returned: success |
|
The image’s size in bytes. Returned: success |
|
The tag of the image. Returned: success |