docker_* modules: updating argument_spec (#48491)

* Updating argument_spec for docker_* modules.

* Adjust docker_network to work with new recursive argument_spec.

* Adjust device IO limits to recursive argument_spec.

* Improve test (test Ansible's cast from str to int).

* Adjust healthcheck options construction.

* Remove superfluous check.

* Make flake8 happy.

* Simplify comparison.

lib/ansible/modules/cloud/docker/docker_container.py

@@ -101,8 +101,18 @@ options:
   device_read_bps:
     description:
       - "List of device path and read rate (bytes per second) from device."
-      - "I(path) - device path in the container."
-      - "I(rate) - device read limit (format: <number>[<unit>])"
+    type: list
+    suboptions:
+      path:
+        type: str
+        required: true
+        description:
+        - Device path in the container.
+      rate:
+        type: str
+        required: true
+        description:
+        - "Device read limit. Format: <number>[<unit>]"
         - "Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
           C(T) (tebibyte), or C(P) (pebibyte)"
         - "Omitting the unit defaults to bytes."
@@ -110,8 +120,18 @@ options:
   device_write_bps:
     description:
       - "List of device and write rate (bytes per second) to device."
-      - "I(path) - device path in the container."
-      - "I(rate) - device write limit (format: <number>[<unit>])"
+    type: list
+    suboptions:
+      path:
+        type: str
+        required: true
+        description:
+        - Device path in the container.
+      rate:
+        type: str
+        required: true
+        description:
+        - "Device read limit. Format: <number>[<unit>]"
         - "Number is a positive integer. Unit can be one of C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
           C(T) (tebibyte), or C(P) (pebibyte)"
         - "Omitting the unit defaults to bytes."
@@ -119,16 +139,36 @@ options:
   device_read_iops:
     description:
       - "List of device and read rate (IO per second) from device."
-      - "I(path) - device path in the container."
-      - "I(rate) - device read limit (format: <number>)"
-      - "Number is a positive integer."
+    type: list
+    suboptions:
+      path:
+        type: str
+        required: true
+        description:
+        - Device path in the container.
+      rate:
+        type: int
+        required: true
+        description:
+        - "Device read limit."
+        - "Must be a positive integer."
     version_added: "2.8"
   device_write_iops:
     description:
       - "List of device and write rate (IO per second) to device."
-      - "I(path) - device path in the container."
-      - "I(rate) - device write limit (format: <number>)"
-      - "Number is a positive integer."
+    type: list
+    suboptions:
+      path:
+        type: str
+        required: true
+        description:
+        - Device path in the container.
+      rate:
+        type: int
+        required: true
+        description:
+        - "Device read limit."
+        - "Must be a positive integer."
     version_added: "2.8"
   dns_opts:
     description:
@@ -184,14 +224,29 @@ options:
       - '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.'
-      - 'I(test) - Command to run to check health. C(test) must be either a string or a list. If it is a list, the first item must
-        be one of C(NONE), C(CMD) or C(CMD-SHELL).'
-      - 'I(interval) - Time between running the check. (default: 30s)'
-      - 'I(timeout) - Maximum time to allow one check to run. (default: 30s)'
-      - 'I(retries) - Consecutive failures needed to report unhealthy. It accept integer value. (default: 3)'
-      - 'I(start_period) - Start period for the container to initialize before starting health-retries countdown. (default: 0s)'
-      - 'C(interval), C(timeout) and C(start_period) are specified as durations. They accept duration as a string in a format
+      - 'I(interval), I(timeout) and I(start_period) are specified as durations. They accept duration as a string in a format
         that look like: C(5h34m56s), C(1m30s) etc. The supported units are C(us), C(ms), C(s), C(m) and C(h)'
+    suboptions:
+      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 C(NONE), C(CMD) or C(CMD-SHELL).
+      interval:
+        description:
+          - 'Time between running the check. (default: 30s)'
+        type: str
+      timeout:
+        description:
+          - 'Maximum time to allow one check to run. (default: 30s)'
+        type: str
+      retries:
+        description:
+          - 'Consecutive failures needed to report unhealthy. It accept integer value. (default: 3)'
+        type: int
+      start_period:
+        description:
+          - 'Start period for the container to initialize before starting health-retries countdown. (default: 0s)'
+        type: str
   hostname:
     description:
       - Container hostname.
@@ -300,15 +355,36 @@ options:
   networks:
      description:
        - List of networks the container belongs to.
-       - Each network is a dict with keys C(name), C(ipv4_address), C(ipv6_address), C(links), C(aliases).
-       - For each network C(name) is required, all other keys are optional.
-       - If included, C(links) or C(aliases) are lists.
        - For examples of the data structure and usage see EXAMPLES below.
        - To remove a container from one or more networks, use the C(purge_networks) option.
        - Note that as opposed to C(docker run ...), M(docker_container) does not remove the default
          network if C(networks) is specified. You need to explicity use C(purge_networks) to enforce
          the removal of the default network (and all other networks not explicitly mentioned in C(networks)).
      version_added: "2.2"
+     type: list
+     suboptions:
+        name:
+           type: str
+           required: true
+           description:
+             - The network's name.
+        ipv4_address:
+           type: str
+           description:
+             - The container's IPv4 address in this network.
+        ipv6_address:
+           type: str
+           description:
+             - The container's IPv6 address in this network.
+        links:
+           type: list
+           description:
+             - A list of containers to link to.
+        aliases:
+           type: list
+           description:
+             - List of aliases for this container in this network. These names
+               can be used in the network to reach this container.
   oom_killer:
     description:
       - Whether or not to disable OOM Killer for the container.
@@ -1015,8 +1091,6 @@ class TaskParameters(DockerBaseClass):
 
         if self.networks:
             for network in self.networks:
-                if not network.get('name'):
-                    self.fail("Parameter error: network must have a name attribute.")
                 network['id'] = self._get_network_id(network['name'])
                 if not network['id']:
                     self.fail("Parameter error: network named %s could not be found. Does it exist?" % network['name'])
@@ -1441,6 +1515,10 @@ class TaskParameters(DockerBaseClass):
 
         for (key, value) in options.items():
             if value in self.healthcheck:
+                if self.healthcheck.get(value) is None:
+                    # due to recursive argument_spec, all keys are always present
+                    # (but have default value None if not specified)
+                    continue
                 if value in duration_options:
                     time = self._convert_duration_to_nanosecond(self.healthcheck.get(value))
                     if time:
@@ -1539,7 +1617,7 @@ class TaskParameters(DockerBaseClass):
         devices_list = []
         for v in getattr(self, option):
             device_dict = dict((x.title(), y) for x, y in v.items())
-            device_dict['Rate'] = human_to_bytes(device_dict.get('Rate', 0))
+            device_dict['Rate'] = human_to_bytes(device_dict['Rate'])
             devices_list.append(device_dict)
 
         setattr(self, option, devices_list)
@@ -1550,12 +1628,8 @@ class TaskParameters(DockerBaseClass):
         """
         devices_list = []
         for v in getattr(self, option):
-            try:
             device_dict = dict((x.title(), y) for x, y in v.items())
-                device_dict['Rate'] = int(device_dict.get('Rate', 0))
             devices_list.append(device_dict)
-            except ValueError:
-                self.fail("Invalid device iops value: '{0}'. Must be a positive integer.".format(device_dict.get('Rate')))
 
         setattr(self, option, devices_list)
 
@@ -1866,20 +1940,14 @@ class Container(DockerBaseClass):
                     diff = True
                 if network.get('ipv6_address') and network['ipv6_address'] != connected_networks[network['name']].get('GlobalIPv6Address'):
                     diff = True
-                if network.get('aliases') and not connected_networks[network['name']].get('Aliases'):
+                if network.get('aliases'):
+                    if not compare_generic(network['aliases'], connected_networks[network['name']].get('Aliases'), 'allow_more_present', 'set'):
                         diff = True
-                if network.get('aliases') and connected_networks[network['name']].get('Aliases'):
-                    for alias in network.get('aliases'):
-                        if alias not in connected_networks[network['name']].get('Aliases', []):
-                            diff = True
-                if network.get('links') and not connected_networks[network['name']].get('Links'):
-                    diff = True
-                if network.get('links') and connected_networks[network['name']].get('Links'):
+                if network.get('links'):
                     expected_links = []
                     for link, alias in network['links']:
                         expected_links.append("%s:%s" % (link, alias))
-                    for link in expected_links:
-                        if link not in connected_networks[network['name']].get('Links', []):
+                    if not compare_generic(expected_links, connected_networks[network['name']].get('Links'), 'allow_more_present', 'set'):
                         diff = True
                 if diff:
                     different = True
@@ -2723,8 +2791,8 @@ def main():
     argument_spec = dict(
         auto_remove=dict(type='bool', default=False),
         blkio_weight=dict(type='int'),
-        capabilities=dict(type='list'),
-        cap_drop=dict(type='list'),
+        capabilities=dict(type='list', elements='str'),
+        cap_drop=dict(type='list', elements='str'),
         cleanup=dict(type='bool', default=False),
         command=dict(type='raw'),
         comparisons=dict(type='dict'),
@@ -2734,23 +2802,41 @@ def main():
         cpuset_mems=dict(type='str'),
         cpu_shares=dict(type='int'),
         detach=dict(type='bool', default=True),
-        devices=dict(type='list'),
-        device_read_bps=dict(type='list'),
-        device_write_bps=dict(type='list'),
-        device_read_iops=dict(type='list'),
-        device_write_iops=dict(type='list'),
-        dns_servers=dict(type='list'),
-        dns_opts=dict(type='list'),
-        dns_search_domains=dict(type='list'),
+        devices=dict(type='list', elements='str'),
+        device_read_bps=dict(type='list', elements='dict', options=dict(
+            path=dict(required=True, type='str'),
+            rate=dict(required=True, type='str'),
+        )),
+        device_write_bps=dict(type='list', elements='dict', options=dict(
+            path=dict(required=True, type='str'),
+            rate=dict(required=True, type='str'),
+        )),
+        device_read_iops=dict(type='list', elements='dict', options=dict(
+            path=dict(required=True, type='str'),
+            rate=dict(required=True, type='int'),
+        )),
+        device_write_iops=dict(type='list', elements='dict', options=dict(
+            path=dict(required=True, type='str'),
+            rate=dict(required=True, type='int'),
+        )),
+        dns_servers=dict(type='list', elements='str'),
+        dns_opts=dict(type='list', elements='str'),
+        dns_search_domains=dict(type='list', elements='str'),
         domainname=dict(type='str'),
-        entrypoint=dict(type='list'),
+        entrypoint=dict(type='list', elements='str'),
         env=dict(type='dict'),
         env_file=dict(type='path'),
         etc_hosts=dict(type='dict'),
-        exposed_ports=dict(type='list', aliases=['exposed', 'expose']),
+        exposed_ports=dict(type='list', aliases=['exposed', 'expose'], elements='str'),
         force_kill=dict(type='bool', default=False, aliases=['forcekill']),
-        groups=dict(type='list'),
-        healthcheck=dict(type='dict'),
+        groups=dict(type='list', elements='str'),
+        healthcheck=dict(type='dict', options=dict(
+            test=dict(type='raw'),
+            interval=dict(type='str'),
+            timeout=dict(type='str'),
+            start_period=dict(type='str'),
+            retries=dict(type='int'),
+        )),
         hostname=dict(type='str'),
         ignore_image=dict(type='bool', default=False),
         image=dict(type='str'),
@@ -2761,7 +2847,7 @@ def main():
         kernel_memory=dict(type='str'),
         kill_signal=dict(type='str'),
         labels=dict(type='dict'),
-        links=dict(type='list'),
+        links=dict(type='list', elements='str'),
         log_driver=dict(type='str'),
         log_options=dict(type='dict', aliases=['log_opt']),
         mac_address=dict(type='str'),
@@ -2771,14 +2857,20 @@ def main():
         memory_swappiness=dict(type='int'),
         name=dict(type='str', required=True),
         network_mode=dict(type='str'),
-        networks=dict(type='list'),
+        networks=dict(type='list', elements='dict', options=dict(
+            name=dict(required=True, type='str'),
+            ipv4_address=dict(type='str'),
+            ipv6_address=dict(type='str'),
+            aliases=dict(type='list', elements='str'),
+            links=dict(type='list', elements='str'),
+        )),
         oom_killer=dict(type='bool'),
         oom_score_adj=dict(type='int'),
         output_logs=dict(type='bool', default=False),
         paused=dict(type='bool', default=False),
         pid_mode=dict(type='str'),
         privileged=dict(type='bool', default=False),
-        published_ports=dict(type='list', aliases=['ports']),
+        published_ports=dict(type='list', aliases=['ports'], elements='str'),
         pull=dict(type='bool', default=False),
         purge_networks=dict(type='bool', default=False),
         read_only=dict(type='bool', default=False),
@@ -2787,22 +2879,22 @@ def main():
         restart_policy=dict(type='str', choices=['no', 'on-failure', 'always', 'unless-stopped']),
         restart_retries=dict(type='int', default=None),
         runtime=dict(type='str', default=None),
-        security_opts=dict(type='list'),
+        security_opts=dict(type='list', elements='str'),
         shm_size=dict(type='str'),
         state=dict(type='str', choices=['absent', 'present', 'started', 'stopped'], default='started'),
         stop_signal=dict(type='str'),
         stop_timeout=dict(type='int'),
         sysctls=dict(type='dict'),
-        tmpfs=dict(type='list'),
+        tmpfs=dict(type='list', elements='str'),
         trust_image_content=dict(type='bool', default=False),
         tty=dict(type='bool', default=False),
-        ulimits=dict(type='list'),
+        ulimits=dict(type='list', elements='str'),
         user=dict(type='str'),
         userns_mode=dict(type='str'),
         uts=dict(type='str'),
         volume_driver=dict(type='str'),
-        volumes=dict(type='list'),
-        volumes_from=dict(type='list'),
+        volumes=dict(type='list', elements='str'),
+        volumes_from=dict(type='list', elements='str'),
         working_dir=dict(type='str'),
     )
 

lib/ansible/modules/cloud/docker/docker_image.py

@@ -583,7 +583,12 @@ class ImageManager(DockerBaseClass):
 def main():
     argument_spec = dict(
         archive_path=dict(type='path'),
-        container_limits=dict(type='dict'),
+        container_limits=dict(type='dict', options=dict(
+            memory=dict(type='int'),
+            memswap=dict(type='int'),
+            cpushares=dict(type='int'),
+            cpusetcpus=dict(type='str'),
+        )),
         dockerfile=dict(type='str'),
         force=dict(type='bool', default=False),
         http_timeout=dict(type='int'),

lib/ansible/modules/cloud/docker/docker_image_facts.py

@@ -227,7 +227,7 @@ class ImageManager(DockerBaseClass):
 
 def main():
     argument_spec = dict(
-        name=dict(type='list'),
+        name=dict(type='list', elements='str'),
     )
 
     client = AnsibleDockerClient(

lib/ansible/modules/cloud/docker/docker_network.py

@@ -77,7 +77,7 @@ options:
   ipam_options:
     description:
       - Dictionary of IPAM options.
-      - Deprecated in 2.8, will be removed in 2.12. Use parameter ``ipam_config`` instead. In Docker 1.10.0, IPAM
+      - Deprecated in 2.8, will be removed in 2.12. Use parameter C(ipam_config) instead. In Docker 1.10.0, IPAM
         options were introduced (see L(here,https://github.com/moby/moby/pull/17316)). This module parameter addresses
         the IPAM config not the newly introduced IPAM options.
 
@@ -86,9 +86,27 @@ options:
     description:
       - List of IPAM config blocks. Consult
         L(Docker docs,https://docs.docker.com/compose/compose-file/compose-file-v2/#ipam) for valid options and values.
+        Note that I(iprange) is spelled differently here (we use the notation from the Docker Python SDK).
     type: list
     default: null
     required: false
+    suboptions:
+      subnet:
+        description:
+          - IP subset in CIDR notation.
+        type: str
+      iprange:
+        description:
+          - IP address range in CIDR notation.
+        type: str
+      gateway:
+        description:
+          - IP gateway address.
+        type: str
+      aux_addresses:
+        description:
+          - Auxiliary IP addresses used by Network driver, as a mapping from hostname to IP.
+        type: dict
 
   state:
     description:
@@ -300,7 +318,8 @@ class DockerNetworkManager(object):
         if not self.parameters.connected and self.existing_network:
             self.parameters.connected = container_names_in_network(self.existing_network)
 
-        if self.parameters.ipam_options:
+        if (self.parameters.ipam_options['subnet'] or self.parameters.ipam_options['iprange'] or
+                self.parameters.ipam_options['gateway'] or self.parameters.ipam_options['aux_addresses']):
             self.parameters.ipam_config = [self.parameters.ipam_options]
 
         if self.parameters.driver_options:
@@ -362,6 +381,10 @@ class DockerNetworkManager(object):
                         self.client.fail(str(e))
 
                     for key, value in ipam_config.items():
+                        if value is None:
+                            # due to recursive argument_spec, all keys are always present
+                            # (but have default value None if not specified)
+                            continue
                         camelkey = None
                         for net_key in net_config:
                             if key == net_key.lower():
@@ -493,15 +516,25 @@ class DockerNetworkManager(object):
 def main():
     argument_spec = dict(
         network_name=dict(type='str', required=True, aliases=['name']),
-        connected=dict(type='list', default=[], aliases=['containers']),
+        connected=dict(type='list', default=[], aliases=['containers'], elements='str'),
         state=dict(type='str', default='present', choices=['present', 'absent']),
         driver=dict(type='str', default='bridge'),
         driver_options=dict(type='dict', default={}),
         force=dict(type='bool', default=False),
         appends=dict(type='bool', default=False, aliases=['incremental']),
         ipam_driver=dict(type='str'),
-        ipam_options=dict(type='dict', default={}, removed_in_version='2.12'),
-        ipam_config=dict(type='list', elements='dict'),
+        ipam_options=dict(type='dict', default={}, removed_in_version='2.12', options=dict(
+            subnet=dict(type='str'),
+            iprange=dict(type='str'),
+            gateway=dict(type='str'),
+            aux_addresses=dict(type='dict'),
+        )),
+        ipam_config=dict(type='list', elements='dict', options=dict(
+            subnet=dict(type='str'),
+            iprange=dict(type='str'),
+            gateway=dict(type='str'),
+            aux_addresses=dict(type='dict'),
+        )),
         enable_ipv6=dict(type='bool'),
         internal=dict(type='bool'),
         debug=dict(type='bool', default=False)

lib/ansible/modules/cloud/docker/docker_service.py

@@ -1033,7 +1033,7 @@ def main():
     argument_spec = dict(
         project_src=dict(type='path'),
         project_name=dict(type='str',),
-        files=dict(type='list'),
+        files=dict(type='list', elements='path'),
         state=dict(type='str', choices=['absent', 'present'], default='present'),
         definition=dict(type='dict'),
         hostname_check=dict(type='bool', default=False),
@@ -1045,7 +1045,7 @@ def main():
         stopped=dict(type='bool', default=False),
         restarted=dict(type='bool', default=False),
         scale=dict(type='dict'),
-        services=dict(type='list'),
+        services=dict(type='list', elements='str'),
         dependencies=dict(type='bool', default=True),
         pull=dict(type='bool', default=False),
         nocache=dict(type='bool', default=False),

lib/ansible/modules/cloud/docker/docker_swarm.py

@@ -475,7 +475,7 @@ def main():
         state=dict(type='str', choices=['present', 'join', 'absent', 'remove', 'inspect'], default='present'),
         force=dict(type='bool', default=False),
         listen_addr=dict(type='str', default='0.0.0.0:2377'),
-        remote_addrs=dict(type='list'),
+        remote_addrs=dict(type='list', elements='str'),
         join_token=dict(type='str'),
         snapshot_interval=dict(type='int'),
         task_history_retention_limit=dict(type='int'),

test/integration/targets/docker_container/tasks/tests/options.yml

@@ -709,7 +709,7 @@
     state: started
     device_read_iops:
       - path: /dev/urandom
-        rate: 20
+        rate: "20"
       - path: /dev/random
         rate: 10
   register: device_read_iops_2