community.docker.docker_swarm_service module – docker swarm service
Note
This module is part of the community.docker collection (version 4.2.0).
You might already have this collection installed if you are using the ansible package.
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_swarm_service.
Synopsis
Manages docker services via a swarm manager node.
This modules does not support updating services in a stack.
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). This module does *not* work with docker-py.
Docker SDK for Python >= 2.0.2
Python >= 2.7
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: |
|
List arguments to be passed to the container. Corresponds to the |
|
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 |
|
List of capabilities to add to the container. Requires API version >= 1.41. |
|
List of capabilities to drop from the container. Requires API version >= 1.41. |
|
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 |
|
Command to execute when the container starts. A command may be either a string or a list or a list of strings. Corresponds to the |
|
List of dictionaries describing the service configs. Corresponds to the Requires API version >= 1.30. |
|
Config’s ID. |
|
Config’s name as defined at its creation. |
|
Name of the file containing the config. Defaults to the |
|
GID of the config file’s group. |
|
File access mode inside the container. Must be an octal number (like |
|
UID of the config file’s owner. |
|
Dictionary of key value pairs. Corresponds to the |
|
Debug mode Choices:
|
|
List of custom DNS servers. Corresponds to the |
|
List of custom DNS options. Corresponds to the |
|
List of custom DNS search domains. Corresponds to the |
|
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: |
|
Service endpoint mode. Corresponds to the Choices:
|
|
List or dictionary of the service environment variables. If passed a list each items need to be in the format of If passed a dictionary values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example Corresponds to the |
|
Force update even if no changes require it. Corresponds to the Choices:
|
|
List of additional group names and/or IDs that the container process will run as. Corresponds to the |
|
Configure a check that is run to determine whether or not containers for this service are “healthy”. See the docs for the HEALTHCHECK Dockerfile instruction for details on how healthchecks work.
|
|
Time between running the check. |
|
Consecutive failures needed to report unhealthy. It accept integer value. |
|
Start period for the container to initialize before starting health-retries countdown. |
|
Command to run to check health. Must be either a string or a list. If it is a list, the first item must be one of |
|
Maximum time to allow one check to run. |
|
Container hostname. Corresponds to the |
|
Dict of host-to-IP mappings, where each host name is a key in the dictionary. Each host name will be added to the container’s /etc/hosts file. Corresponds to the |
|
Service image path and tag. Corresponds to the |
|
Use an init inside each service container to forward signals and reap processes. Corresponds to the Requires API version >= 1.37. Choices:
|
|
Dictionary of key value pairs. Corresponds to the |
|
Configures service resource limits. |
|
Service CPU limit. Corresponds to the |
|
Service memory limit in format
Omitting the unit defaults to bytes. Corresponds to the |
|
Logging configuration for the service. |
|
Configure the logging driver for a service. Corresponds to the |
|
Options for service logging driver. Corresponds to the |
|
Service replication mode. Service will be removed and recreated when changed. Corresponds to the Choices:
|
|
List of dictionaries describing the service mounts. Corresponds to the |
|
Volume driver configuration. Can only be used when |
|
Name of the volume-driver plugin to use for the volume. |
|
Options as key-value pairs to pass to the driver for this volume. |
|
Volume labels to apply. |
|
Disable copying of data from a container when a volume is created. Can only be used when Choices:
|
|
The propagation mode to use. Can only be used when Choices:
|
|
Whether the mount should be read-only. Choices:
|
|
Mount source (for example a volume name or a host path). Must be specified if |
|
Container path. |
|
File mode of the tmpfs in octal. Can only be used when |
|
Size of the tmpfs mount in format Can only be used when |
|
The mount type. Note that Choices:
|
|
Service name. Corresponds to the |
|
List of the service networks names or dictionaries. When passed dictionaries valid sub-options are Prior to API version 1.29, updating and removing networks is not supported. If changes are made the service will then be removed and recreated. Corresponds to the |
|
Configures service placement preferences and constraints. |
|
List of the service constraints. Corresponds to the |
|
List of the placement preferences as key value pairs. Corresponds to the Requires API version >= 1.27. |
|
Maximum number of tasks per node. Corresponds to the Requires API version >= 1.40 |
|
List of dictionaries describing the service published ports. Corresponds to the |
|
What publish mode to use. Requires API version >= 1.32. Choices:
|
|
What protocol to use. Choices:
|
|
The port to make externally available. |
|
The port inside the container to expose. |
|
Mount the containers root filesystem as read only. Corresponds to the Choices:
|
|
Number of containers instantiated in the service. Valid only if If set to If set to Corresponds to the Default: |
|
Configures service resource reservations. |
|
Service CPU reservation. Corresponds to the |
|
Service memory reservation in format
Omitting the unit defaults to bytes. Corresponds to the |
|
If the current image digest should be resolved from registry and updated if changed. Requires API version >= 1.30. Choices:
|
|
Configures if and how to restart containers when they exit. |
|
Restart condition of the service. Corresponds to the Choices:
|
|
Delay between restarts. Accepts a a string in a format that look like: Corresponds to the |
|
Maximum number of service restarts. Corresponds to the |
|
Restart policy evaluation window. Accepts a string in a format that look like: Corresponds to the |
|
Configures how the service should be rolled back in case of a failing update. |
|
Delay between task rollbacks. Accepts a string in a format that look like: Corresponds to the Requires API version >= 1.28. |
|
Action to take in case of rollback failure. Corresponds to the Requires API version >= 1.28. Choices:
|
|
Fraction of tasks that may fail during a rollback. Corresponds to the Requires API version >= 1.28. |
|
Duration after each task rollback to monitor for failure. Accepts a string in a format that look like: Corresponds to the Requires API version >= 1.28. |
|
Specifies the order of operations during rollbacks. Corresponds to the Requires API version >= 1.29. |
|
The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously. Corresponds to the Requires API version >= 1.28. |
|
List of dictionaries describing the service secrets. Corresponds to the |
|
Name of the file containing the secret. Defaults to the Corresponds to the |
|
GID of the secret file’s group. |
|
File access mode inside the container. Must be an octal number (like |
|
Secret’s ID. |
|
Secret’s name as defined at its creation. |
|
UID of the secret file’s owner. |
|
Choices:
|
|
Time to wait before force killing a container. Accepts a duration as a string in a format that look like: Corresponds to the |
|
Override default signal used to stop the container. Corresponds to the |
|
Dictionary of key, value pairs. |
|
The maximum amount of time in seconds to wait on a response from the API. If the value is not specified in the task, the value of environment variable 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. |
|
Allocate a pseudo-TTY. Corresponds to the Choices:
|
|
Configures how the service should be updated. Useful for configuring rolling updates. |
|
Rolling update delay. Accepts a string in a format that look like: Corresponds to the |
|
Action to take in case of container failure. Corresponds to the Usage of Choices:
|
|
Fraction of tasks that may fail during an update before the failure action is invoked. Corresponds to the |
|
Time to monitor updated tasks for failures. Accepts a string in a format that look like: Corresponds to the |
|
Specifies the order of operations when rolling out an updated task. Corresponds to the Requires API version >= 1.29. |
|
Rolling update parallelism. Corresponds to the |
|
For SSH transports, use the Requires Docker SDK for Python 4.4.0 or newer. Choices:
|
|
Sets the username or UID used for the specified command. Before Ansible 2.8, the default value for this option was The default has been removed so that the user defined in the image is used if no user is specified here. Corresponds to the |
|
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:
|
|
Path to the working directory. Corresponds to the |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Action groups: community.docker.docker, docker |
Use |
|
Support: full |
Can run in |
|
Support: full |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
Images will only resolve to the latest digest when using Docker API >= 1.30 and Docker SDK for Python >= 3.2.0. When using older versions use
force_update=trueto trigger the swarm to resolve a new image.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_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.
Examples
- name: Set command and arguments
community.docker.docker_swarm_service:
name: myservice
image: alpine
command: sleep
args:
- "3600"
- name: Set a bind mount
community.docker.docker_swarm_service:
name: myservice
image: alpine
mounts:
- source: /tmp/
target: /remote_tmp/
type: bind
- name: Set service labels
community.docker.docker_swarm_service:
name: myservice
image: alpine
labels:
com.example.description: "Accounting webapp"
com.example.department: "Finance"
- name: Set environment variables
community.docker.docker_swarm_service:
name: myservice
image: alpine
env:
ENVVAR1: envvar1
ENVVAR2: envvar2
env_files:
- envs/common.env
- envs/apps/web.env
- name: Set fluentd logging
community.docker.docker_swarm_service:
name: myservice
image: alpine
logging:
driver: fluentd
options:
fluentd-address: "127.0.0.1:24224"
fluentd-async-connect: "true"
tag: myservice
- name: Set restart policies
community.docker.docker_swarm_service:
name: myservice
image: alpine
restart_config:
condition: on-failure
delay: 5s
max_attempts: 3
window: 120s
- name: Set update config
community.docker.docker_swarm_service:
name: myservice
image: alpine
update_config:
parallelism: 2
delay: 10s
order: stop-first
- name: Set rollback config
community.docker.docker_swarm_service:
name: myservice
image: alpine
update_config:
failure_action: rollback
rollback_config:
parallelism: 2
delay: 10s
order: stop-first
- name: Set placement preferences
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
placement:
preferences:
- spread: node.labels.mylabel
constraints:
- node.role == manager
- engine.labels.operatingsystem == ubuntu 14.04
replicas_max_per_node: 2
- name: Set configs
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
configs:
- config_name: myconfig_name
filename: "/tmp/config.txt"
- name: Set networks
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
networks:
- mynetwork
- name: Set networks as a dictionary
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
networks:
- name: "mynetwork"
aliases:
- "mynetwork_alias"
options:
foo: bar
- name: Set secrets
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
secrets:
- secret_name: mysecret_name
filename: "/run/secrets/secret.txt"
- name: Start service with healthcheck
community.docker.docker_swarm_service:
name: myservice
image: nginx:1.13
healthcheck:
# Check if nginx server is healthy by curl'ing the server.
# If this fails or timeouts, the healthcheck fails.
test: ["CMD", "curl", "--fail", "http://nginx.host.com"]
interval: 1m30s
timeout: 10s
retries: 3
start_period: 30s
- name: Configure service resources
community.docker.docker_swarm_service:
name: myservice
image: alpine:edge
reservations:
cpus: 0.25
memory: 20M
limits:
cpus: 0.50
memory: 50M
- name: Remove service
community.docker.docker_swarm_service:
name: myservice
state: absent
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
List of changed service attributes if a service has been altered, [] otherwise. Returned: always Sample: |
|
True if the service has been recreated (removed and created) Returned: always Sample: |
|
Dictionary of variables representing the current state of the service. Matches the module parameters format. Note that facts are not part of registered vars but accessible directly. Note that before Ansible 2.7.9, the return variable was documented as Returned: always Sample: |