Try Spotterdocker swarm service
| "added in version" 2.7 of ansible.builtin"
Authors: Dario Zanzico (@dariko), Jason Witkowski (@jwitko)
preview | supported by community
pipInstall with pip install ansible==2.7.16
Manage docker services. Allows live altering of already defined services
- name: define myservice
docker_swarm_service:
name: myservice
image: "alpine"
args:
- "sleep"
- "3600"
mounts:
- source: /tmp/
target: /remote_tmp/
type: bind
env:
- "ENVVAR1=envvar1"
log_driver: fluentd
log_driver_options:
fluentd-address: "127.0.0.1:24224"
fluentd-async-connect: true
tag: "{{.Name}}/{{.ID}}"
restart_policy: any
restart_policy_attempts: 5
restart_policy_window: 30
register: dss_out1
- name: change myservice.env
docker_swarm_service:
name: myservice
image: "alpine"
args:
- "sleep"
- "7200"
mounts:
- source: /tmp/
target: /remote_tmp/
type: bind
env:
- "ENVVAR1=envvar1"
restart_policy: any
restart_policy_attempts: 5
restart_policy_window: 30
register: dss_out2
- name: test for changed myservice facts
fail:
msg: unchanged service
when: "{{ dss_out1 == dss_out2 }}"
- name: change myservice.image
docker_swarm_service:
name: myservice
image: "alpine:edge"
args:
- "sleep"
- "7200"
mounts:
- source: /tmp/
target: /remote_tmp/
type: bind
env:
- "ENVVAR1=envvar1"
restart_policy: any
restart_policy_attempts: 5
restart_policy_window: 30
register: dss_out3
- name: test for changed myservice facts
fail:
msg: unchanged service
when: "{{ dss_out2 == dss_out3 }}"
- name: remove mount
docker_swarm_service:
name: myservice
image: "alpine:edge"
args:
- "sleep"
- "7200"
env:
- "ENVVAR1=envvar1"
restart_policy: any
restart_policy_attempts: 5
restart_policy_window: 30
register: dss_out4
- name: test for changed myservice facts
fail:
msg: unchanged service
when: "{{ dss_out3 == dss_out4 }}"
- name: keep service as it is
docker_swarm_service:
name: myservice
image: "alpine:edge"
args:
- "sleep"
- "7200"
env:
- "ENVVAR1=envvar1"
restart_policy: any
restart_policy_attempts: 5
restart_policy_window: 30
register: dss_out5
- name: test for changed service facts
fail:
msg: changed service
when: "{{ dss_out5 != dss_out5 }}"
- name: remove myservice
docker_swarm_service:
name: myservice
state: absent
dns:
default: []
description:
- List of custom DNS servers.
- Maps docker service --dns option.
- Requires API version >= 1.25
required: false
env:
default: []
description:
- List of the service environment variables.
- Maps docker service --env option.
required: false
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
tty:
default: false
description:
- Allocate a pseudo-TTY
- Maps docker service --tty option.
- Requires API version >= 1.25
required: false
type: bool
args:
default: []
description:
- List comprised of the command and the arguments to be run inside
- the container
required: false
mode:
default: replicated
description:
- Service replication mode.
- Maps docker service --mode option.
required: false
name:
description:
- Service name
required: true
user:
default: root
description:
- username or UID.
- If set to C(null) the image provided value (or the one already set for the service)
will be used
required: false
debug:
default: false
description:
- Debug mode
type: bool
image:
description:
- Service image path and tag. Maps docker service IMAGE parameter.
required: true
state:
choices:
- present
- absent
default: present
description:
- Service state.
required: true
labels:
description:
- Dictionary of key value pairs.
- Maps docker service --label option.
required: false
type: dict
mounts:
default: []
description:
- List of dictionaries describing the service mounts.
- Every item must be a dictionary exposing the keys source, target, type (defaults
to 'bind'), readonly (defaults to false)
- Maps docker service --mount option.
required: false
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
configs:
default: []
description:
- List of dictionaries describing the service configs.
- Every item must be a dictionary exposing the keys config_id, config_name, filename,
uid (defaults to 0), gid (defaults to 0), mode (defaults to 0444)
- Maps docker service --config option.
- Requires API version >= 1.30
required: false
publish:
default: []
description:
- List of dictionaries describing the service published ports.
- Every item must be a dictionary exposing the keys published_port, target_port, protocol
(defaults to 'tcp'), mode <ingress|host>, default to ingress.
- Only used with api_version >= 1.25
- If API version >= 1.32 and docker python library >= 3.0.0 attribute 'mode' can be
set to 'ingress' or 'host' (default 'ingress').
required: false
secrets:
default: []
description:
- List of dictionaries describing the service secrets.
- Every item must be a dictionary exposing the keys secret_id, secret_name, filename,
uid (defaults to 0), gid (defaults to 0), mode (defaults to 0444)
- Maps docker service --secret option.
- Requires API version >= 1.25
required: false
timeout:
default: 60
description:
- 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 C(DOCKER_TIMEOUT)
will be used instead. If the environment variable is not set, the default value
will be used.
type: int
hostname:
default: ''
description:
- Container hostname
- Maps docker service --hostname option.
- Requires API version >= 1.25
required: false
networks:
default: []
description:
- List of the service networks names.
- Maps docker service --network option.
required: false
replicas:
default: -1
description:
- Number of containers instantiated in the service. Valid only if ``mode=='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.
- Maps docker service --replicas option.
required: false
limit_cpu:
default: 0.0
description:
- Service CPU limit. 0 equals no limit.
- Maps docker service --limit-cpu option.
required: false
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
dns_search:
default: []
description:
- List of custom DNS search domains.
- Maps docker service --dns-search option.
- Requires API version >= 1.25
required: false
log_driver:
default: json-file
description:
- Configure the logging driver for a service
required: false
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
constraints:
default: []
description:
- List of the service constraints.
- Maps docker service --constraint option.
required: false
dns_options:
default: []
description:
- List of custom DNS options.
- Maps docker service --dns-option option.
- Requires API version >= 1.25
required: false
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
reserve_cpu:
default: 0.0
description:
- Service CPU reservation. 0 equals no reservation.
- Maps docker service --reserve-cpu option.
required: false
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
force_update:
default: false
description:
- Force update even if no changes require it.
- Maps to docker service update --force option.
- Requires API version >= 1.25
required: false
type: bool
limit_memory:
default: 0
description:
- 'Service memory limit (format: C(<number>[<unit>])). Number is a positive integer.
Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
C(T) (tebibyte), or C(P) (pebibyte).'
- 0 equals no limit.
- Omitting the unit defaults to bytes.
- Maps docker service --limit-memory option.
required: false
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
update_delay:
default: 10
description:
- Rolling update delay
- Maps docker service --update-delay option
required: false
update_order:
choices:
- stop-first
- start-first
default: stop-first
description:
- Specifies the order of operations when rolling out an updated task.
- Maps to docker service --update-order
- Requires API version >= 1.29
required: false
endpoint_mode:
choices:
- vip
- dnsrr
description:
- Service endpoint mode.
- Maps docker service --endpoint-mode option.
type: str
reserve_memory:
default: 0
description:
- 'Service memory reservation (format: C(<number>[<unit>])). Number is a positive
integer. Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G)
(gibibyte), C(T) (tebibyte), or C(P) (pebibyte).'
- 0 equals no reservation.
- Omitting the unit defaults to bytes.
- Maps docker service --reserve-memory option.
required: false
restart_policy:
choices:
- none
- on-failure
- any
default: none
description:
- Restart condition of the service.
- Maps docker service --restart-condition option.
required: false
update_monitor:
default: 5000000000
description:
- Time to monitor updated tasks for failures, in nanoseconds.
- Maps to docker service --update-monitor option
required: false
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
container_labels:
description:
- Dictionary of key value pairs.
- Maps docker service --container-label option.
required: false
type: dict
log_driver_options:
default: []
description:
- Options for service logging driver
required: false
update_parallelism:
default: 1
description:
- Rolling update parallelism
- Maps docker service --update-parallelism option
required: false
restart_policy_delay:
default: 0
description:
- Delay between restarts.
- Maps docker service --restart-delay option.
required: false
restart_policy_window:
default: 0
description:
- Restart policy evaluation window.
- Maps docker service --restart-window option.
required: false
update_failure_action:
choices:
- continue
- pause
default: continue
description:
- Action to take in case of container failure
- Maps to docker service --update-failure-action option
required: false
restart_policy_attempts:
default: 0
description:
- Maximum number of service restarts.
- Maps docker service --restart-max-attempts option.
required: false
update_max_failure_ratio:
default: 0.0
description:
- Fraction of tasks that may fail during an update before the failure action is invoked
- Maps to docker service --update-max-failure-ratio
required: false
changes:
description:
- List of changed service attributes if a service has been altered, [] otherwhise
returned: always
sample:
- container_labels
- replicas
type: list
rebuilt:
description:
- True if the service has been recreated (removed and created)
returned: always
sample: true
type: bool
swarm_service:
description:
- 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 C(ansible_swarm_service),
while the module actually returned a variable called C(ansible_docker_service).
The variable was renamed to C(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 C(ansible_docker_service)
can still be used.
returned: always
sample: '{ "args": [ "sleep", "3600" ], "constraints": [], "container_labels": {},
"endpoint_mode": "vip", "env": [ "ENVVAR1=envvar1" ], "force_update": False, "image":
"alpine", "labels": {}, "limit_cpu": 0.0, "limit_memory": 0, "log_driver": "json-file",
"log_driver_options": {}, "mode": "replicated", "mounts": [ { "source": "/tmp/",
"target": "/remote_tmp/", "type": "bind" } ], "secrets": [], "configs": [], "networks":
[], "publish": [], "replicas": 1, "reserve_cpu": 0.0, "reserve_memory": 0, "restart_policy":
"any", "restart_policy_attempts": 5, "restart_policy_delay": 0, "restart_policy_window":
30, "update_delay": 10, "update_parallelism": 1, "update_failure_action": "continue",
"update_monitor": 5000000000 "update_max_failure_ratio": 0, "update_order": "stop-first"
}'
type: dict