docker_swarm_service – docker swarm service
docker_swarm_service – docker swarm service
New in version 2.7.
Synopsis
- Manages docker services via a swarm manager node.
Requirements
The below requirements are needed on the host that executes this module.
- Docker API >= 1.24
- 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 | Choices/Defaults | Comments | ||
---|---|---|---|---|
api_version string |
Default: "auto" |
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
| ||
args list |
List arguments to be passed to the container. Corresponds to the | |||
ca_cert path |
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
| |||
client_cert path |
Path to the client's TLS certificate file. If the value is not specified in the task and the environment variable
| |||
client_key path |
Path to the client's TLS key file. If the value is not specified in the task and the environment variable
| |||
command raw added in 2.8 |
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 | |||
configs list |
List of dictionaries describing the service configs. Corresponds to the Requires API version >= 1.30. | |||
config_id string / required |
Config's ID. | |||
config_name string / required |
Config's name as defined at its creation. | |||
filename string / required |
Name of the file containing the config. Defaults to the config_name if not specified. | |||
gid string |
GID of the config file's group. | |||
mode integer |
File access mode inside the container. Must be an octal number (like | |||
uid string |
UID of the config file's owner. | |||
constraints list |
List of the service constraints. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
container_labels dictionary |
Dictionary of key value pairs. Corresponds to the | |||
debug boolean |
|
Debug mode | ||
dns list |
List of custom DNS servers. Corresponds to the Requires API version >= 1.25. | |||
dns_options list |
List of custom DNS options. Corresponds to the Requires API version >= 1.25. | |||
dns_search list |
List of custom DNS search domains. Corresponds to the Requires API version >= 1.25. | |||
docker_host string |
Default: "unix://var/run/docker.sock" |
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
| ||
endpoint_mode string |
|
Service endpoint mode. Corresponds to the Requires API version >= 1.25. | ||
env raw |
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 (e.g. Corresponds to the | |||
env_files list added in 2.8 |
List of paths to files, present on the target, containing environment variables The order of the list is significant in determining the value assigned to a variable that shows up more than once. If variable also present in env, then env value will override. | |||
force_update boolean |
|
Force update even if no changes require it. Corresponds to the Requires API version >= 1.25. | ||
groups list added in 2.8 |
List of additional group names and/or IDs that the container process will run as. Corresponds to the Requires API version >= 1.25. | |||
healthcheck dictionary added in 2.8 |
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. interval, timeout and start_period are specified as durations. They accept duration as a string in a format that look like: Requires API version >= 1.25. | |||
interval string |
Time between running the check. | |||
retries integer |
Consecutive failures needed to report unhealthy. It accept integer value. | |||
start_period string |
Start period for the container to initialize before starting health-retries countdown. | |||
test raw |
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 | |||
timeout string |
Maximum time to allow one check to run. | |||
hostname string |
Container hostname. Corresponds to the Requires API version >= 1.25. | |||
hosts dictionary added in 2.8 |
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 Requires API version >= 1.25. | |||
image string / required |
Service image path and tag. Corresponds to the | |||
labels dictionary |
Dictionary of key value pairs. Corresponds to the | |||
limit_cpu float |
Service CPU limit. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
limit_memory string |
Service memory limit in format
Omitting the unit defaults to bytes. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
limits dictionary added in 2.8 |
Configures service resource limits. | |||
cpus float |
Service CPU limit. Corresponds to the | |||
memory string |
Service memory limit in format
Omitting the unit defaults to bytes. Corresponds to the | |||
log_driver string |
Configure the logging driver for a service. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
log_driver_options dictionary |
Options for service logging driver. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
logging dictionary added in 2.8 |
Logging configuration for the service. | |||
driver string |
Configure the logging driver for a service. Corresponds to the | |||
options dictionary |
Options for service logging driver. Corresponds to the | |||
mode string |
|
Service replication mode. Service will be removed and recreated when changed. Corresponds to the | ||
mounts list |
List of dictionaries describing the service mounts. Corresponds to the | |||
driver_config dictionary added in 2.8 |
Volume driver configuration. Can only be used when mode is | |||
name string |
Name of the volume-driver plugin to use for the volume. | |||
options dictionary |
Options as key-value pairs to pass to the driver for this volume. | |||
labels dictionary added in 2.8 |
Volume labels to apply. | |||
no_copy boolean added in 2.8 |
|
Disable copying of data from a container when a volume is created. Can only be used when mode is | ||
propagation string added in 2.8 |
|
The propagation mode to use. Can only be used when mode is | ||
readonly boolean |
|
Whether the mount should be read-only. | ||
source string |
Mount source (e.g. a volume name or a host path). Must be specified if type is not | |||
target string / required |
Container path. | |||
tmpfs_mode integer added in 2.8 |
File mode of the tmpfs in octal. Can only be used when mode is | |||
tmpfs_size string added in 2.8 |
Size of the tmpfs mount in format Can only be used when mode is | |||
type string |
|
The mount type. | ||
name string / required |
Service name. Corresponds to the | |||
networks list |
List of the service networks names. 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 | |||
placement dictionary added in 2.8 |
Configures service placement preferences and constraints. | |||
constraints list |
List of the service constraints. Corresponds to the | |||
preferences list |
List of the placement preferences as key value pairs. Corresponds to the Requires API version >= 1.27. | |||
publish list |
List of dictionaries describing the service published ports. Corresponds to the Requires API version >= 1.25. | |||
mode string |
|
What publish mode to use. Requires API version >= 1.32. | ||
protocol string |
|
What protocol to use. | ||
published_port integer / required |
The port to make externally available. | |||
target_port integer / required |
The port inside the container to expose. | |||
read_only boolean added in 2.8 |
|
Mount the containers root filesystem as read only. Corresponds to the | ||
replicas integer |
Default: -1 |
Number of containers instantiated in the service. Valid only if mode is If set to If set to Corresponds to the | ||
reservations dictionary added in 2.8 |
Configures service resource reservations. | |||
cpus float |
Service CPU reservation. Corresponds to the | |||
memory string |
Service memory reservation in format
Omitting the unit defaults to bytes. Corresponds to the | |||
reserve_cpu float |
Service CPU reservation. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
reserve_memory string |
Service memory reservation in format
Omitting the unit defaults to bytes. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
resolve_image boolean added in 2.8 |
|
If the current image digest should be resolved from registry and updated if changed. Requires API version >= 1.30. | ||
restart_config dictionary added in 2.8 |
Configures if and how to restart containers when they exit. | |||
condition string |
|
Restart condition of the service. Corresponds to the | ||
delay string |
Delay between restarts. Accepts a a string in a format that look like: Corresponds to the | |||
max_attempts integer |
Maximum number of service restarts. Corresponds to the | |||
window string |
Restart policy evaluation window. Accepts a string in a format that look like: Corresponds to the | |||
restart_policy string |
|
Restart condition of the service. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | ||
restart_policy_attempts integer |
Maximum number of service restarts. Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
restart_policy_delay raw |
Delay between restarts. Accepts a duration as an integer in nanoseconds or as a string in a format that look like: Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
restart_policy_window raw |
Restart policy evaluation window. Accepts a duration as an integer in nanoseconds or as a string in a format that look like: Corresponds to the Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
rollback_config dictionary added in 2.8 |
Configures how the service should be rolled back in case of a failing update. | |||
delay string |
Delay between task rollbacks. Accepts a string in a format that look like: Corresponds to the Requires API version >= 1.28. | |||
failure_action string |
|
Action to take in case of rollback failure. Corresponds to the Requires API version >= 1.28. | ||
max_failure_ratio float |
Fraction of tasks that may fail during a rollback. Corresponds to the Requires API version >= 1.28. | |||
monitor string |
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. | |||
order string |
|
Specifies the order of operations during rollbacks. Corresponds to the Requires API version >= 1.29. | ||
parallelism integer |
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. | |||
secrets list |
List of dictionaries describing the service secrets. Corresponds to the Requires API version >= 1.25. | |||
filename string |
Name of the file containing the secret. Defaults to the secret_name if not specified. Corresponds to the | |||
gid string |
GID of the secret file's group. | |||
mode integer |
File access mode inside the container. Must be an octal number (like | |||
secret_id string / required |
Secret's ID. | |||
secret_name string / required |
Secret's name as defined at its creation. | |||
uid string |
UID of the secret file's owner. | |||
ssl_version string |
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 | |||
state string / required |
|
| ||
stop_grace_period string added in 2.8 |
Time to wait before force killing a container. Accepts a duration as a string in a format that look like: Corresponds to the | |||
stop_signal string added in 2.8 |
Override default signal used to stop the container. Corresponds to the | |||
timeout integer |
Default: 60 |
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 | ||
tls boolean |
|
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if validate_certs is set to If the value is not specified in the task, the value of environment variable | ||
tls_hostname string |
Default: "localhost" |
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 | ||
tty boolean |
|
Allocate a pseudo-TTY. Corresponds to the Requires API version >= 1.25. | ||
update_config dictionary added in 2.8 |
Configures how the service should be updated. Useful for configuring rolling updates. | |||
delay string |
Rolling update delay. Accepts a string in a format that look like: Corresponds to the | |||
failure_action string |
|
Action to take in case of container failure. Corresponds to the Usage of rollback requires API version >= 1.29. | ||
max_failure_ratio float |
Fraction of tasks that may fail during an update before the failure action is invoked. Corresponds to the Requires API version >= 1.25. | |||
monitor string |
Time to monitor updated tasks for failures. Accepts a string in a format that look like: Corresponds to the Requires API version >= 1.25. | |||
order string |
|
Specifies the order of operations when rolling out an updated task. Corresponds to the Requires API version >= 1.29. | ||
parallelism integer |
Rolling update parallelism. Corresponds to the | |||
update_delay raw |
Rolling update delay. Accepts a duration as an integer in nanoseconds or as a string in a format that look like: Corresponds to the Before Ansible 2.8, the default value for this option was Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
update_failure_action string |
|
Action to take in case of container failure. Corresponds to the Usage of rollback requires API version >= 1.29. Deprecated in 2.8, will be removed in 2.12. Use parameter | ||
update_max_failure_ratio float |
Fraction of tasks that may fail during an update before the failure action is invoked. Corresponds to the Requires API version >= 1.25. Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
update_monitor raw |
Time to monitor updated tasks for failures. Accepts a duration as an integer in nanoseconds or as a string in a format that look like: Corresponds to the Requires API version >= 1.25. Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
update_order string |
|
Specifies the order of operations when rolling out an updated task. Corresponds to the Requires API version >= 1.29. Deprecated in 2.8, will be removed in 2.12. Use parameter | ||
update_parallelism integer |
Rolling update parallelism. Corresponds to the Before Ansible 2.8, the default value for this option was Deprecated in 2.8, will be removed in 2.12. Use parameter | |||
user string |
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 | |||
validate_certs boolean |
|
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
| ||
working_dir string added in 2.8 |
Path to the working directory. Corresponds to the |
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: true
to 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_SSL_VERSION
,DOCKER_TLS
,DOCKER_TLS_VERIFY
andDOCKER_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://docker-py.readthedocs.io/en/stable/machine/ 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 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.json
if theDOCKER_CONFIG
environment variable is not specified, and use$DOCKER_CONFIG/config.json
otherwise.
Examples
- name: Set command and arguments
docker_swarm_service:
name: myservice
image: alpine
command: sleep
args:
- "3600"
- name: Set a bind mount
docker_swarm_service:
name: myservice
image: alpine
mounts:
- source: /tmp/
target: /remote_tmp/
type: bind
- name: Set service labels
docker_swarm_service:
name: myservice
image: alpine
labels:
com.example.description: "Accounting webapp"
com.example.department: "Finance"
- name: Set environment variables
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
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
docker_swarm_service:
name: myservice
image: alpine
restart_config:
condition: on-failure
delay: 5s
max_attempts: 3
window: 120s
- name: Set update config
docker_swarm_service:
name: myservice
image: alpine
update_config:
parallelism: 2
delay: 10s
order: stop-first
- name: Set rollback config
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
docker_swarm_service:
name: myservice
image: alpine:edge
placement:
preferences:
- spread: node.labels.mylabel
constraints:
- node.role == manager
- engine.labels.operatingsystem == ubuntu 14.04
- name: Set configs
docker_swarm_service:
name: myservice
image: alpine:edge
configs:
- config_id: myconfig_id
config_name: myconfig_name
filename: "/tmp/config.txt"
- name: Set networks
docker_swarm_service:
name: myservice
image: alpine:edge
networks:
- mynetwork
- name: Set secrets
docker_swarm_service:
name: myservice
image: alpine:edge
secrets:
- secret_id: mysecret_id
secret_name: mysecret_name
filename: "/run/secrets/secret.txt"
- name: Start service with healthcheck
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
docker_swarm_service:
name: myservice
image: alpine:edge
reservations:
cpus: 0.25
memory: 20M
limits:
cpus: 0.50
memory: 50M
- name: Remove service
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 | Returned | Description |
---|---|---|
changes list |
always |
List of changed service attributes if a service has been altered, [] otherwise.
Sample: ['container_labels', 'replicas'] |
rebuilt boolean |
always |
True if the service has been recreated (removed and created)
Sample: True |
swarm_service dictionary |
always |
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
Sample: { "args": [ "3600" ], "command": [ "sleep" ], "configs": null, "constraints": [ "node.role == manager", "engine.labels.operatingsystem == ubuntu 14.04" ], "container_labels": null, "dns": null, "dns_options": null, "dns_search": null, "endpoint_mode": null, "env": [ "ENVVAR1=envvar1", "ENVVAR2=envvar2" ], "force_update": null, "groups": null, "healthcheck": { "interval": 90000000000, "retries": 3, "start_period": 30000000000, "test": [ "CMD", "curl", "--fail", "http://nginx.host.com%22 ], "timeout": 10000000000 }, "healthcheck_disabled": false, "hostname": null, "hosts": null, "image": "alpine:latest@sha256:b3dbf31b77fd99d9c08f780ce6f5282aba076d70a513a8be859d8d3a4d0c92b8", "labels": { "com.example.department": "Finance", "com.example.description": "Accounting webapp" }, "limit_cpu": 0.5, "limit_memory": 52428800, "log_driver": "fluentd", "log_driver_options": { "fluentd-address": "127.0.0.1:24224", "fluentd-async-connect": "true", "tag": "myservice" }, "mode": "replicated", "mounts": [ { "readonly": false, "source": "/tmp/", "target": "/remote_tmp/", "type": "bind", "labels": null, "propagation": null, "no_copy": null, "driver_config": null, "tmpfs_size": null, "tmpfs_mode": null } ], "networks": null, "placement_preferences": [ { "spread": "node.labels.mylabel" } ], "publish": null, "read_only": null, "replicas": 1, "reserve_cpu": 0.25, "reserve_memory": 20971520, "restart_policy": "on-failure", "restart_policy_attempts": 3, "restart_policy_delay": 5000000000, "restart_policy_window": 120000000000, "secrets": null, "stop_grace_period": null, "stop_signal": null, "tty": null, "update_delay": 10000000000, "update_failure_action": null, "update_max_failure_ratio": null, "update_monitor": null, "update_order": "stop-first", "update_parallelism": 2, "user": null, "working_dir": null } |
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Dario Zanzico (@dariko)
- Jason Witkowski (@jwitko)
- Hannes Ljungberg (@hannseman)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/docker_swarm_service_module.html