Try SpotterManage multi-container Docker applications with Docker Compose.
Authors: Chris Houseknecht (@chouseknecht)
Install with ansible-galaxy collection install community.general:==1.3.14
collections:
- name: community.general
version: 1.3.14Uses Docker Compose to start, shutdown and scale services.
Works with compose versions 1 and 2.
Configuration can be read from a C(docker-compose.yml) or C(docker-compose.yaml) file or inline using the I(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: 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"
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 I(validate_certs) is set to C(yes) as well,
it will take precedence.
- If the value is not specified in the task, the value of environment variable C(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 I(state) C(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 I(recreate)
is C(never).
type: bool
build:
default: false
description:
- Use with I(state) C(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 I(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
I(recreate) is C(never).
type: bool
debug:
default: false
description:
- Debug mode
type: bool
files:
description:
- List of Compose file names relative to I(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 I(state) is C(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 C(present) is the same as running C(docker-compose up) resp. C(docker-compose
stop) (with I(stopped)) resp. C(docker-compose restart) (with I(restarted)).
- Specifying C(absent) is the same as running C(docker-compose down).
type: str
ca_cert:
aliases:
- 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 C(DOCKER_CERT_PATH)
is set, the file C(ca.pem) from the directory specified in the environment variable
C(DOCKER_CERT_PATH) will be used.
type: path
nocache:
default: false
description:
- Use with the I(build) option to ignore the cache during the image build process.
type: bool
stopped:
default: false
description:
- Use with I(state) C(present) to stop all containers defined in the Compose file.
- If I(services) is defined, only the containers listed there will be stopped.
type: bool
timeout:
default: 10
description:
- timeout in seconds for container shutdown when attached or when containers are already
running.
type: int
recreate:
choices:
- always
- never
- smart
default: smart
description:
- By default containers will be recreated when their configuration differs from the
service definition.
- Setting to C(never) ignores configuration differences and leaves existing containers
unchanged.
- Setting to C(always) forces recreation of all existing containers.
type: str
services:
description:
- When I(state) is C(present) run C(docker-compose up) resp. C(docker-compose stop)
(with I(stopped)) resp. C(docker-compose restart) (with I(restarted)) 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 I(definition)).
elements: str
type: list
restarted:
default: false
description:
- Use with I(state) C(present) to restart all containers defined in the Compose file.
- If I(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 C(DOCKER_CERT_PATH)
is set, the file C(key.pem) from the directory specified in the environment variable
C(DOCKER_CERT_PATH) will be used.
type: path
definition:
description:
- Compose file describing one or more services, networks and volumes.
- Mutually exclusive with I(project_src) and I(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 C(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 C(DOCKER_CERT_PATH)
is set, the file C(cert.pem) from the directory specified in the environment variable
C(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, C(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 C(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 I(definition).
- Required when no I(definition) is provided.
type: path
ssl_version:
description:
- Provide a valid SSL version number. Default value determined by ssl.py module.
- If the value is not specified in the task, the value of environment variable C(DOCKER_SSL_VERSION)
will be used instead.
type: str
dependencies:
default: true
description:
- When I(state) is C(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 I(project_src).
- Required when I(definition) is provided.
type: str
tls_hostname:
default: localhost
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 C(DOCKER_TLS_HOSTNAME)
will be used instead. If the environment variable is not set, the default value
will be used.
type: str
remove_images:
choices:
- all
- local
description:
- Use with I(state) C(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 I(state) C(absent) to remove data volumes.
type: bool
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 C(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 I(debug) is C(yes)
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.
- Note that facts are part of the registered vars since Ansible 2.8. For compatibility
reasons, the facts are also accessible directly. The service's name is the variable
with which the container dictionary can be accessed. Note that the returned facts
will be removed in community.general 2.0.0.
returned: success
type: complex