Try SpotterManage multi-container Docker applications with Docker Compose CLI plugin
| "added in version" 3.6.0 of community.docker"
Authors: Felix Fontein (@felixfontein)
Install with ansible-galaxy collection install community.docker:==3.8.1
collections:
- name: community.docker
version: 3.8.1Uses Docker Compose to start or shutdown services.
# 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_v2:
project_src: flask
state: absent
- name: Create and start services
community.docker.docker_compose_v2:
project_src: flask
register: output
- name: Show results
ansible.builtin.debug:
var: output
- name: Run `docker-compose up` again
community.docker.docker_compose_v2:
project_src: flask
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_v2:
project_src: flask
state: stopped
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_v2:
project_src: flask
state: restarted
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:
choices:
- always
- missing
- never
- policy
default: policy
description:
- Whether to pull images before running. This is used when C(docker compose up) is
run.
- V(always) ensures that the images are always pulled, even when already present on
the Docker daemon.
- V(missing) only pulls them when they are not present on the Docker daemon.
- V(never) never pulls images. If they are not present, the module will fail when
trying to create the containers that need them.
- V(policy) use the Compose file's C(pull_policy) defined for the service to figure
out what to do.
type: str
wait:
default: false
description:
- When running C(docker compose up), pass C(--wait) to wait for services to be running/healthy.
- A timeout can be set with the O(wait_timeout) option.
type: bool
version_added: 3.8.0
version_added_collection: community.docker
build:
choices:
- always
- never
- policy
default: policy
description:
- Whether to build images before starting containers. This is used when C(docker compose
up) is run.
- V(always) always builds before starting containers. This is equivalent to the C(--build)
option of C(docker compose up).
- V(never) never builds before starting containers. This is equivalent to the C(--no-build)
option of C(docker compose up).
- V(policy) uses the policy as defined in the Compose file.
type: str
files:
description:
- List of Compose file names relative to O(project_src) to be used instead of the
main Compose file (C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)).
- Files are loaded and merged in the order given.
elements: path
type: list
version_added: 3.7.0
version_added_collection: community.docker
scale:
description:
- Define how to scale services when running C(docker compose up).
- 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
version_added: 3.7.0
version_added_collection: community.docker
state:
choices:
- absent
- stopped
- restarted
- present
default: present
description:
- Desired state of the project.
- V(present) is equivalent to running C(docker compose up).
- V(stopped) is equivalent to running C(docker compose stop).
- V(absent) is equivalent to running C(docker compose down).
- V(restarted) is equivalent to running C(docker compose restart).
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.
type: path
timeout:
description:
- Timeout in seconds for container shutdown when attached or when containers are already
running.
type: int
profiles:
description:
- List of profiles to enable when starting services.
- Equivalent to C(docker compose --profile).
elements: str
type: list
recreate:
choices:
- always
- never
- auto
default: auto
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:
- Specifies a subset of services to be targeted.
elements: str
type: list
env_files:
description:
- By default environment files are loaded from a C(.env) file located directly under
the O(project_src) directory.
- O(env_files) can be used to specify the path of one or multiple custom environment
files instead.
- The path is relative to the O(project_src) directory.
elements: path
type: list
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
docker_cli:
description:
- Path to the Docker CLI. If not provided, will search for Docker CLI on the E(PATH).
type: path
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 this collection 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
cli_context:
description:
- The Docker CLI context to use.
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 Compose file (C(compose.yml), C(compose.yaml),
C(docker-compose.yml), or C(docker-compose.yaml)).
- If O(files) is provided, will look for these files in this directory instead.
required: true
type: path
dependencies:
default: true
description:
- When O(state) is V(present) or V(restarted), 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).
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.
type: str
wait_timeout:
description:
- When O(wait=true), wait at most this amount of seconds.
type: int
version_added: 3.8.0
version_added_collection: community.docker
remove_images:
choices:
- all
- local
description:
- Use with O(state=absent) to remove all images or only local images.
type: str
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
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:
id:
description:
- The ID of the resource that was changed.
sample: container
type: str
status:
choices:
- Starting
- Exiting
- Restarting
- Creating
- Stopping
- Killing
- Removing
- Recreating
- Pulling
- Building
description:
- The status change that happened.
sample: Creating
type: str
what:
choices:
- container
- image
- network
- service
- unknown
- volume
description:
- What kind of resource was changed.
sample: container
type: str
description:
- A list of actions that have been applied.
elements: dict
returned: success
type: list
containers:
contains:
Command:
description:
- The container's command.
type: raw
CreatedAt:
description:
- The timestamp when the container was created.
sample: 2024-01-02 12:20:41 +0100 CET
type: str
ExitCode:
description:
- The container's exit code.
type: int
Health:
description:
- The container's health check.
type: raw
ID:
description:
- The container's ID.
sample: 44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135
type: str
Image:
description:
- The container's image.
type: str
Labels:
description:
- Labels for this container.
type: dict
LocalVolumes:
description:
- The local volumes count.
type: str
Mounts:
description:
- Mounts.
type: str
Name:
description:
- The container's primary name.
type: str
Names:
description:
- List of names of the container.
elements: str
type: list
Networks:
description:
- List of networks attached to this container.
elements: str
type: list
Ports:
description:
- List of port assignments as a string.
type: str
Publishers:
contains:
Protocol:
choices:
- tcp
- udp
description:
- The protocol.
type: str
PublishedPort:
description:
- The port that is published.
type: int
TargetPort:
description:
- The container's port the published port maps to.
type: int
URL:
description:
- Interface the port is bound to.
type: str
description:
- List of port assigments.
elements: dict
type: list
RunningFor:
description:
- Amount of time the container runs.
type: str
Service:
description:
- The name of the service.
type: str
Size:
description:
- The container's size.
sample: 0B
type: str
State:
description:
- The container's state.
sample: running
type: str
Status:
description:
- The container's status.
sample: Up About a minute
type: str
description:
- A list of containers associated to the service.
elements: dict
returned: success
type: list
images:
contains:
ContainerName:
description:
- Name of the conainer this image is used by.
type: str
ID:
description:
- The image's ID.
sample: sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1
type: str
Repository:
description:
- The repository where this image belongs to.
type: str
Size:
description:
- The image's size in bytes.
type: int
Tag:
description:
- The tag of the image.
type: str
description:
- A list of images associated to the service.
elements: dict
returned: success
type: list