community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose.

Note

This module is part of the community.docker collection (version 3.5.0).

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.

Synopsis 

Uses Docker Compose to start and shutdown services.
Swarm mode is not supported (thus secrets and configs are not supported).
Configuration can be read from a Compose file or inline using the definition option.
See the examples for more details.

Requirements 

The below requirements are needed on the host that executes this module.

docker-compose >= 2.0.0
PyYAML

Parameters 

Parameter	Comments
build boolean	Use with state `present` to always build images prior to starting the application. Equivalent to `docker-compose up --build`. Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents. If an existing image is replaced, services using the image will be recreated unless recreate is `never`. Choices: `false` ← (default) `true`
definition dictionary	Compose file describing one or more services, networks and volumes. Mutually exclusive with files.
dependencies boolean	When state is `present` specify whether or not to include linked services. When false, equivalent to `docker-compose up --no-deps`. When state is `pull` specify whether or not to also pull for linked services. When true, equivalent to `docker-compose pull --include-deps`. Choices: `false` `true` ← (default)
docker_host aliases: docker_url string	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, `tcp://192.0.2.23:2376`. If TLS is used to encrypt the connection, the module will automatically replace `tcp` in the connection URL with `https`. If the value is not specified in the task, the value of environment variable `DOCKER_HOST` will be used instead. If the environment variable is not set, the default value will be used. Default: `"unix://var/run/docker.sock"`
env_file path	By default environment files are loaded from a `.env` file located directly under the project_src directory. env_file can be used to specify the path of a custom environment file instead. The path is relative to the project_src directory. Equivalent to `docker-compose --env-file`.
files list / elements=path	List of Compose files. Files are passed to docker-compose in the order given. Equivalent to `docker-compose -f`.
nocache boolean	Use with the build option to ignore the cache during the image build process. Equivalent to `docker-compose build --no-cache`. Choices: `false` ← (default) `true`
profiles list / elements=string	List of profiles to enable when starting services. Equivalent to `docker-compose --profile`.
project_name string	Provide a project name. Equivalent to `docker-compose --project-name`.
project_src path	Path to the root directory of the Compose project. Required when definition is provided.
pull boolean	Use with state `present` to always pull images prior to starting the application. Equivalent to `docker-compose up --pull always`. When a new image is pulled, services using the image will be recreated unless recreate is `never`. Choices: `false` ← (default) `true`
recreate string	By default containers will be recreated when their configuration differs from the service definition. Setting to `never` ignores configuration differences and leaves existing containers unchanged. Setting to `always` forces recreation of all existing containers. When set to `never`, equivalent to `docker-compose up --no-recreate`. When set to `always`, equivalent to `docker-compose up --force-recreate`. Choices: `"always"` `"never"` `"smart"` ← (default)
remove_images string	Use with state `absent` to remove all images or only local images. Equivalent to `docker-compose down --rmi all\|local`. Choices: `"all"` `"local"`
remove_orphans boolean	Remove containers for services not defined in the Compose file. Equivalent to `docker-compose up --remove-orphans` or `docker-compose down --remove-orphans`. Choices: `false` ← (default) `true`
remove_volumes boolean	Use with state `absent` to remove data volumes. Equivalent to `docker-compose down --volumes`. Choices: `false` ← (default) `true`
services list / elements=string	When state is `present` run `docker-compose up` resp. `docker-compose stop` (with stopped) resp. `docker-compose restart` (with restarted) on a subset of services. If empty, which is the default, the operation will be performed on all services defined in the Compose file (or inline definition).
state string	Desired state of the project. Specifying `pulled` is the same as running `docker-compose pull`. Specifying `built` is the same as running `docker-compose build`. Specifying `stopped` is the same as running `docker-compose stop`. Specifying `present` is the same as running `docker-compose up`. Specifying `restarted` is the same as running `docker-compose restart`. Specifying `absent` is the same as running `docker-compose down`. Choices: `"absent"` `"built"` `"present"` ← (default) `"pulled"` `"restarted"` `"stopped"`
timeout integer	Timeout in seconds for container shutdown when attached or when containers are already running. By default `compose` will use a `10s` timeout unless `default_grace_period` is defined for a particular service in the project_src.

Attributes 

Attribute	Support	Description
check_mode	Support: none	Check mode is not supported because the `docker-compose` CLI doesn’t allow it.
diff_mode	Support: none	Diff mode is not supported.

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:
        project_src: flask
        state: absent

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

    - ansible.builtin.debug:
        var: output

    - name: Run `docker-compose up` again
      community.docker.docker_compose:
        project_src: flask
        build: false
      register: output

    - ansible.builtin.debug:
        var: output

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

    - name: Stop all services
      community.docker.docker_compose:
        project_src: flask
        build: false
        stopped: true
      register: output

    - ansible.builtin.debug:
        var: output

    - ansible.builtin.assert:
        that:
          - "'stopped' in containers['flask_web_1'] | default([])"
          - "'stopped' in containers['flask_db_1'] | default([])"

    - name: Restart services
      community.docker.docker_compose:
        project_src: flask
        build: false
        restarted: true
      register: output

    - ansible.builtin.debug:
        var: output

    - ansible.builtin.assert:
        that:
          - "'started' in containers['flask_web_1'] | default([])"
          - "'started' in containers['flask_db_1'] | default([])"

- name: Run with inline Compose file version 2
  # https://docs.docker.com/compose/compose-file/compose-file-v2/
  hosts: localhost
  gather_facts: false
  tasks:
    - community.docker.docker_compose:
        project_src: flask
        state: absent

    - community.docker.docker_compose:
        project_name: flask
        definition:
          version: '2'
          services:
            db:
              image: postgres
            web:
              build: "{{ playbook_dir }}/flask"
              command: "python manage.py runserver 0.0.0.0:8000"
              volumes:
                - "{{ playbook_dir }}/flask:/code"
              ports:
                - "8000:8000"
              depends_on:
                - db
      register: output

    - ansible.builtin.debug:
        var: output

    - ansible.builtin.assert:
        that:
          - "'started' in containers['flask_web_1'] | default([])"
          - "'started' in containers['flask_db_1'] | default([])"

- name: Run with inline Compose file version 1
  # https://docs.docker.com/compose/compose-file/compose-file-v1/
  hosts: localhost
  gather_facts: false
  tasks:
    - community.docker.docker_compose:
        project_src: flask
        state: absent

    - community.docker.docker_compose:
        project_name: flask
        definition:
            db:
              image: postgres
            web:
              build: "{{ playbook_dir }}/flask"
              command: "python manage.py runserver 0.0.0.0:8000"
              volumes:
                - "{{ playbook_dir }}/flask:/code"
              ports:
                - "8000:8000"
              links:
                - db
      register: output

    - ansible.builtin.debug:
        var: output

    - ansible.builtin.assert:
        that:
          - "'started' in containers['flask_web_1'] | default([])"
          - "'started' in containers['flask_db_1'] | default([])"

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
containers dictionary	A dictionary mapping containers to the various status they went through during `docker-compose` operation. A dict of lists, where dict keys are containers names and lists elements are statuses. Returned: always, unless when `docker-compose` was not given the chance to run Sample: `{"container_1": ["stopped", "removed"], "container_2": ["running"]}`
images dictionary	A dictionary mapping images to the various status they went through during `docker-compose` operation. A dict of lists, where dict keys are services names and lists elements are statuses. `docker-compose` does not report images by their names, but by the name of the service which require them. Returned: always, unless when `docker-compose` was not given the chance to run Sample: `{"service_1": ["pulled"], "service_2": ["pulled"]}`
networks dictionary	A dictionary mapping networks to the various status they went through during `docker-compose` operation. A dict of lists, where dict keys are networks names and lists elements are statuses. Returned: always, unless when `docker-compose` was not given the chance to run Sample: `{"network1": ["created"], "network2": ["removed"]}`
stderr string	The stderr from docker-compose. Returned: always, unless when `docker-compose` was not given the chance to run
stdout string	The stdout from docker-compose. Returned: always, unless when `docker-compose` was not given the chance to run
volumes dictionary	A dictionary mapping volumes to the various status they went through during `docker-compose` operation. A dict of lists, where dict keys are volumes names and lists elements are statuses. Returned: always, unless when `docker-compose` was not given the chance to run Sample: `{"volume_1": ["created"], "volume_2": ["removed"]}`

Authors

Léo El Amri (@lel-amri)

Collection links

Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication

community.docker.docker_compose_v2 module – Manage multi-container Docker applications with Docker Compose.

Synopsis

Requirements

Parameters

Attributes

Examples

Return Values