Try SpotterManage docker services and containers.
| "added in version" 2.1 of ansible.builtin"
Authors: Chris Houseknecht (@chouseknecht)
preview | supported by community
pipInstall with pip install ansible==2.7.16
Consumes docker compose to start, shutdown and scale services.
Works with compose versions 1 and 2.
Compose can be read from a docker-compose.yml (or .yaml) file or inline using the C(definition) option.
See the examples for more details.
Supports check mode.
# Examples use the django example at U(https://docs.docker.com/compose/django/). Follow it to create the flask
# directory
- name: Run using a project directory
hosts: localhost
connection: local
gather_facts: no
tasks:
- docker_service:
project_src: flask
state: absent
- docker_service:
project_src: flask
register: output
- debug:
var: output
- docker_service:
project_src: flask
build: no
register: output
- debug:
var: output
- assert:
that: "not output.changed "
- docker_service:
project_src: flask
build: no
stopped: true
register: output
- debug:
var: output
- assert:
that:
- "not web.flask_web_1.state.running"
- "not db.flask_db_1.state.running"
- docker_service:
project_src: flask
build: no
restarted: true
register: output
- debug:
var: output
- assert:
that:
- "web.flask_web_1.state.running"
- "db.flask_db_1.state.running"
- name: Scale the web service to 2
hosts: localhost
connection: local
gather_facts: no
tasks:
- docker_service:
project_src: flask
scale:
web: 2
register: output
- debug:
var: output
- name: Run with inline v2 compose
hosts: localhost
connection: local
gather_facts: no
tasks:
- docker_service:
project_src: flask
state: absent
- docker_service:
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
- debug:
var: output
- assert:
that:
- "web.flask_web_1.state.running"
- "db.flask_db_1.state.running"
- name: Run with inline v1 compose
hosts: localhost
connection: local
gather_facts: no
tasks:
- docker_service:
project_src: flask
state: absent
- docker_service:
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
- debug:
var: output
- 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: 'no'
description:
- Use with state I(present) to always pull images prior to starting the application.
- Same as running docker-compose pull.
- When a new image is pulled, services using the image will be recreated unless C(recreate)
is I(never).
type: bool
version_added: '2.2'
version_added_collection: ansible.builtin
build:
default: 'no'
description:
- Use with state I(present) to always build images prior to starting the application.
- Same as running 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 C(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
C(recreate) is I(never).
type: bool
debug:
default: false
description:
- Debug mode
type: bool
files:
description:
- List of file names relative to C(project_src). Overrides docker-compose.yml or docker-compose.yaml.
- Files are loaded and merged in the order given.
scale:
description:
- When C(state) is I(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.
state:
choices:
- absent
- present
default: present
description:
- Desired state of the project.
- Specifying I(present) is the same as running I(docker-compose up).
- Specifying I(absent) is the same as running I(docker-compose down).
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: 'no'
description:
- Use with the build option to ignore the cache during the image build process.
type: bool
version_added: '2.2'
version_added_collection: ansible.builtin
stopped:
default: 'no'
description:
- Use with state I(present) to leave the containers in an exited or non-running state.
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 I(never) ignores configuration differences and leaves existing containers
unchanged.
- Setting to I(always) forces recreation of all existing containers.
required: false
services:
description:
- When C(state) is I(present) run I(docker-compose up) on a subset of services.
restarted:
default: 'no'
description:
- Use with state I(present) to restart all containers.
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:
- Provide docker-compose yaml describing one or more services, networks and volumes.
- Mutually exclusive with C(project_src) and C(files).
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 docker-compose.yml or docker-compose.yaml file.
- Mutually exclusive with C(definition).
- Required when no C(definition) is provided.
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: 'yes'
description:
- When C(state) is I(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 C(project_src).
- Required when C(definition) is provided.
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 C(DOCKER_TLS_HOSTNAME)
will be used instead. If the environment variable is not set, the default value
will be used.
- The current default value is C(localhost). This default is deprecated and will change
in community.docker 2.0.0 to be a value computed from I(docker_host). Explicitly
specify C(localhost) to make sure this value will still be used, and to disable
the deprecation message which will be shown otherwise.
type: str
remove_images:
choices:
- all
- local
description:
- Use with state I(absent) to remove the all images or only local images.
hostname_check:
default: 'no'
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: 'no'
description:
- Use with state I(absent) to remove data volumes.
type: bool
use_ssh_client:
default: false
description:
- For SSH transports, use the C(ssh) CLI tool instead of paramiko.
- Requires Docker SDK for Python 4.4.0 or newer.
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 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: string
name:
description: the container's name
returned: always
type: string
short_id:
description: the container's short ID
returned: always
type: string
description: A descriptive name of the action to be performed on the service's
containers.
returned: always
type: list
built_image:
contains:
id:
description: image hash
returned: always
type: string
name:
description: name of the image
returned: always
type: string
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: string
name:
description: name of the image
returned: always
type: string
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) true
type: complex
service:
contains:
container_name:
contains:
cmd:
description: One or more commands to be executed in the container.
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: complex
networks:
contains:
IPAddress:
description: The IP address assigned to the container.
example: 172.17.0.2
returned: success
type: string
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.
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.
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.
returned: success
type: complex
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: complex
description: Name of the container. Format is I(project_service_#).
returned: success
type: complex
description: Name of the service.
returned: success
type: complex