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

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.

New in community.docker 3.5.0

Synopsis

  • Uses Docker Compose v2 to manage docker services. This module requires docker-compose >= 2.0.0. and python >= 3.7

  • Configuration can be read from a docker-compose.yaml file.

  • See the examples for more details.

  • Supports check mode.

Requirements

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

Parameters

Parameter

Comments

build

boolean

Use with state present to always build images prior to starting the application.

Same as running docker-compose build with the pull option.

Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents.

Use the nocache option to ignore the image cache when performing the build.

If an existing image is replaced, services using the image will be recreated unless recreate is never.

Choices:

  • false ← (default)

  • true

nocache

boolean

Use with the build option to ignore the cache during the image build process.

Choices:

  • false ← (default)

  • true

project_src

path

Path to a directory containing a docker-compose.yaml file.

Required.

pull

boolean

Use with state present to always pull images prior to starting the application.

Same as running docker-compose pull.

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.

Choices:

  • "always"

  • "never"

  • "smart" ← (default)

remove_images

string

Use with state absent to remove all images or only local images.

Choices:

  • "all"

  • "local"

remove_orphans

boolean

Remove containers for services not defined in the Compose file when not restarted or stopped.

Choices:

  • false ← (default)

  • true

remove_volumes

boolean

Use with state absent to remove data volumes.

Choices:

  • false ← (default)

  • true

restarted

boolean

Use with state present to restart all containers defined in the Compose file.

Choices:

  • false ← (default)

  • true

state

string

Desired state of the project.

Specifying present is the same as running docker-compose up resp. docker-compose stop (with stopped) resp. docker-compose restart (with restarted).

Specifying absent is the same as running docker-compose down.

Choices:

  • "absent"

  • "present" ← (default)

stopped

boolean

Use with state present to stop all containers defined in the Compose file.

Choices:

  • false ← (default)

  • true

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

# Set up a virtual environment for the module and install python on whales
- name: Set up virtual env for compose v2
  ansible.builtin.pip:
    name:
    - python-on-whales
    virtualenv: ~/ansible-compose-v2

# Ensure project directory is present
- name: Create directory if it does not exist
  ansible.builtin.file:
    path: uptime-kuma
    state: directory
# Create the docker compose file
- name: Create compose file with content
  ansible.builtin.copy:
    dest: "uptime-kuma/docker-compose.yaml"
    content: |
      version: '3.3'

      services:
        uptime-kuma:
          image: louislam/uptime-kuma:1
          container_name: uptime-kuma
          volumes:
            - ./uptime-kuma-data:/app/data
          ports:
            - 3001:3001
          restart: always

# Tear down any containers, remove images and volumes
- name: Tear down all existing containers
  vars:
    ansible_python_interpreter: ansible-compose-v2/bin/python
  community.docker.docker_compose_v2:
    project_src: uptime-kuma/docker-compose.yaml
    remove_volumes: true
    remove_orphans: true
    remove_images: all
    state: absent

# Pull the latest image and then start services
- name: Pull image and start service
  vars:
    ansible_python_interpreter: ansible-compose-v2/bin/python
  community.docker.docker_compose_v2:
    project_src: uptime-kuma/docker-compose.yaml
    pull: true
    state: present

# Restart services
- name: Restart service
  vars:
    ansible_python_interpreter: ansible-compose-v2/bin/python
  community.docker.docker_compose_v2:
    project_src: uptime-kuma/docker-compose.yaml
    restarted: true
    state: present

# Stop services
- name: Stop service
  vars:
    ansible_python_interpreter: ansible-compose-v2/bin/python
  community.docker.docker_compose_v2:
    project_src: uptime-kuma/docker-compose.yaml
    stopped: true
    state: present

# Start services, recreating all containers
- name: Recreate service
  vars:
    ansible_python_interpreter: ansible-compose-v2/bin/python
  community.docker.docker_compose_v2:
    project_src: uptime-kuma/docker-compose.yaml
    recreate: always
    state: present

Return Values

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

Key

Description

actions

list / elements=string

List stating which compose commands were run (not the entire command itself).

Returned: success

Sample: ["pull", "up"]

changed

boolean

If something was changed (currently, changed is (almost) always true as there is no check of current state).

Returned: always

Sample: true

msg

boolean

In docker failures, has docker command + some description. In other failures, stringified exception is returned. In success, descriptive message of what happened.

Returned: always

Sample: true

rc

string

Return code of executed docker command.

Returned: failure from docker

Sample: "12"

Authors

  • Sid Sun (@SidSun)