docker_swarm_service: Documentation fixes (#53479)

* Document and validate mode choices

* Update examples

* Test cpu float values

* Test correct option

* Fix module return sample

* Add secrets and user to module return value

* Order options alphabetically

* Add changelog

* yaml indentation

* Revert "Order options alphabetically"

This reverts commit 51dabccda7930b707d5683670af7f89a68aeb577.

* Be consistent with choices type

changelogs/fragments/53479-docker_swarm_service-documentation-fixes.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - "docker_swarm_service - Validate choices for option ``mode``."

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.
+    - Dictionary of variables representing the current state of the service.
-    Matches the module parameters format.
+      Matches the module parameters format.
-  - Note that facts are not part of registered vars but accessible directly.
+    - 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),
+    - 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
+      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.
+      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.
+      In Ansible 2.7.x, the old name C(ansible_docker_service) can still be used.
   sample: '{
     "args": [
-      "sleep",
       "3600"
     ],
-    "constraints": [],
+    "command": [
-    "container_labels": {},
+      "sleep"
-    "endpoint_mode": "vip",
-    "env": [
-      "ENVVAR1=envvar1"
     ],
-    "force_update": False,
+    "configs": null,
-    "image": "alpine",
+    "constraints": [
-    "labels": {},
+      "node.role == manager",
-    "limit_cpu": 0.0,
+      "engine.labels.operatingsystem == ubuntu 14.04"
-    "limit_memory": 0,
+    ],
-    "log_driver": "json-file",
+    "container_labels": null,
-    "log_driver_options": {},
+    "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": [],
+    "networks": null,
-    "configs": [],
+    "placement_preferences": [
-    "networks": [],
+      {
-    "publish": [],
+        "spread": "node.labels.mylabel"
+      }
+    ],
+    "publish": null,
     "replicas": 1,
-    "reserve_cpu": 0.0,
+    "reserve_cpu": 0.25,
-    "reserve_memory": 0,
+    "reserve_memory": 20971520,
-    "restart_policy": "any",
+    "restart_policy": "on-failure",
-    "restart_policy_attempts": 5,
+    "restart_policy_attempts": 3,
-    "restart_policy_delay": 0,
+    "restart_policy_delay": 5000000000,
-    "restart_policy_window": 30,
+    "restart_policy_window": 120000000000,
-    "update_delay": 10,
+    "secrets": null,
-    "update_parallelism": 1,
+    "stop_grace_period": null,
-    "update_failure_action": "continue",
+    "stop_signal": null,
-    "update_monitor": 5000000000
+    "tty": null,
-    "update_max_failure_ratio": 0,
+    "update_delay": 10000000000,
-    "update_order": "stop-first"
+    "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,
+    - List of changed service attributes if a service has been altered, [] otherwise.
-    [] 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"
+      ENVVAR1: envvar1
-      - "ENVVAR2=envvar2"
+      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
+    logging:
-    log_driver_options:
+      driver: fluentd
-      fluentd-address: "127.0.0.1:24224"
+      options:
-      fluentd-async-connect: true
+        fluentd-address: "127.0.0.1:24224"
-      tag: myservice
+        fluentd-async-connect: "true"
+        tag: myservice
 
 - name: Set restart policies
   docker_swarm_service:
     name: myservice
     image: alpine
     restart_config:
-      condition: any
+      condition: on-failure
-      max_attempts: 5
       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')),
+            protocol=dict(type='str', default='tcp', choices=['tcp', 'udp']),
-            mode=dict(type='str', choices=('ingress', 'host')),
+            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'),

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
 

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

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