community.general.docker_compose – Manage multi-container Docker applications with Docker Compose.¶
Note
This plugin is part of the community.general collection (version 1.3.6).
To install it use: ansible-galaxy collection install community.general.
To use it in a playbook, specify: community.general.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.ymlordocker-compose.yamlfile or inline using the definition option.See the examples for more details.
Supports check mode.
This module was called
docker_servicebefore 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-pymust be used. Otherwise, it is recommended to install thedockerPython 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_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.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.jsonif theDOCKER_CONFIGenvironment variable is not specified, and use$DOCKER_CONFIG/config.jsonotherwise.
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.general.docker_compose:
project_src: flask
state: absent
- name: Create and start services
community.general.docker_compose:
project_src: flask
register: output
- ansible.builtin.debug:
var: output
- name: Run `docker-compose up` again
community.general.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.general.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.general.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.general.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.general.docker_compose:
project_src: flask
state: absent
- community.general.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.general.docker_compose:
project_src: flask
state: absent
- community.general.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)