community / community.docker / 3.5.0 / module / docker_swarm_service docker swarm service Authors: Dario Zanzico (@dariko), Jason Witkowski (@jwitko), Hannes Ljungberg (@hannseman), Piotr Wojciechowski (@wojciechowskipiotr)community.docker.docker_swarm_service (3.5.0) — module
Install with ansible-galaxy collection install community.docker:==3.5.0
collections: - name: community.docker version: 3.5.0
Manages docker services via a swarm manager node.
This modules does not support updating services in a stack.
- 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
dns: description: - List of custom DNS servers. - Corresponds to the C(--dns) option of C(docker service create). elements: str type: list env: description: - List or dictionary of the service environment variables. - If passed a list each items need to be in the format of C(KEY=VALUE). - If passed a dictionary values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example V("true")) in order to avoid data loss. - Corresponds to the C(--env) option of C(docker service create). type: raw 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 O(validate_certs) is set to V(true) as well, it will take precedence. - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used instead. If the environment variable is not set, the default value will be used. type: bool tty: description: - Allocate a pseudo-TTY. - Corresponds to the C(--tty) option of C(docker service create). type: bool args: description: - List arguments to be passed to the container. - Corresponds to the C(ARG) parameter of C(docker service create). elements: str type: list init: description: - Use an init inside each service container to forward signals and reap processes. - Corresponds to the C(--init) option of C(docker service create). - Requires API version >= 1.37. type: bool mode: choices: - replicated - global default: replicated description: - Service replication mode. - Service will be removed and recreated when changed. - Corresponds to the C(--mode) option of C(docker service create). type: str name: description: - Service name. - Corresponds to the C(--name) option of C(docker service create). required: true type: str user: description: - Sets the username or UID used for the specified command. - Before Ansible 2.8, the default value for this option was V(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 C(--user) option of C(docker service create). type: str debug: default: false description: - Debug mode type: bool hosts: description: - 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 C(--host) option of C(docker service create). type: dict image: description: - Service image path and tag. - Corresponds to the C(IMAGE) parameter of C(docker service create). type: str state: choices: - present - absent default: present description: - V(absent) - A service matching the specified name will be removed and have its tasks stopped. - V(present) - Asserts the existence of a service matching the name and provided configuration parameters. Unspecified configuration parameters will be set to docker defaults. type: str groups: description: - List of additional group names and/or IDs that the container process will run as. - Corresponds to the C(--group) option of C(docker service update). elements: str type: list labels: description: - Dictionary of key value pairs. - Corresponds to the C(--label) option of C(docker service create). type: dict limits: description: - Configures service resource limits. suboptions: cpus: description: - Service CPU limit. V(0) equals no limit. - Corresponds to the C(--limit-cpu) option of C(docker service create). type: float memory: description: - Service memory limit in format C(<number>[<unit>]). Number is a positive integer. Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte), V(T) (tebibyte), or V(P) (pebibyte). - V(0) equals no limit. - Omitting the unit defaults to bytes. - Corresponds to the C(--limit-memory) option of C(docker service create). type: str type: dict mounts: description: - List of dictionaries describing the service mounts. - Corresponds to the C(--mount) option of C(docker service create). elements: dict suboptions: driver_config: description: - Volume driver configuration. - Can only be used when O(mounts[].type=volume). suboptions: name: description: - Name of the volume-driver plugin to use for the volume. type: str options: description: - Options as key-value pairs to pass to the driver for this volume. type: dict type: dict labels: description: - Volume labels to apply. type: dict no_copy: description: - Disable copying of data from a container when a volume is created. - Can only be used when O(mounts[].type=volume). type: bool propagation: choices: - shared - slave - private - rshared - rslave - rprivate description: - The propagation mode to use. - Can only be used when O(mounts[].type=bind). type: str readonly: description: - Whether the mount should be read-only. type: bool source: description: - Mount source (for example a volume name or a host path). - Must be specified if O(mounts[].type) is not V(tmpfs). type: str target: description: - Container path. required: true type: str tmpfs_mode: description: - File mode of the tmpfs in octal. - Can only be used when O(mounts[].type=tmpfs). type: int tmpfs_size: description: - Size of the tmpfs mount in format C(<number>[<unit>]). Number is a positive integer. Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte), V(T) (tebibyte), or V(P) (pebibyte). - Can only be used when O(mounts[].type=tmpfs). type: str type: choices: - bind - volume - tmpfs - npipe default: bind description: - The mount type. - Note that V(npipe) is only supported by Docker for Windows. Also note that V(npipe) was added in Ansible 2.9. type: str type: list 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 E(DOCKER_CERT_PATH) is set, the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. type: path cap_add: description: - List of capabilities to add to the container. - Requires API version >= 1.41. elements: str type: list version_added: 2.2.0 version_added_collection: community.docker command: description: - 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 C(COMMAND) parameter of C(docker service create). type: raw configs: description: - List of dictionaries describing the service configs. - Corresponds to the C(--config) option of C(docker service create). - Requires API version >= 1.30. elements: dict suboptions: config_id: description: - Config's ID. type: str config_name: description: - Config's name as defined at its creation. required: true type: str filename: description: - Name of the file containing the config. Defaults to the O(configs[].config_name) if not specified. type: str gid: description: - GID of the config file's group. type: str mode: description: - File access mode inside the container. Must be an octal number (like V(0644) or V(0444)). type: int uid: description: - UID of the config file's owner. type: str type: list logging: description: - Logging configuration for the service. suboptions: driver: description: - Configure the logging driver for a service. - Corresponds to the C(--log-driver) option of C(docker service create). type: str options: description: - Options for service logging driver. - Corresponds to the C(--log-opt) option of C(docker service create). type: dict type: dict publish: description: - List of dictionaries describing the service published ports. - Corresponds to the C(--publish) option of C(docker service create). elements: dict suboptions: mode: choices: - ingress - host description: - What publish mode to use. - Requires API version >= 1.32. type: str protocol: choices: - tcp - udp default: tcp description: - What protocol to use. type: str published_port: description: - The port to make externally available. required: false type: int target_port: description: - The port inside the container to expose. required: true type: int type: list secrets: description: - List of dictionaries describing the service secrets. - Corresponds to the C(--secret) option of C(docker service create). elements: dict suboptions: filename: description: - Name of the file containing the secret. Defaults to the O(secrets[].secret_name) if not specified. - Corresponds to the C(target) key of C(docker service create --secret). type: str gid: description: - GID of the secret file's group. type: str mode: description: - File access mode inside the container. Must be an octal number (like V(0644) or V(0444)). type: int secret_id: description: - Secret's ID. type: str secret_name: description: - Secret's name as defined at its creation. required: true type: str uid: description: - UID of the secret file's owner. type: str type: list 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 E(DOCKER_TIMEOUT) will be used instead. If the environment variable is not set, the default value will be used. type: int cap_drop: description: - List of capabilities to drop from the container. - Requires API version >= 1.41. elements: str type: list version_added: 2.2.0 version_added_collection: community.docker hostname: description: - Container hostname. - Corresponds to the C(--hostname) option of C(docker service create). type: str networks: description: - List of the service networks names or dictionaries. - When passed dictionaries valid sub-options are C(name), which is required, and C(aliases) and C(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 C(--network) option of C(docker service create). elements: raw type: list replicas: default: -1 description: - Number of containers instantiated in the service. Valid only if O(mode=replicated). - If set to V(-1), and service is not present, service replicas will be set to V(1). - If set to V(-1), and service is present, service replicas will be unchanged. - Corresponds to the C(--replicas) option of C(docker service create). type: int env_files: description: - List of paths to files, present on the target, containing environment variables C(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 O(env), then O(env) value will override. elements: path type: list placement: description: - Configures service placement preferences and constraints. suboptions: constraints: description: - List of the service constraints. - Corresponds to the C(--constraint) option of C(docker service create). elements: str type: list preferences: description: - List of the placement preferences as key value pairs. - Corresponds to the C(--placement-pref) option of C(docker service create). - Requires API version >= 1.27. elements: dict type: list replicas_max_per_node: description: - Maximum number of tasks per node. - Corresponds to the C(--replicas_max_per_node) option of C(docker service create). - Requires API version >= 1.40 type: int version_added: 1.3.0 version_added_collection: community.docker type: dict read_only: description: - Mount the containers root filesystem as read only. - Corresponds to the C(--read-only) option of C(docker service create). 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 E(DOCKER_CERT_PATH) is set, the file C(key.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. type: path dns_search: description: - List of custom DNS search domains. - Corresponds to the C(--dns-search) option of C(docker service create). elements: str type: list 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 E(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 E(DOCKER_CERT_PATH) is set, the file C(cert.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. type: path dns_options: description: - List of custom DNS options. - Corresponds to the C(--dns-option) option of C(docker service create). elements: str type: list 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, V(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 E(DOCKER_HOST) will be used instead. If the environment variable is not set, the default value will be used. type: str healthcheck: description: - Configure a check that is run to determine whether or not containers for this service are "healthy". See the docs for the L(HEALTHCHECK Dockerfile instruction,https://docs.docker.com/engine/reference/builder/#healthcheck) for details on how healthchecks work. - 'O(healthcheck.interval), O(healthcheck.timeout), and O(healthcheck.start_period) are specified as durations. They accept duration as a string in a format that look like: V(5h34m56s), V(1m30s), and so on. The supported units are V(us), V(ms), V(s), V(m) and V(h).' suboptions: interval: description: - Time between running the check. type: str retries: description: - Consecutive failures needed to report unhealthy. It accept integer value. type: int start_period: description: - Start period for the container to initialize before starting health-retries countdown. type: str test: description: - 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 V(NONE), V(CMD) or V(CMD-SHELL). type: raw timeout: description: - Maximum time to allow one check to run. type: str type: dict ssl_version: description: - Provide a valid SSL version number. Default value determined by L(SSL Python module, https://docs.python.org/3/library/ssl.html). - If the value is not specified in the task, the value of environment variable E(DOCKER_SSL_VERSION) will be used instead. - B(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. type: str stop_signal: description: - Override default signal used to stop the container. - Corresponds to the C(--stop-signal) option of C(docker service create). type: str working_dir: description: - Path to the working directory. - Corresponds to the C(--workdir) option of C(docker service create). type: str force_update: default: false description: - Force update even if no changes require it. - Corresponds to the C(--force) option of C(docker service update). type: bool reservations: description: - Configures service resource reservations. suboptions: cpus: description: - Service CPU reservation. V(0) equals no reservation. - Corresponds to the C(--reserve-cpu) option of C(docker service create). type: float memory: description: - Service memory reservation in format C(<number>[<unit>]). Number is a positive integer. Unit can be V(B) (byte), V(K) (kibibyte, 1024B), V(M) (mebibyte), V(G) (gibibyte), V(T) (tebibyte), or V(P) (pebibyte). - V(0) equals no reservation. - Omitting the unit defaults to bytes. - Corresponds to the C(--reserve-memory) option of C(docker service create). type: str type: dict 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 E(DOCKER_TLS_HOSTNAME) will be used instead. If the environment variable is not set, the default value will be used. - Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0. - B(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. type: str endpoint_mode: choices: - vip - dnsrr description: - Service endpoint mode. - Corresponds to the C(--endpoint-mode) option of C(docker service create). type: str resolve_image: default: false description: - If the current image digest should be resolved from registry and updated if changed. - Requires API version >= 1.30. type: bool update_config: description: - Configures how the service should be updated. Useful for configuring rolling updates. suboptions: delay: description: - Rolling update delay. - 'Accepts a string in a format that look like: V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h).' - Corresponds to the C(--update-delay) option of C(docker service create). type: str failure_action: choices: - continue - pause - rollback description: - Action to take in case of container failure. - Corresponds to the C(--update-failure-action) option of C(docker service create). - Usage of V(rollback) requires API version >= 1.29. type: str max_failure_ratio: description: - Fraction of tasks that may fail during an update before the failure action is invoked. - Corresponds to the C(--update-max-failure-ratio) option of C(docker service create). type: float monitor: description: - Time to monitor updated tasks for failures. - 'Accepts a string in a format that look like: V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h).' - Corresponds to the C(--update-monitor) option of C(docker service create). type: str order: description: - Specifies the order of operations when rolling out an updated task. - Corresponds to the C(--update-order) option of C(docker service create). - Requires API version >= 1.29. type: str parallelism: description: - Rolling update parallelism. - Corresponds to the C(--update-parallelism) option of C(docker service create). type: int type: dict restart_config: description: - Configures if and how to restart containers when they exit. suboptions: condition: choices: - none - on-failure - any description: - Restart condition of the service. - Corresponds to the C(--restart-condition) option of C(docker service create). type: str delay: description: - Delay between restarts. - 'Accepts a a string in a format that look like: V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h).' - Corresponds to the C(--restart-delay) option of C(docker service create). type: str max_attempts: description: - Maximum number of service restarts. - Corresponds to the C(--restart-condition) option of C(docker service create). type: int window: description: - Restart policy evaluation window. - 'Accepts a string in a format that look like: V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h).' - Corresponds to the C(--restart-window) option of C(docker service create). type: str type: dict 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 E(DOCKER_TLS_VERIFY) will be used instead. If the environment variable is not set, the default value will be used. type: bool rollback_config: description: - Configures how the service should be rolled back in case of a failing update. suboptions: delay: description: - Delay between task rollbacks. - 'Accepts a string in a format that look like: V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h).' - Corresponds to the C(--rollback-delay) option of C(docker service create). - Requires API version >= 1.28. type: str failure_action: choices: - continue - pause description: - Action to take in case of rollback failure. - Corresponds to the C(--rollback-failure-action) option of C(docker service create). - Requires API version >= 1.28. type: str max_failure_ratio: description: - Fraction of tasks that may fail during a rollback. - Corresponds to the C(--rollback-max-failure-ratio) option of C(docker service create). - Requires API version >= 1.28. type: float monitor: description: - Duration after each task rollback to monitor for failure. - 'Accepts a string in a format that look like: V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h).' - Corresponds to the C(--rollback-monitor) option of C(docker service create). - Requires API version >= 1.28. type: str order: description: - Specifies the order of operations during rollbacks. - Corresponds to the C(--rollback-order) option of C(docker service create). - Requires API version >= 1.29. type: str parallelism: description: - The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously. - Corresponds to the C(--rollback-parallelism) option of C(docker service create). - Requires API version >= 1.28. type: int type: dict container_labels: description: - Dictionary of key value pairs. - Corresponds to the C(--container-label) option of C(docker service create). type: dict stop_grace_period: description: - Time to wait before force killing a container. - 'Accepts a duration as a string in a format that look like: V(5h34m56s), V(1m30s) etc. The supported units are V(us), V(ms), V(s), V(m) and V(h).' - Corresponds to the C(--stop-grace-period) option of C(docker service create). type: str
changes: description: - List of changed service attributes if a service has been altered, [] otherwise. elements: str 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 RV(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": [ "3600" ], "cap_add": null, "cap_drop": [ "ALL" ], "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, "replicas_max_per_node": 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 }' type: dict