community.docker.docker_compose module – Manage multi-container Docker applications with Docker Compose V1
+community.docker.docker_compose
Note
-This module is part of the community.docker collection (version 3.13.2).
-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.
This plugin was part of the community.docker collection (version 4.0.0).
DEPRECATED
--
-
- Removed in: -
version 4.0.0
-
-- Why: -
This module uses docker-compose v1, which is End of Life since July 2022.
-
-- Alternative: -
Migrate to community.docker.docker_compose_v2
-
-
Synopsis
--
-
Uses Docker Compose to start, shutdown and scale services. This module requires docker-compose < 2.0.0. Use the community.docker.docker_compose_v2 module for using the modern Docker compose CLI plugin.
-Configuration can be read from a
docker-compose.ymlordocker-compose.yamlfile or inline using thedefinitionoption.
-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.25
-Docker SDK for Python: Please note that the docker-py Python module has been superseded by docker (see here for details). 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, < 7. Docker SDK for Python 7+ is incompatible to docker-compose v1.
-PyYAML >= 3.11
-docker-compose >= 1.7.0, < 2.0.0
-
Parameters
-Parameter |
-Comments |
-
|---|---|
| - | The version of the Docker API running on the Docker Host. -Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon. -If the value is not specified in the task, the value of environment variable Default: |
-
| - | Use with Same as running Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents. -Use the If an existing image is replaced, services using the image will be recreated unless 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 This option was called |
-
| - | 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 |
-
| - | Debug mode -Choices: -
|
-
| - | Compose file describing one or more services, networks and volumes. -Mutually exclusive with |
-
| - | When Choices: -
|
-
| - | 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 Default: |
-
| - | By default environment files are loaded from a
The path is relative to the Requires Note: |
-
| - | List of Compose file names relative to Files are loaded and merged in the order given. - |
-
| - | Whether or not to check the Docker daemon’s hostname against the name provided in the client certificate. -Choices: -
|
-
| - | Use with the Choices: -
|
-
| - | List of profiles to enable when starting services. -Equivalent to Requires |
-
| - | Provide a project name. If not provided, the project name is taken from the basename of Required when |
-
| - | Path to a directory containing a Mutually exclusive with Required when no |
-
| - | Use with Same as running When a new image is pulled, services using the image will be recreated unless 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: -
|
-
| - | - |
| - | Use with If Choices: -
|
-
| - | When |
-
| - | When If empty, which is the default, the operation will be performed on all services defined in the Compose file (or inline |
-
| - | Provide a valid SSL version number. Default value determined by SSL Python module. -If the value is not specified in the task, the value of environment variable Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error. - |
-
| - | Desired state of the project. -Specifying Specifying Choices: -
|
-
| - | Use with If Requires Choices: -
|
-
| - | Timeout in seconds for container shutdown when attached or when containers are already running. -By default |
-
| - | 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 Note that this option had a default value Note: this option is no longer supported for Docker SDK for Python 7.0.0+. Specifying it with Docker SDK for Python 7.0.0 or newer will lead to an error. - |
-
| - | Currently ignored for this module, but might suddenly be supported later on. -Choices: -
|
-
| - | 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: -
|
-
Attributes
-Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.docker.docker, docker - |
-Use |
-
| - | Support: full - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
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.
-This module uses the Docker SDK for Python to communicate with the Docker daemon.
-
See Also
-See also
--
-
- community.docker.docker_compose_v2
Manage multi-container Docker applications with Docker Compose CLI plugin.
-
-
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
-
- - name: Show results
- ansible.builtin.debug:
- var: output
-
- - name: Run `docker-compose up` again
- community.docker.docker_compose:
- project_src: flask
- build: false
- 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:
- project_src: flask
- build: false
- stopped: true
- register: output
-
- - name: Show results
- ansible.builtin.debug:
- var: output
-
- - name: Verify that web and db services are not running
- ansible.builtin.assert:
- that:
- - "not output.services.web.flask_web_1.state.running"
- - "not output.services.db.flask_db_1.state.running"
-
- - name: Restart services
- community.docker.docker_compose:
- project_src: flask
- build: false
- restarted: true
- register: output
-
- - name: Show results
- ansible.builtin.debug:
- var: output
-
- - name: Verify that web and db services are running
- ansible.builtin.assert:
- that:
- - "output.services.web.flask_web_1.state.running"
- - "output.services.db.flask_db_1.state.running"
-
-- name: Scale the web service to 2
- hosts: localhost
- gather_facts: false
- tasks:
- - name: Scale the web service to two instances
- community.docker.docker_compose:
- project_src: flask
- scale:
- web: 2
- register: output
-
- - name: Show results
- ansible.builtin.debug:
- var: output
-
-- name: Run with inline Compose file version 2
- # https://docs.docker.com/compose/compose-file/compose-file-v2/
- hosts: localhost
- gather_facts: false
- tasks:
- - name: Remove flask project
- community.docker.docker_compose:
- project_src: flask
- state: absent
-
- - name: Start flask project with inline definition
- 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
-
- - name: Show results
- ansible.builtin.debug:
- var: output
-
- - name: Verify that the db and web services are running
- ansible.builtin.assert:
- that:
- - "output.services.web.flask_web_1.state.running"
- - "output.services.db.flask_db_1.state.running"
-
-- name: Run with inline Compose file version 1
- # https://docs.docker.com/compose/compose-file/compose-file-v1/
- hosts: localhost
- gather_facts: false
- tasks:
- - name: Remove flask project
- community.docker.docker_compose:
- project_src: flask
- state: absent
-
- - name: Start flask project with inline definition
- 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
-
- - name: Show results
- ansible.builtin.debug:
- var: output
-
- - name: Verify that web and db services are running
- ansible.builtin.assert:
- that:
- - "output.services.web.flask_web_1.state.running"
- - "output.services.db.flask_db_1.state.running"
-Return Values
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Provides the actions to be taken on each service as determined by compose. -Returned: when in check mode or |
-
| - | Name of the service. -Returned: always - |
-
| - | A descriptive name of the action to be performed on the service’s containers. -Returned: always - |
-
| - | the container’s long ID -Returned: always - |
-
| - | the container’s name -Returned: always - |
-
| - | the container’s short ID -Returned: always - |
-
| - | Provides image details when a new image is built for the service. -Returned: on image build - |
-
| - | image hash -Returned: always - |
-
| - | name of the image -Returned: always - |
-
| - | Provides image details when a new image is pulled for the service. -Returned: on image pull - |
-
| - | image hash -Returned: always - |
-
| - | name of the image -Returned: always - |
-
| - | A dictionary mapping the service’s name to a dictionary of containers. -Returned: success - |
-
| - | Name of the container. Format is Returned: success - |
-
| - | One or more commands to be executed in the container. -Returned: success -Sample: |
-
| - | Name of the image from which the container was built. -Returned: success -Sample: |
-
| - | Meta data assigned to the container. -Returned: success -Sample: |
-
| - | Contains a dictionary for each network to which the container is a member. -Returned: success - |
-
| - | Aliases assigned to the container by the network. -Returned: success -Sample: |
-
| - | IPv6 address assigned to the container. -Returned: success -Sample: |
-
| - | IPv6 subnet length. -Returned: success -Sample: |
-
| - | The IP address assigned to the container. -Returned: success -Sample: |
-
| - | Number of bits used by the subnet. -Returned: success -Sample: |
-
| - | List of container names to which this container is linked. -Returned: success - |
-
| - | Mac Address assigned to the virtual NIC. -Returned: success -Sample: |
-
| - | Information regarding the current disposition of the container. -Returned: success - |
-
| - | Whether or not the container is up with a running process. -Returned: success -Sample: |
-
| - | Description of the running state. -Returned: success -Sample: |
-
Status
--
-
This module will be removed in version 4.0.0. -[deprecated]
-For more information see DEPRECATED.
-
Collection links
- -This module has been removed +in version 4.0.0 of community.docker. +This module uses docker-compose v1, which is End of Life since July 2022. Please migrate to community.docker.docker_compose_v2.