diff --git a/changelogs/fragments/53479-docker_swarm_service-documentation-fixes.yaml b/changelogs/fragments/53479-docker_swarm_service-documentation-fixes.yaml new file mode 100644 index 0000000000..2bce160a36 --- /dev/null +++ b/changelogs/fragments/53479-docker_swarm_service-documentation-fixes.yaml @@ -0,0 +1,2 @@ +bugfixes: + - "docker_swarm_service - Validate choices for option ``mode``." diff --git a/lib/ansible/modules/cloud/docker/docker_swarm_service.py b/lib/ansible/modules/cloud/docker/docker_swarm_service.py index 3fe5590102..7d63c4e913 100644 --- a/lib/ansible/modules/cloud/docker/docker_swarm_service.py +++ b/lib/ansible/modules/cloud/docker/docker_swarm_service.py @@ -306,9 +306,13 @@ options: mode: 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 default: replicated + choices: + - replicated + - global mounts: description: - List of dictionaries describing the service mounts. @@ -461,7 +465,6 @@ options: mode: description: - What publish mode to use. - - Service will be removed and recreated when changed. - Requires API version >= 1.32. type: str choices: @@ -670,79 +673,121 @@ swarm_service: returned: always type: dict 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. + - 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. sample: '{ "args": [ - "sleep", "3600" ], - "constraints": [], - "container_labels": {}, - "endpoint_mode": "vip", - "env": [ - "ENVVAR1=envvar1" + "command": [ + "sleep" ], - "force_update": False, - "image": "alpine", - "labels": {}, - "limit_cpu": 0.0, - "limit_memory": 0, - "log_driver": "json-file", - "log_driver_options": {}, + "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" } ], - "secrets": [], - "configs": [], - "networks": [], - "publish": [], + "networks": null, + "placement_preferences": [ + { + "spread": "node.labels.mylabel" + } + ], + "publish": null, "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" + "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 }' changes: returned: always description: - - List of changed service attributes if a service has been altered, - [] otherwise + - List of changed service attributes if a service has been altered, [] otherwise. type: list sample: ['container_labels', 'replicas'] rebuilt: returned: always description: - - True if the service has been recreated (removed and created) + - True if the service has been recreated (removed and created) type: bool sample: True ''' EXAMPLES = ''' -- name: Set arguments +- name: Set command and arguments docker_swarm_service: name: myservice image: alpine + command: sleep args: - - "sleep" - "3600" - name: Set a bind mount @@ -754,33 +799,54 @@ EXAMPLES = ''' 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" + ENVVAR1: envvar1 + ENVVAR2: envvar2 + env_files: + - envs/common.env + - envs/apps/web.env - name: Set fluentd logging docker_swarm_service: name: myservice image: alpine - log_driver: fluentd - log_driver_options: - fluentd-address: "127.0.0.1:24224" - fluentd-async-connect: true - tag: myservice + 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: any - max_attempts: 5 + condition: on-failure delay: 5s - window: 30s + 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 placement preferences docker_swarm_service: @@ -788,7 +854,10 @@ EXAMPLES = ''' image: alpine:edge placement: preferences: - - spread: "node.labels.mylabel" + - spread: node.labels.mylabel + constraints: + - node.role == manager + - engine.labels.operatingsystem == ubuntu 14.04 - name: Set configs docker_swarm_service: @@ -815,11 +884,6 @@ EXAMPLES = ''' secret_name: mysecret_name filename: "/run/secrets/secret.txt" -- name: Remove service - docker_swarm_service: - name: myservice - state: absent - - name: Start service with healthcheck docker_swarm_service: name: myservice @@ -832,6 +896,22 @@ EXAMPLES = ''' 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 ''' import shlex @@ -1018,6 +1098,7 @@ class DockerService(DockerBaseClass): 'replicas': self.replicas, 'endpoint_mode': self.endpoint_mode, 'restart_policy': self.restart_policy, + 'secrets': self.secrets, 'stop_grace_period': self.stop_grace_period, 'stop_signal': self.stop_signal, 'limit_cpu': self.limit_cpu, @@ -1033,6 +1114,7 @@ class DockerService(DockerBaseClass): 'update_monitor': self.update_monitor, 'update_max_failure_ratio': self.update_max_failure_ratio, 'update_order': self.update_order, + 'user': self.user, 'working_dir': self.working_dir, } @@ -2123,8 +2205,8 @@ def main(): publish=dict(type='list', elements='dict', options=dict( published_port=dict(type='int', required=True), target_port=dict(type='int', required=True), - protocol=dict(type='str', default='tcp', choices=('tcp', 'udp')), - mode=dict(type='str', choices=('ingress', 'host')), + protocol=dict(type='str', default='tcp', choices=['tcp', 'udp']), + mode=dict(type='str', choices=['ingress', 'host']), )), placement=dict(type='dict', options=dict( constraints=dict(type='list'), @@ -2146,7 +2228,11 @@ def main(): hosts=dict(type='dict'), labels=dict(type='dict'), container_labels=dict(type='dict'), - mode=dict(type='str', default='replicated'), + mode=dict( + type='str', + default='replicated', + choices=['replicated', 'global'] + ), replicas=dict(type='int', default=-1), endpoint_mode=dict(type='str', choices=['vip', 'dnsrr']), stop_grace_period=dict(type='str'), diff --git a/test/integration/targets/docker_swarm_service/tasks/tests/options.yml b/test/integration/targets/docker_swarm_service/tasks/tests/options.yml index e2ec0f79e9..4d4af36776 100644 --- a/test/integration/targets/docker_swarm_service/tasks/tests/options.yml +++ b/test/integration/targets/docker_swarm_service/tasks/tests/options.yml @@ -1106,7 +1106,7 @@ image: alpine:3.8 resolve_image: no command: '/bin/sh -v -c "sleep 10m"' - labels: {} + healthcheck: {} register: healthcheck_8 ignore_errors: yes @@ -1116,7 +1116,7 @@ image: alpine:3.8 resolve_image: no command: '/bin/sh -v -c "sleep 10m"' - labels: {} + healthcheck: {} register: healthcheck_9 ignore_errors: yes diff --git a/test/integration/targets/docker_swarm_service/tasks/tests/resources.yml b/test/integration/targets/docker_swarm_service/tasks/tests/resources.yml index c0a073d33e..03ccea93c9 100644 --- a/test/integration/targets/docker_swarm_service/tasks/tests/resources.yml +++ b/test/integration/targets/docker_swarm_service/tasks/tests/resources.yml @@ -48,7 +48,7 @@ resolve_image: no command: '/bin/sh -v -c "sleep 10m"' limits: - cpus: 2 + cpus: 0.5 register: limit_cpu_3 - name: cleanup @@ -159,7 +159,7 @@ resolve_image: no command: '/bin/sh -v -c "sleep 10m"' reservations: - cpus: 2 + cpus: 0.5 register: reserve_cpu_3 - name: cleanup diff --git a/test/integration/targets/docker_swarm_service/vars/main.yml b/test/integration/targets/docker_swarm_service/vars/main.yml index cfabafed9a..fd8c6932f3 100644 --- a/test/integration/targets/docker_swarm_service/vars/main.yml +++ b/test/integration/targets/docker_swarm_service/vars/main.yml @@ -26,6 +26,7 @@ service_expected_output: mode: global mounts: null networks: null + secrets: null stop_grace_period: null stop_signal: null placement_preferences: null @@ -46,4 +47,5 @@ service_expected_output: update_monitor: null update_order: null update_parallelism: null + user: null working_dir: null