Try SpotterManage multi-container Docker applications with Docker Compose V1
Authors: Chris Houseknecht (@chouseknecht)
Install with ansible-galaxy collection install community.docker:==3.8.1
collections:
- name: community.docker
version: 3.8.1Uses Docker Compose to start, shutdown and scale services. B(This module requires docker-compose < 2.0.0.) Use the M(community.docker.docker_compose_v2) module for using the modern Docker compose CLI plugin.
Configuration can be read from a C(docker-compose.yml) or C(docker-compose.yaml) file or inline using the O(definition) option.
See the examples for more details.
Supports check mode.
This module was called C(docker_service) before Ansible 2.8. The usage did not change.
# 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"
tls:
default: false
description:
- Secure the connection to the API by using TLS without verifying the authenticity
of the Docker host server. Note that if O(validate_certs) is set to V(true) as well,
it will take precedence.
- If the value is not specified in the task, the value of environment variable E(DOCKER_TLS)
will be used instead. If the environment variable is not set, the default value
will be used.
type: bool
pull:
default: false
description:
- Use with O(state=present) to always pull images prior to starting the application.
- Same as running C(docker-compose pull).
- When a new image is pulled, services using the image will be recreated unless O(recreate=never).
type: bool
build:
default: false
description:
- Use with O(state=present) to always build images prior to starting the application.
- Same as running C(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 O(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
O(recreate=never).
type: bool
debug:
default: false
description:
- Debug mode
type: bool
files:
description:
- List of Compose file names relative to O(project_src). Overrides C(docker-compose.yml)
or C(docker-compose.yaml).
- Files are loaded and merged in the order given.
elements: path
type: list
scale:
description:
- When O(state) is V(present) scale services. Provide a dictionary of key/value pairs
where the key is the name of the service and the value is an integer count for the
number of containers.
type: dict
state:
choices:
- absent
- present
default: present
description:
- Desired state of the project.
- Specifying V(present) is the same as running C(docker-compose up) resp. C(docker-compose
stop) (with O(stopped=true)) resp. C(docker-compose restart) (with O(restarted=true)).
- Specifying V(absent) is the same as running C(docker-compose down).
type: str
ca_path:
aliases:
- ca_cert
- tls_ca_cert
- cacert_path
description:
- 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 E(DOCKER_CERT_PATH)
is set, the file C(ca.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
- This option was called O(ca_cert) and got renamed to O(ca_path) in community.docker
3.6.0. The old name has been added as an alias and can still be used.
type: path
nocache:
default: false
description:
- Use with the O(build) option to ignore the cache during the image build process.
type: bool
stopped:
default: false
description:
- Use with O(state=present) to stop all containers defined in the Compose file.
- If O(services) is defined, only the containers listed there will be stopped.
- Requires C(docker-compose) version 1.17.0 or greater for full support. For older
versions, the services will first be started and then stopped when the service is
supposed to be created as stopped.
type: bool
timeout:
default: null
description:
- Timeout in seconds for container shutdown when attached or when containers are already
running.
- By default C(docker-compose) will use a V(10) seconds timeout unless C(default_grace_period)
is defined for a particular service in the O(project_src).
type: int
env_file:
description:
- By default environment files are loaded from a C(.env) file located directly under
the O(project_src) directory.
- O(env_file) can be used to specify the path of a custom environment file instead.
- The path is relative to the O(project_src) directory.
- Requires C(docker-compose) version 1.25.0 or greater.
- 'Note: C(docker-compose) versions C(<=1.28) load the env file from the current working
directory of the C(docker-compose) command rather than O(project_src).'
type: path
version_added: 1.9.0
version_added_collection: community.docker
profiles:
description:
- List of profiles to enable when starting services.
- Equivalent to C(docker-compose --profile).
- Requires C(docker-compose) version 1.28.0 or greater.
elements: str
type: list
version_added: 1.8.0
version_added_collection: community.docker
recreate:
choices:
- always
- never
- smart
default: smart
description:
- By default containers will be recreated when their configuration differs from the
service definition.
- Setting to V(never) ignores configuration differences and leaves existing containers
unchanged.
- Setting to V(always) forces recreation of all existing containers.
type: str
services:
description:
- When O(state) is V(present) run C(docker-compose up) resp. C(docker-compose stop)
(with O(stopped=true)) resp. C(docker-compose restart) (with O(restarted=true))
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 O(definition)).
elements: str
type: list
restarted:
default: false
description:
- Use with O(state=present) to restart all containers defined in the Compose file.
- If O(services) is defined, only the containers listed there will be restarted.
type: bool
client_key:
aliases:
- tls_client_key
- key_path
description:
- Path to the client's TLS key file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
is set, the file C(key.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
type: path
definition:
description:
- Compose file describing one or more services, networks and volumes.
- Mutually exclusive with O(project_src) and O(files).
type: dict
api_version:
aliases:
- docker_api_version
default: auto
description:
- 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 E(DOCKER_API_VERSION)
will be used instead. If the environment variable is not set, the default value
will be used.
type: str
client_cert:
aliases:
- tls_client_cert
- cert_path
description:
- Path to the client's TLS certificate file.
- If the value is not specified in the task and the environment variable E(DOCKER_CERT_PATH)
is set, the file C(cert.pem) from the directory specified in the environment variable
E(DOCKER_CERT_PATH) will be used.
type: path
docker_host:
aliases:
- docker_url
default: unix:///var/run/docker.sock
description:
- 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, V(tcp://192.0.2.23:2376).
If TLS is used to encrypt the connection, the module will automatically replace
C(tcp) in the connection URL with C(https).
- If the value is not specified in the task, the value of environment variable E(DOCKER_HOST)
will be used instead. If the environment variable is not set, the default value
will be used.
type: str
project_src:
description:
- Path to a directory containing a C(docker-compose.yml) or C(docker-compose.yaml)
file.
- Mutually exclusive with O(definition).
- Required when no O(definition) is provided.
type: path
ssl_version:
description:
- Provide a valid SSL version number. Default value determined by L(SSL Python module,
https://docs.python.org/3/library/ssl.html).
- If the value is not specified in the task, the value of environment variable E(DOCKER_SSL_VERSION)
will be used instead.
- B(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.
type: str
dependencies:
default: true
description:
- When O(state) is V(present) specify whether or not to include linked services.
type: bool
project_name:
description:
- Provide a project name. If not provided, the project name is taken from the basename
of O(project_src).
- Required when O(definition) is provided.
type: str
tls_hostname:
description:
- 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 E(DOCKER_TLS_HOSTNAME)
will be used instead. If the environment variable is not set, the default value
will be used.
- Note that this option had a default value V(localhost) in older versions. It was
removed in community.docker 3.0.0.
- B(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.
type: str
remove_images:
choices:
- all
- local
description:
- Use with O(state=absent) to remove all images or only local images.
type: str
hostname_check:
default: false
description:
- Whether or not to check the Docker daemon's hostname against the name provided in
the client certificate.
type: bool
remove_orphans:
default: false
description:
- Remove containers for services not defined in the Compose file.
type: bool
remove_volumes:
default: false
description:
- Use with O(state=absent) to remove data volumes.
type: bool
use_ssh_client:
default: false
description:
- Currently ignored for this module, but might suddenly be supported later on.
type: bool
version_added: 1.5.0
version_added_collection: community.docker
validate_certs:
aliases:
- tls_verify
default: false
description:
- 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 E(DOCKER_TLS_VERIFY)
will be used instead. If the environment variable is not set, the default value
will be used.
type: bool
actions:
contains:
service_name:
contains:
action:
contains:
id:
description: the container's long ID
returned: always
type: str
name:
description: the container's name
returned: always
type: str
short_id:
description: the container's short ID
returned: always
type: str
description: A descriptive name of the action to be performed on the service's
containers.
elements: str
returned: always
type: list
built_image:
contains:
id:
description: image hash
returned: always
type: str
name:
description: name of the image
returned: always
type: str
description: Provides image details when a new image is built for the service.
returned: on image build
type: complex
pulled_image:
contains:
id:
description: image hash
returned: always
type: str
name:
description: name of the image
returned: always
type: str
description: Provides image details when a new image is pulled for the service.
returned: on image pull
type: complex
description: Name of the service.
returned: always
type: complex
description: Provides the actions to be taken on each service as determined by compose.
returned: when in check mode or O(debug=true)
type: complex
services:
contains:
container_name:
contains:
cmd:
description: One or more commands to be executed in the container.
elements: str
example:
- postgres
returned: success
type: list
image:
description: Name of the image from which the container was built.
example: postgres
returned: success
type: str
labels:
description: Meta data assigned to the container.
example:
'...': null
returned: success
type: dict
networks:
contains:
IPAddress:
description: The IP address assigned to the container.
example: 172.17.0.2
returned: success
type: str
IPPrefixLen:
description: Number of bits used by the subnet.
example: 16
returned: success
type: int
aliases:
description: Aliases assigned to the container by the network.
elements: str
example:
- db
returned: success
type: list
globalIPv6:
description: IPv6 address assigned to the container.
example: ''
returned: success
type: str
globalIPv6PrefixLen:
description: IPv6 subnet length.
example: 0
returned: success
type: int
links:
description: List of container names to which this container is linked.
elements: str
example: null
returned: success
type: list
macAddress:
description: Mac Address assigned to the virtual NIC.
example: 02:42:ac:11:00:02
returned: success
type: str
description: Contains a dictionary for each network to which the container
is a member.
elements: dict
returned: success
type: list
state:
contains:
running:
description: Whether or not the container is up with a running process.
example: true
returned: success
type: bool
status:
description: Description of the running state.
example: running
returned: success
type: str
description: Information regarding the current disposition of the container.
returned: success
type: dict
description: Name of the container. Format is C(project_service_#).
returned: success
type: complex
description:
- A dictionary mapping the service's name to a dictionary of containers.
returned: success
type: complex