community.docker.docker_compose – Manage multi-container Docker applications with Docker Compose.¶
Note
This plugin is part of the community.docker collection (version 1.5.0).
To install it use: ansible-galaxy collection install community.docker
.
To use it in a playbook, specify: community.docker.docker_compose
.
Synopsis¶
Uses Docker Compose to start, shutdown and scale services.
Works with compose versions 1 and 2.
Configuration can be read from a
docker-compose.yml
ordocker-compose.yaml
file or inline using the definition option.See the examples for more details.
Supports check mode.
This module was called
docker_service
before Ansible 2.8. The usage did not change.
Requirements¶
The below requirements are needed on the host that executes this module.
Docker API >= 1.20
Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). For Python 2.6,
docker-py
must be used. Otherwise, it is recommended to install thedocker
Python module. Note that both modules should not be installed at the same time. Also note that when both modules are installed and one of them is uninstalled, the other might no longer function and a reinstall of it is required.Docker SDK for Python >= 1.8.0 (use docker-py for Python 2.6)
PyYAML >= 3.11
docker-compose >= 1.7.0
Parameters¶
Notes¶
Note
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_SSL_VERSION
,DOCKER_TLS
,DOCKER_TLS_VERIFY
andDOCKER_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.When connecting to Docker daemon with TLS, you might need to install additional Python packages. For the Docker SDK for Python, version 2.4 or newer, this can be done by installing
docker[tls]
with ansible.builtin.pip.Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions. In general, it will use
$HOME/.docker/config.json
if theDOCKER_CONFIG
environment variable is not specified, and use$DOCKER_CONFIG/config.json
otherwise.This module uses the Docker SDK for Python to communicate with the Docker daemon.
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: no
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: no
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: no
stopped: yes
register: output
- ansible.builtin.debug:
var: output
- ansible.builtin.assert:
that:
- "not web.flask_web_1.state.running"
- "not db.flask_db_1.state.running"
- name: Restart services
community.docker.docker_compose:
project_src: flask
build: no
restarted: yes
register: output
- ansible.builtin.debug:
var: output
- ansible.builtin.assert:
that:
- "web.flask_web_1.state.running"
- "db.flask_db_1.state.running"
- name: Scale the web service to 2
hosts: localhost
gather_facts: no
tasks:
- community.docker.docker_compose:
project_src: flask
scale:
web: 2
register: output
- ansible.builtin.debug:
var: output
- name: Run with inline v2 compose
hosts: localhost
gather_facts: no
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:
- "web.flask_web_1.state.running"
- "db.flask_db_1.state.running"
- name: Run with inline v1 compose
hosts: localhost
gather_facts: no
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:
- "web.flask_web_1.state.running"
- "db.flask_db_1.state.running"
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Authors¶
Chris Houseknecht (@chouseknecht)