ansible / ansible.builtin / v2.7.16 / module / docker_swarm_service docker swarm service | "added in version" 2.7 of ansible.builtin" Authors: Dario Zanzico (@dariko), Jason Witkowski (@jwitko) preview | supported by communityansible.builtin.docker_swarm_service (v2.7.16) — module
pip
Install 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