community.docker.docker_swarm_service – docker swarm service¶

Note

This plugin is part of the community.docker collection (version 1.2.2).

To install it use: ansible-galaxy collection install community.docker.

To use it in a playbook, specify: community.docker.docker_swarm_service.

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

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 `DOCKER_API_VERSION` will be used instead. If the environment variable is not set, the default value will be used. aliases: docker_api_version
args list / elements=string				List arguments to be passed to the container. Corresponds to the `ARG` parameter of `docker service create`.
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 `DOCKER_CERT_PATH` is set, the file `ca.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used. aliases: tls_ca_cert, cacert_path
client_cert path				Path to the client's TLS certificate file. If the value is not specified in the task and the environment variable `DOCKER_CERT_PATH` is set, the file `cert.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used. aliases: tls_client_cert, cert_path
client_key path				Path to the client's TLS key file. If the value is not specified in the task and the environment variable `DOCKER_CERT_PATH` is set, the file `key.pem` from the directory specified in the environment variable `DOCKER_CERT_PATH` will be used. aliases: tls_client_key, key_path
command raw				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 `COMMAND` parameter of `docker service create`.
configs list / elements=dictionary				List of dictionaries describing the service configs. Corresponds to the `--config` option of `docker service create`. Requires API version >= 1.30.
	config_id string			Config's ID.
	config_name string / required			Config's name as defined at its creation.
	filename string			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 `0644` or `0444`).
	uid string			UID of the config file's owner.
container_labels dictionary				Dictionary of key value pairs. Corresponds to the `--container-label` option of `docker service create`.
debug boolean			Choices: no ← yes	Debug mode
dns list / elements=string				List of custom DNS servers. Corresponds to the `--dns` option of `docker service create`. Requires API version >= 1.25.
dns_options list / elements=string				List of custom DNS options. Corresponds to the `--dns-option` option of `docker service create`. Requires API version >= 1.25.
dns_search list / elements=string				List of custom DNS search domains. Corresponds to the `--dns-search` option of `docker service create`. 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, `tcp://192.0.2.23:2376`. If TLS is used to encrypt the connection, the module will automatically replace `tcp` in the connection URL with `https`. If the value is not specified in the task, the value of environment variable `DOCKER_HOST` will be used instead. If the environment variable is not set, the default value will be used. aliases: docker_url
endpoint_mode string			Choices: vip dnsrr	Service endpoint mode. Corresponds to the `--endpoint-mode` option of `docker service create`. 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 `KEY=VALUE`. If passed a dictionary values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (e.g. `"true"`) in order to avoid data loss. Corresponds to the `--env` option of `docker service create`.
env_files list / elements=path				List of paths to files, present on the target, containing environment variables `FOO=BAR`. 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			Choices: no ← yes	Force update even if no changes require it. Corresponds to the `--force` option of `docker service update`. Requires API version >= 1.25.
groups list / elements=string				List of additional group names and/or IDs that the container process will run as. Corresponds to the `--group` option of `docker service update`. Requires API version >= 1.25.
healthcheck dictionary				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: `5h34m56s`, `1m30s` etc. The supported units are `us`, `ms`, `s`, `m` and `h`. 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 `NONE`, `CMD` or `CMD-SHELL`.
	timeout string			Maximum time to allow one check to run.
hostname string				Container hostname. Corresponds to the `--hostname` option of `docker service create`. Requires API version >= 1.25.
hosts dictionary				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 `--host` option of `docker service create`. Requires API version >= 1.25.
image string				Service image path and tag. Corresponds to the `IMAGE` parameter of `docker service create`.
init boolean			Choices: no yes	Use an init inside each service container to forward signals and reap processes. Corresponds to the `--init` option of `docker service create`. Requires API version >= 1.37.
labels dictionary				Dictionary of key value pairs. Corresponds to the `--label` option of `docker service create`.
limits dictionary				Configures service resource limits.
	cpus float			Service CPU limit. `0` equals no limit. Corresponds to the `--limit-cpu` option of `docker service create`.
	memory string			Service memory limit in format `<number>[<unit>]`. Number is a positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). `0` equals no limit. Omitting the unit defaults to bytes. Corresponds to the `--limit-memory` option of `docker service create`.
logging dictionary				Logging configuration for the service.
	driver string			Configure the logging driver for a service. Corresponds to the `--log-driver` option of `docker service create`.
	options dictionary			Options for service logging driver. Corresponds to the `--log-opt` option of `docker service create`.
mode string			Choices: replicated ← global	Service replication mode. Service will be removed and recreated when changed. Corresponds to the `--mode` option of `docker service create`.
mounts list / elements=dictionary				List of dictionaries describing the service mounts. Corresponds to the `--mount` option of `docker service create`.
	driver_config dictionary			Volume driver configuration. Can only be used when type is `volume`.
		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			Volume labels to apply.
	no_copy boolean		Choices: no yes	Disable copying of data from a container when a volume is created. Can only be used when type is `volume`.
	propagation string		Choices: shared slave private rshared rslave rprivate	The propagation mode to use. Can only be used when type is `bind`.
	readonly boolean		Choices: no yes	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 `tmpfs`.
	target string / required			Container path.
	tmpfs_mode integer			File mode of the tmpfs in octal. Can only be used when type is `tmpfs`.
	tmpfs_size string			Size of the tmpfs mount in format `<number>[<unit>]`. Number is a positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). Can only be used when type is `tmpfs`.
	type string		Choices: bind ← volume tmpfs npipe	The mount type. Note that `npipe` is only supported by Docker for Windows. Also note that `npipe` was added in Ansible 2.9.
name string / required				Service name. Corresponds to the `--name` option of `docker service create`.
networks list / elements=raw				List of the service networks names or dictionaries. When passed dictionaries valid sub-options are name, which is required, and aliases and options. 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 `--network` option of `docker service create`.
placement dictionary				Configures service placement preferences and constraints.
	constraints list / elements=string			List of the service constraints. Corresponds to the `--constraint` option of `docker service create`.
	preferences list / elements=dictionary			List of the placement preferences as key value pairs. Corresponds to the `--placement-pref` option of `docker service create`. Requires API version >= 1.27.
publish list / elements=dictionary				List of dictionaries describing the service published ports. Corresponds to the `--publish` option of `docker service create`. Requires API version >= 1.25.
	mode string		Choices: ingress host	What publish mode to use. Requires API version >= 1.32.
	protocol string		Choices: tcp ← udp	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			Choices: no yes	Mount the containers root filesystem as read only. Corresponds to the `--read-only` option of `docker service create`.
replicas integer			Default: -1	Number of containers instantiated in the service. Valid only if mode is `replicated`. If set to `-1`, and service is not present, service replicas will be set to `1`. If set to `-1`, and service is present, service replicas will be unchanged. Corresponds to the `--replicas` option of `docker service create`.
reservations dictionary				Configures service resource reservations.
	cpus float			Service CPU reservation. `0` equals no reservation. Corresponds to the `--reserve-cpu` option of `docker service create`.
	memory string			Service memory reservation in format `<number>[<unit>]`. Number is a positive integer. Unit can be `B` (byte), `K` (kibibyte, 1024B), `M` (mebibyte), `G` (gibibyte), `T` (tebibyte), or `P` (pebibyte). `0` equals no reservation. Omitting the unit defaults to bytes. Corresponds to the `--reserve-memory` option of `docker service create`.
resolve_image boolean			Choices: no ← yes	If the current image digest should be resolved from registry and updated if changed. Requires API version >= 1.30.
restart_config dictionary				Configures if and how to restart containers when they exit.
	condition string		Choices: none on-failure any	Restart condition of the service. Corresponds to the `--restart-condition` option of `docker service create`.
	delay string			Delay between restarts. Accepts a a string in a format that look like: `5h34m56s`, `1m30s` etc. The supported units are `us`, `ms`, `s`, `m` and `h`. Corresponds to the `--restart-delay` option of `docker service create`.
	max_attempts integer			Maximum number of service restarts. Corresponds to the `--restart-condition` option of `docker service create`.
	window string			Restart policy evaluation window. Accepts a string in a format that look like: `5h34m56s`, `1m30s` etc. The supported units are `us`, `ms`, `s`, `m` and `h`. Corresponds to the `--restart-window` option of `docker service create`.
rollback_config dictionary				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: `5h34m56s`, `1m30s` etc. The supported units are `us`, `ms`, `s`, `m` and `h`. Corresponds to the `--rollback-delay` option of `docker service create`. Requires API version >= 1.28.
	failure_action string		Choices: continue pause	Action to take in case of rollback failure. Corresponds to the `--rollback-failure-action` option of `docker service create`. Requires API version >= 1.28.
	max_failure_ratio float			Fraction of tasks that may fail during a rollback. Corresponds to the `--rollback-max-failure-ratio` option of `docker service create`. 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: `5h34m56s`, `1m30s` etc. The supported units are `us`, `ms`, `s`, `m` and `h`. Corresponds to the `--rollback-monitor` option of `docker service create`. Requires API version >= 1.28.
	order string			Specifies the order of operations during rollbacks. Corresponds to the `--rollback-order` option of `docker service create`. 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 `--rollback-parallelism` option of `docker service create`. Requires API version >= 1.28.
secrets list / elements=dictionary				List of dictionaries describing the service secrets. Corresponds to the `--secret` option of `docker service create`. 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 `target` key of `docker service create --secret`.
	gid string			GID of the secret file's group.
	mode integer			File access mode inside the container. Must be an octal number (like `0644` or `0444`).
	secret_id string			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 `DOCKER_SSL_VERSION` will be used instead.
state string			Choices: present ← absent	`absent` - A service matching the specified name will be removed and have its tasks stopped. `present` - Asserts the existence of a service matching the name and provided configuration parameters. Unspecified configuration parameters will be set to docker defaults.
stop_grace_period string				Time to wait before force killing a container. Accepts a duration as a string in a format that look like: `5h34m56s`, `1m30s` etc. The supported units are `us`, `ms`, `s`, `m` and `h`. Corresponds to the `--stop-grace-period` option of `docker service create`.
stop_signal string				Override default signal used to stop the container. Corresponds to the `--stop-signal` option of `docker service create`.
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 `DOCKER_TIMEOUT` will be used instead. If the environment variable is not set, the default value will be used.
tls boolean			Choices: no ← yes	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 `yes` as well, it will take precedence. If the value is not specified in the task, the value of environment variable `DOCKER_TLS` will be used instead. If the environment variable is not set, the default value will be used.
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 `DOCKER_TLS_HOSTNAME` will be used instead. If the environment variable is not set, the default value will be used.
tty boolean			Choices: no yes	Allocate a pseudo-TTY. Corresponds to the `--tty` option of `docker service create`. Requires API version >= 1.25.
update_config dictionary				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: `5h34m56s`, `1m30s` etc. The supported units are `us`, `ms`, `s`, `m` and `h`. Corresponds to the `--update-delay` option of `docker service create`.
	failure_action string		Choices: continue pause rollback	Action to take in case of container failure. Corresponds to the `--update-failure-action` option of `docker service create`. 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 `--update-max-failure-ratio` option of `docker service create`. Requires API version >= 1.25.
	monitor string			Time to monitor updated tasks for failures. Accepts a string in a format that look like: `5h34m56s`, `1m30s` etc. The supported units are `us`, `ms`, `s`, `m` and `h`. Corresponds to the `--update-monitor` option of `docker service create`. Requires API version >= 1.25.
	order string			Specifies the order of operations when rolling out an updated task. Corresponds to the `--update-order` option of `docker service create`. Requires API version >= 1.29.
	parallelism integer			Rolling update parallelism. Corresponds to the `--update-parallelism` option of `docker service create`.
user string				Sets the username or UID used for the specified command. Before Ansible 2.8, the default value for this option was `root`. The default has been removed so that the user defined in the image is used if no user is specified here. Corresponds to the `--user` option of `docker service create`.
validate_certs boolean			Choices: no ← yes	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 `DOCKER_TLS_VERIFY` will be used instead. If the environment variable is not set, the default value will be used. aliases: tls_verify
working_dir string				Path to the working directory. Corresponds to the `--workdir` option of `docker service create`.

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 and DOCKER_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.json if the DOCKER_CONFIG environment variable is not specified, and use $DOCKER_CONFIG/config.json otherwise.
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

- 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	Returned	Description
changes list / elements=string	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 `ansible_swarm_service`, while the module actually returned a variable called `ansible_docker_service`. The variable was renamed to `swarm_service` in both code and documentation for Ansible 2.7.9 and Ansible 2.8.0. In Ansible 2.7.x, the old name `ansible_docker_service` can still be used. 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" ], "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 }

Authors¶

Dario Zanzico (@dariko)
Jason Witkowski (@jwitko)
Hannes Ljungberg (@hannseman)

community.docker.docker_swarm_service – docker swarm service¶

Synopsis¶

Requirements¶

Parameters¶

Notes¶

Examples¶

Return Values¶