docker modules: add missing option types (#52422)

* Add missing option types for docker modules.

* Reorder argument_spec.

* First part of option reordering/reformatting.

* Second part of option reordering/reformatting.

* Forgot two required: false.

* Normalize booleans.

* Added missing period.

lib/ansible/module_utils/docker/common.py

@@ -78,9 +78,9 @@ MIN_DOCKER_VERSION = "1.8.0"
 DEFAULT_TIMEOUT_SECONDS = 60
 
 DOCKER_COMMON_ARGS = dict(
-    docker_host=dict(type='str', aliases=['docker_url'], default=DEFAULT_DOCKER_HOST, fallback=(env_fallback, ['DOCKER_HOST'])),
+    docker_host=dict(type='str', default=DEFAULT_DOCKER_HOST, fallback=(env_fallback, ['DOCKER_HOST']), aliases=['docker_url']),
     tls_hostname=dict(type='str', default=DEFAULT_TLS_HOSTNAME, fallback=(env_fallback, ['DOCKER_TLS_HOSTNAME'])),
-    api_version=dict(type='str', aliases=['docker_api_version'], default='auto', fallback=(env_fallback, ['DOCKER_API_VERSION'])),
+    api_version=dict(type='str', default='auto', fallback=(env_fallback, ['DOCKER_API_VERSION']), aliases=['docker_api_version']),
     timeout=dict(type='int', default=DEFAULT_TIMEOUT_SECONDS, fallback=(env_fallback, ['DOCKER_TIMEOUT'])),
     cacert_path=dict(type='path', aliases=['tls_ca_cert']),
     cert_path=dict(type='path', aliases=['tls_client_cert']),

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

@@ -36,55 +36,62 @@ options:
       - Path to a directory containing a docker-compose.yml or docker-compose.yaml file.
       - Mutually exclusive with C(definition).
       - Required when no C(definition) is provided.
+    type: path
   project_name:
     description:
       - Provide a project name. If not provided, the project name is taken from the basename of C(project_src).
       - Required when C(definition) is provided.
+    type: str
   files:
     description:
       - List of file names relative to C(project_src). Overrides docker-compose.yml or docker-compose.yaml.
       - Files are loaded and merged in the order given.
+    type: list
   state:
     description:
       - Desired state of the project.
       - Specifying I(present) is the same as running I(docker-compose up).
       - Specifying I(absent) is the same as running I(docker-compose down).
+    type: str
+    default: present
     choices:
       - absent
       - present
-      default: present
   services:
     description:
       - When C(state) is I(present) run I(docker-compose up) on a subset of services.
+    type: list
   scale:
     description:
       - When C(state) is I(present) scale services. Provide a dictionary of key/value pairs where the key
         is the name of the service and the value is an integer count for the number of containers.
+    type: dict
   dependencies:
     description:
       - When C(state) is I(present) specify whether or not to include linked services.
     type: bool
-      default: 'yes'
+    default: yes
   definition:
     description:
       - Provide docker-compose yaml describing one or more services, networks and volumes.
       - Mutually exclusive with C(project_src) and C(files).
+    type: dict
   hostname_check:
     description:
       - Whether or not to check the Docker daemon's hostname against the name provided in the client certificate.
     type: bool
-      default: 'no'
+    default: no
   recreate:
     description:
       - By default containers will be recreated when their configuration differs from the service definition.
       - Setting to I(never) ignores configuration differences and leaves existing containers unchanged.
       - Setting to I(always) forces recreation of all existing containers.
-      required: false
+    type: str
+    default: smart
     choices:
       - always
       - never
       - smart
-      default: smart
   build:
     description:
       - Use with state I(present) to always build images prior to starting the application.
@@ -93,24 +100,25 @@ options:
       - Use the C(nocache) option to ignore the image cache when performing the build.
       - If an existing image is replaced, services using the image will be recreated unless C(recreate) is I(never).
     type: bool
-      default: 'no'
+    default: no
   pull:
     description:
       - Use with state I(present) to always pull images prior to starting the application.
       - Same as running docker-compose pull.
       - When a new image is pulled, services using the image will be recreated unless C(recreate) is I(never).
     type: bool
-      default: 'no'
+    default: no
     version_added: "2.2"
   nocache:
     description:
       - Use with the build option to ignore the cache during the image build process.
     type: bool
-      default: 'no'
+    default: no
     version_added: "2.2"
   remove_images:
     description:
       - Use with state I(absent) to remove the all images or only local images.
+    type: str
     choices:
         - 'all'
         - 'local'
@@ -118,25 +126,26 @@ options:
     description:
       - Use with state I(absent) to remove data volumes.
     type: bool
-      default: 'no'
+    default: no
   stopped:
     description:
       - Use with state I(present) to leave the containers in an exited or non-running state.
     type: bool
-      default: 'no'
+    default: no
   restarted:
     description:
       - Use with state I(present) to restart all containers.
     type: bool
-      default: 'no'
+    default: no
   remove_orphans:
     description:
       - Remove containers for services not defined in the compose file.
     type: bool
-      default: false
+    default: no
   timeout:
     description:
         - timeout in seconds for container shutdown when attached or when containers are already running.
+    type: int
     default: 10
 
 extends_documentation_fragment:
@@ -1033,10 +1042,10 @@ def main():
         project_src=dict(type='path'),
         project_name=dict(type='str',),
         files=dict(type='list', elements='path'),
-        state=dict(type='str', choices=['absent', 'present'], default='present'),
+        state=dict(type='str', default='present', choices=['absent', 'present']),
         definition=dict(type='dict'),
         hostname_check=dict(type='bool', default=False),
-        recreate=dict(type='str', choices=['always', 'never', 'smart'], default='smart'),
+        recreate=dict(type='str', default='smart', choices=['always', 'never', 'smart']),
         build=dict(type='bool', default=False),
         remove_images=dict(type='str', choices=['all', 'local']),
         remove_volumes=dict(type='bool', default=False),

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

@@ -30,7 +30,6 @@ options:
   data:
     description:
       - The value of the config. Required when state is C(present).
-    required: false
     type: str
   data_is_b64:
     description:
@@ -38,29 +37,28 @@ options:
         decoded before being used.
       - To use binary C(data), it is better to keep it Base64 encoded and let it
         be decoded by this option.
-    default: false
     type: bool
+    default: no
   labels:
     description:
       - "A map of key:value meta data, where both the I(key) and I(value) are expected to be a string."
       - If new meta data is provided, or existing meta data is modified, the config will be updated by removing it and creating it again.
-    required: false
     type: dict
   force:
     description:
       - Use with state C(present) to always remove and recreate an existing config.
       - If I(true), an existing config will be replaced, even if it has not been changed.
-    default: false
     type: bool
+    default: no
   name:
     description:
       - The name of the config.
-    required: true
     type: str
+    required: yes
   state:
     description:
       - Set to C(present), if the config should exist, and C(absent), if it should not.
-    required: false
+    type: str
     default: present
     choices:
       - absent
@@ -264,7 +262,7 @@ class ConfigManager(DockerBaseClass):
 def main():
     argument_spec = dict(
         name=dict(type='str', required=True),
-        state=dict(type='str', choices=['absent', 'present'], default='present'),
+        state=dict(type='str', default='present', choices=['absent', 'present']),
         data=dict(type='str'),
         data_is_b64=dict(type='bool', default=False),
         labels=dict(type='dict'),

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

@@ -29,31 +29,34 @@ options:
     description:
       - enable auto-removal of the container on daemon side when the container's process exits
     type: bool
-    default: 'no'
+    default: no
     version_added: "2.4"
   blkio_weight:
     description:
       - Block IO (relative weight), between 10 and 1000.
+    type: int
   capabilities:
     description:
       - List of capabilities to add to the container.
+    type: list
   cap_drop:
     description:
       - List of capabilities to drop from the container.
+    type: list
     version_added: "2.7"
   cleanup:
     description:
       - Use with I(detach=false) to remove the container after successful execution.
     type: bool
-    default: 'no'
+    default: no
     version_added: "2.2"
   command:
     description:
       - Command to execute when the container starts.
         A command may be either a string or a list.
-        Prior to version 2.4, strings were split on commas.
+      - Prior to version 2.4, strings were split on commas.
+    type: raw
   comparisons:
-    type: dict
     description:
       - Allows to specify how properties of existing containers are compared with
         module options to decide whether the container should be recreated / updated
@@ -72,50 +75,57 @@ options:
       - The wildcard option C(*) can be used to set one of the default values C(strict)
         or C(ignore) to I(all) comparisons.
       - See the examples for details.
+    type: dict
     version_added: "2.8"
   cpu_period:
     description:
       - Limit CPU CFS (Completely Fair Scheduler) period
+    type: int
   cpu_quota:
     description:
       - Limit CPU CFS (Completely Fair Scheduler) quota
+    type: int
   cpuset_cpus:
     description:
       - CPUs in which to allow execution C(1,3) or C(1-3).
+    type: str
   cpuset_mems:
     description:
       - Memory nodes (MEMs) in which to allow execution C(0-3) or C(0,1)
+    type: str
   cpu_shares:
     description:
       - CPU shares (relative weight).
+    type: int
   detach:
     description:
       - Enable detached mode to leave the container running in background.
         If disabled, the task will reflect the status of the container run (failed if the command failed).
     type: bool
-    default: true
+    default: yes
   devices:
     description:
       - "List of host device bindings to add to the container. Each binding is a mapping expressed
         in the format: <path_on_host>:<path_in_container>:<cgroup_permissions>"
+    type: list
   device_read_bps:
     description:
       - "List of device path and read rate (bytes per second) from device."
     type: list
     suboptions:
       path:
-        type: str
-        required: true
         description:
         - Device path in the container.
-      rate:
         type: str
-        required: true
+        required: yes
+      rate:
         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."
+        type: str
+        required: yes
     version_added: "2.8"
   device_write_bps:
     description:
@@ -123,18 +133,18 @@ options:
     type: list
     suboptions:
       path:
-        type: str
-        required: true
         description:
         - Device path in the container.
-      rate:
         type: str
-        required: true
+        required: yes
+      rate:
         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."
+        type: str
+        required: yes
     version_added: "2.8"
   device_read_iops:
     description:
@@ -142,16 +152,16 @@ options:
     type: list
     suboptions:
       path:
-        type: str
-        required: true
         description:
         - Device path in the container.
+        type: str
+        required: yes
       rate:
-        type: int
-        required: true
         description:
         - "Device read limit."
         - "Must be a positive integer."
+        type: int
+        required: yes
     version_added: "2.8"
   device_write_iops:
     description:
@@ -159,29 +169,33 @@ options:
     type: list
     suboptions:
       path:
-        type: str
-        required: true
         description:
         - Device path in the container.
+        type: str
+        required: yes
       rate:
-        type: int
-        required: true
         description:
         - "Device read limit."
         - "Must be a positive integer."
+        type: int
+        required: yes
     version_added: "2.8"
   dns_opts:
     description:
       - list of DNS options
+    type: list
   dns_servers:
     description:
       - List of custom DNS servers.
+    type: list
   dns_search_domains:
     description:
       - List of custom DNS search domains.
+    type: list
   domainname:
     description:
       - Container domainname.
+    type: str
     version_added: "2.5"
   env:
     description:
@@ -189,23 +203,27 @@ options:
       - Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (e.g. C("true")) in order to avoid data loss.
     type: dict
   env_file:
-    version_added: "2.2"
     description:
       - Path to a file, present on the target, containing environment variables I(FOO=BAR).
       - If variable also present in C(env), then C(env) value will override.
+    type: path
+    version_added: "2.2"
   entrypoint:
     description:
       - Command that overwrites the default ENTRYPOINT of the image.
+    type: list
   etc_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.
+    type: dict
   exposed_ports:
     description:
       - List of additional container ports which informs Docker that the container
         listens on the specified network ports at runtime.
         If the port is already exposed using EXPOSE in a Dockerfile, it does not
         need to be exposed again.
+    type: list
     aliases:
       - exposed
       - expose
@@ -213,26 +231,27 @@ options:
     description:
       - Use the kill command when stopping a running container.
     type: bool
-    default: 'no'
+    default: no
     aliases:
       - forcekill
   groups:
     description:
       - List of additional group names and/or IDs that the container process will run as.
+    type: list
   healthcheck:
-    version_added: "2.8"
-    type: dict
     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.'
       - '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)'
+    type: dict
     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).
+        type: raw
       interval:
         description:
           - 'Time between running the check. (default: 30s)'
@@ -249,9 +268,11 @@ options:
         description:
           - 'Start period for the container to initialize before starting health-retries countdown. (default: 0s)'
         type: str
+    version_added: "2.8"
   hostname:
     description:
       - Container hostname.
+    type: str
   ignore_image:
     description:
       - When C(state) is I(present) or I(started) the module compares the configuration of an existing
@@ -260,7 +281,7 @@ options:
         recreated. Stop this behavior by setting C(ignore_image) to I(True).
       - I(Warning:) This option is ignored if C(image) or C(*) is used for the C(comparisons) option.
     type: bool
-    default: 'no'
+    default: no
     version_added: "2.2"
   image:
     description:
@@ -268,63 +289,72 @@ options:
         will be pulled from the registry. If no tag is included, C(latest) will be used.
       - Can also be an image ID. If this is the case, the image is assumed to be available locally.
         The C(pull) option is ignored for this case.
+    type: str
   init:
     description:
       - Run an init inside the container that forwards signals and reaps processes.
         This option requires Docker API 1.25+.
     type: bool
-    default: 'no'
+    default: no
     version_added: "2.6"
   interactive:
     description:
       - Keep stdin open after a container is launched, even if not attached.
     type: bool
-    default: 'no'
+    default: no
   ipc_mode:
     description:
       - Set the IPC mode for the container. Can be one of 'container:<name|id>' to reuse another
         container's IPC namespace or 'host' to use the host's IPC namespace within the container.
+    type: str
   keep_volumes:
     description:
       - Retain volumes associated with a removed container.
     type: bool
-    default: 'yes'
+    default: yes
   kill_signal:
     description:
       - Override default signal used to kill a running container.
+    type: str
   kernel_memory:
     description:
       - "Kernel 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). Minimum is C(4M)."
       - Omitting the unit defaults to bytes.
+    type: str
   labels:
     description:
       - Dictionary of key value pairs.
+    type: dict
   links:
     description:
       - List of name aliases for linked containers in the format C(container_name:alias).
       - Setting this will force container to be restarted.
+    type: list
   log_driver:
     description:
       - Specify the logging driver. Docker uses I(json-file) by default.
       - See L(here,https://docs.docker.com/config/containers/logging/configure/) for possible choices.
-    required: false
+    type: str
   log_options:
     description:
       - Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/
         for details.
+    type: dict
     aliases:
       - log_opt
   mac_address:
     description:
       - Container MAC address (e.g. 92:d0:c6:0a:29:33)
+    type: str
   memory:
     description:
       - "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)."
       - Omitting the unit defaults to bytes.
+    type: str
     default: '0'
   memory_reservation:
     description:
@@ -332,27 +362,33 @@ options:
         Unit can be 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.
+    type: str
   memory_swap:
     description:
       - "Total memory limit (memory + swap, 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)."
       - Omitting the unit defaults to bytes.
+    type: str
   memory_swappiness:
     description:
         - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
         - If not set, the value will be remain the same if container exists and will be inherited from the host machine if it is (re-)created.
+    type: int
   name:
     description:
       - Assign a name to a new container or match an existing container.
       - When identifying an existing container name may be a name or a long or short container ID.
-    required: true
+    type: str
+    required: yes
   network_mode:
     description:
       - Connect the container to a network. Choices are "bridge", "host", "none" or "container:<name|id>"
+    type: str
   userns_mode:
     description:
       - Set the user namespace mode for the container. Currently, the only valid value is C(host).
+    type: str
     version_added: "2.5"
   networks:
     description:
@@ -362,31 +398,31 @@ options:
       - 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
+        required: yes
+      ipv4_address:
         description:
           - The container's IPv4 address in this network.
-        ipv6_address:
         type: str
+      ipv6_address:
         description:
           - The container's IPv6 address in this network.
+        type: str
       links:
-           type: list
         description:
           - A list of containers to link to.
-        aliases:
         type: list
+      aliases:
         description:
           - List of aliases for this container in this network. These names
             can be used in the network to reach this container.
+        type: list
+    version_added: "2.2"
   oom_killer:
     description:
       - Whether or not to disable OOM Killer for the container.
@@ -394,22 +430,24 @@ options:
   oom_score_adj:
     description:
       - An integer value containing the score given to the container in order to tune OOM killer preferences.
+    type: int
     version_added: "2.2"
   output_logs:
     description:
       - If set to true, output of the container command will be printed (only effective when log_driver is set to json-file or journald.
     type: bool
-    default: 'no'
+    default: no
     version_added: "2.7"
   paused:
     description:
       - Use with the started state to pause running processes inside the container.
     type: bool
-    default: 'no'
+    default: no
   pid_mode:
     description:
       - Set the PID namespace mode for the container.
       - Note that docker-py < 2.0 only supports 'host'. Newer versions allow all values supported by the docker daemon.
+    type: str
   pids_limit:
     description:
       - Set PIDs limit for the container. It accepts an integer value.
@@ -420,7 +458,7 @@ options:
     description:
       - Give extended privileges to the container.
     type: bool
-    default: 'no'
+    default: no
   published_ports:
     description:
       - List of ports to publish from the container to the host.
@@ -440,6 +478,7 @@ options:
         will be bound to the host IP pointed to by com.docker.network.bridge.host_binding_ipv4.
         Note that the first bridge network with a com.docker.network.bridge.host_binding_ipv4
         value encountered in the list of C(networks) is the one that will be used.
+    type: list
     aliases:
       - ports
   pull:
@@ -449,32 +488,33 @@ options:
        - I(Note) that images are only pulled when specified by name. If the image is specified
          as a image ID (hash), it cannot be pulled.
     type: bool
-    default: 'no'
+    default: no
   purge_networks:
     description:
        - Remove the container from ALL networks not included in C(networks) parameter.
        - Any default networks such as I(bridge), if not found in C(networks), will be removed as well.
     type: bool
-    default: 'no'
+    default: no
     version_added: "2.2"
   read_only:
     description:
       - Mount the container's root file system as read-only.
     type: bool
-    default: 'no'
+    default: no
   recreate:
     description:
       - Use with present and started states to force the re-creation of an existing container.
     type: bool
-    default: 'no'
+    default: no
   restart:
     description:
       - Use with started state to force a matching container to be stopped and restarted.
     type: bool
-    default: 'no'
+    default: no
   restart_policy:
     description:
       - Container restart policy. Place quotes around I(no) option.
+    type: str
     choices:
       - 'no'
       - 'on-failure'
@@ -483,9 +523,11 @@ options:
   restart_retries:
     description:
       - Use with restart policy to control maximum number of restart attempts.
+    type: int
   runtime:
     description:
       - Runtime to use for the container.
+    type: str
     version_added: "2.8"
   shm_size:
     description:
@@ -493,9 +535,11 @@ options:
         Unit can be 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. If you omit the size entirely, the system uses C(64M).
+    type: str
   security_opts:
     description:
       - List of security options in the form of C("label:user:User")
+    type: list
   state:
     description:
       - 'I(absent) - A container matching the specified name will be stopped and removed. Use force_kill to kill the container
@@ -517,6 +561,7 @@ options:
         with a removed container.'
       - 'I(stopped) - Asserts that the container is first I(present), and then if the container is running moves it to a stopped
         state. Use force_kill to kill a container rather than stopping it.'
+    type: str
     default: started
     choices:
       - absent
@@ -526,6 +571,7 @@ options:
   stop_signal:
     description:
       - Override default signal used to stop the container.
+    type: str
   stop_timeout:
     description:
       - Number of seconds to wait for the container to stop before sending SIGKILL.
@@ -536,34 +582,40 @@ options:
         the behavior depends on the version of docker. New versions of docker will
         always use the container's configured C(StopTimeout) value if it has been
         configured.
+    type: int
   trust_image_content:
     description:
       - If C(yes), skip image verification.
     type: bool
-    default: 'no'
+    default: no
   tmpfs:
     description:
       - Mount a tmpfs directory
+    type: list
     version_added: 2.4
   tty:
     description:
       - Allocate a pseudo-TTY.
     type: bool
-    default: 'no'
+    default: no
   ulimits:
     description:
       - "List of ulimit options. A ulimit is specified as C(nofile:262144:262144)"
+    type: list
   sysctls:
     description:
       - Dictionary of key,value pairs.
+    type: dict
     version_added: 2.4
   user:
     description:
       - Sets the username or UID used and optionally the groupname or GID for the specified command.
       - "Can be [ user | user:group | uid | uid:gid | user:gid | uid:group ]"
+    type: str
   uts:
     description:
       - Set the UTS namespace mode for the container.
+    type: str
   volumes:
     description:
       - List of volumes to mount within the container.
@@ -575,15 +627,19 @@ options:
         private label for the volume.
       - "Note that Ansible 2.7 and earlier only supported one mode, which had to be one of C(ro), C(rw),
         C(z), and C(Z)."
+    type: list
   volume_driver:
     description:
       - The container volume driver.
+    type: str
   volumes_from:
     description:
       - List of container names or Ids to get volumes from.
+    type: list
   working_dir:
     description:
       - Path to the working directory.
+    type: str
     version_added: "2.4"
 extends_documentation_fragment:
   - docker
@@ -2794,7 +2850,7 @@ def main():
         env=dict(type='dict'),
         env_file=dict(type='path'),
         etc_hosts=dict(type='dict'),
-        exposed_ports=dict(type='list', aliases=['exposed', 'expose'], elements='str'),
+        exposed_ports=dict(type='list', elements='str', aliases=['exposed', 'expose']),
         force_kill=dict(type='bool', default=False, aliases=['forcekill']),
         groups=dict(type='list', elements='str'),
         healthcheck=dict(type='dict', options=dict(
@@ -2825,7 +2881,7 @@ def main():
         name=dict(type='str', required=True),
         network_mode=dict(type='str'),
         networks=dict(type='list', elements='dict', options=dict(
-            name=dict(required=True, type='str'),
+            name=dict(type='str', required=True),
             ipv4_address=dict(type='str'),
             ipv6_address=dict(type='str'),
             aliases=dict(type='list', elements='str'),
@@ -2838,18 +2894,18 @@ def main():
         pid_mode=dict(type='str'),
         pids_limit=dict(type='int'),
         privileged=dict(type='bool', default=False),
-        published_ports=dict(type='list', aliases=['ports'], elements='str'),
+        published_ports=dict(type='list', elements='str', aliases=['ports']),
         pull=dict(type='bool', default=False),
         purge_networks=dict(type='bool', default=False),
         read_only=dict(type='bool', default=False),
         recreate=dict(type='bool', default=False),
         restart=dict(type='bool', default=False),
         restart_policy=dict(type='str', choices=['no', 'on-failure', 'always', 'unless-stopped']),
-        restart_retries=dict(type='int', default=None),
+        restart_retries=dict(type='int'),
-        runtime=dict(type='str', default=None),
+        runtime=dict(type='str'),
         security_opts=dict(type='list', elements='str'),
         shm_size=dict(type='str'),
-        state=dict(type='str', choices=['absent', 'present', 'started', 'stopped'], default='started'),
+        state=dict(type='str', default='started', choices=['absent', 'present', 'started', 'stopped']),
         stop_signal=dict(type='str'),
         stop_timeout=dict(type='int'),
         sysctls=dict(type='dict'),

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

@@ -30,7 +30,8 @@ options:
     description:
       - The name of the container to inspect.
       - When identifying an existing container name may be a name or a long or short container ID.
-    required: true
+    type: str
+    required: yes
 extends_documentation_fragment:
   - docker
   - docker.docker_py_1_documentation

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

@@ -28,88 +28,83 @@ options:
   archive_path:
     description:
       - Use with state C(present) to archive an image to a .tar file.
-    required: false
+    type: path
     version_added: "2.1"
   cache_from:
     description:
       - List of image names to consider as cache source.
-    required: false
     type: list
     version_added: "2.8"
   load_path:
     description:
       - Use with state C(present) to load an image from a .tar file.
-    required: false
+    type: path
     version_added: "2.2"
   dockerfile:
     description:
       - Use with state C(present) to provide an alternate name for the Dockerfile to use when building an image.
-    required: false
+    type: str
     version_added: "2.0"
   force:
     description:
       - Use with state I(absent) to un-tag and remove all images matching the specified name. Use with state
         C(present) to build, load or pull an image when the image already exists.
-    default: false
-    required: false
-    version_added: "2.1"
     type: bool
+    default: no
+    version_added: "2.1"
   http_timeout:
     description:
       - Timeout for HTTP requests during the image build operation. Provide a positive integer value for the number of
         seconds.
-    required: false
+    type: int
     version_added: "2.1"
   name:
     description:
       - "Image name. Name format will be one of: name, repository/name, registry_server:port/name.
         When pushing or pulling an image the name can optionally include the tag by appending ':tag_name'."
       - Note that image IDs (hashes) are not supported.
-    required: true
+    type: str
+    required: yes
   path:
     description:
       - Use with state 'present' to build an image. Will be the path to a directory containing the context and
         Dockerfile for building an image.
+    type: path
     aliases:
       - build_path
-    required: false
   pull:
     description:
       - When building an image downloads any updates to the FROM image in Dockerfile.
-    default: true
-    required: false
-    version_added: "2.1"
     type: bool
+    default: yes
+    version_added: "2.1"
   push:
     description:
       - Push the image to the registry. Specify the registry as part of the I(name) or I(repository) parameter.
-    default: false
-    required: false
-    version_added: "2.2"
     type: bool
+    default: no
+    version_added: "2.2"
   rm:
     description:
       - Remove intermediate containers after build.
-    default: true
-    required: false
-    version_added: "2.1"
     type: bool
+    default: yes
+    version_added: "2.1"
   network:
     description:
       - The network to use for C(RUN) build instructions.
-    required: false
+    type: str
     version_added: "2.8"
   nocache:
     description:
       - Do not use cache when building an image.
-    default: false
-    required: false
     type: bool
+    default: no
   repository:
     description:
       - Full path to a repository. Use with state C(present) to tag the image into the repository. Expects
         format I(repository:tag). If no tag is provided, will use the value of the C(tag) parameter or I(latest).
-    required: false
+    type: str
     version_added: "2.1"
   state:
     description:
@@ -123,7 +118,7 @@ options:
         repository, provide a repository path. If the name contains a repository path, it will be pushed.
       - "NOTE: C(build) is DEPRECATED and will be removed in release 2.11. Specifying C(build) will behave the
          same as C(present)."
-    required: false
+    type: str
     default: present
     choices:
       - absent
@@ -134,33 +129,37 @@ options:
       - Used to select an image when pulling. Will be added to the image when pushing, tagging or building. Defaults to
         I(latest).
       - If C(name) parameter format is I(name:tag), then tag value from C(name) will take precedence.
+    type: str
     default: latest
-    required: false
   buildargs:
     description:
       - Provide a dictionary of C(key:value) build arguments that map to Dockerfile ARG directive.
       - Docker expects the value to be a string. For convenience any non-string values will be converted to strings.
       - Requires Docker API >= 1.21.
-    required: false
+    type: dict
     version_added: "2.2"
   container_limits:
     description:
       - A dictionary of limits applied to each container created by the build process.
-    required: false
+    type: dict
-    version_added: "2.1"
     suboptions:
       memory:
         description:
           - Set memory limit for build.
+        type: int
       memswap:
         description:
           - Total memory (memory + swap), -1 to disable swap.
+        type: int
       cpushares:
         description:
           - CPU shares (relative weight).
+        type: int
       cpusetcpus:
         description:
           - CPUs in which to allow execution, e.g., "0-3", "0,1".
+        type: str
+    version_added: "2.1"
   use_tls:
     description:
       - "DEPRECATED. Whether to use tls to connect to the docker server. Set to
@@ -169,11 +168,11 @@ options:
       - "NOTE: If you specify this option, it will set the value of the I(tls) or
         I(tls_verify) parameters if not set to I(no)."
       - Will be removed in Ansible 2.11.
+    type: str
     choices:
       - 'no'
       - 'encrypt'
       - 'verify'
-    required: false
     version_added: "2.0"
 
 extends_documentation_fragment:
@@ -628,10 +627,10 @@ def main():
         push=dict(type='bool', default=False),
         repository=dict(type='str'),
         rm=dict(type='bool', default=True),
-        state=dict(type='str', choices=['absent', 'present', 'build'], default='present'),
+        state=dict(type='str', default='present', choices=['absent', 'present', 'build']),
         tag=dict(type='str', default='latest'),
         use_tls=dict(type='str', choices=['no', 'encrypt', 'verify'], removed_in_version='2.11'),
-        buildargs=dict(type='dict', default=None),
+        buildargs=dict(type='dict'),
     )
 
     option_minimal_versions = dict(

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

@@ -29,7 +29,8 @@ options:
       - An image name or a list of image names. Name format will be C(name[:tag]) or C(repository/name[:tag]),
         where C(tag) is optional. If a tag is not provided, C(latest) will be used. Instead of image names, also
         image IDs can be used.
-    required: true
+    type: list
+    required: yes
 
 extends_documentation_fragment:
   - docker

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

@@ -31,6 +31,7 @@ options:
     required: False
     description:
       - The registry URL.
+    type: str
     default: "https://index.docker.io/v1/"
     aliases:
       - registry
@@ -38,25 +39,29 @@ options:
   username:
     description:
       - The username for the registry account
-    required: True
+    type: str
+    required: yes
   password:
     description:
       - The plaintext password for the registry account
-    required: True
+    type: str
+    required: yes
   email:
     required: False
     description:
       - "The email address for the registry account."
+    type: str
   reauthorize:
     description:
       - Refresh existing authentication found in the configuration file.
     type: bool
-    default: 'no'
+    default: no
     aliases:
       - reauth
   config_path:
     description:
       - Custom path to the Docker CLI configuration file.
+    type: path
     default: ~/.docker/config.json
     aliases:
       - self.config_path
@@ -68,8 +73,9 @@ options:
       - To logout you only need the registry server, which defaults to DockerHub.
       - Before 2.1 you could ONLY log in.
       - docker does not support 'logout' with a custom config file.
-    choices: ['present', 'absent']
+    type: str
     default: 'present'
+    choices: ['present', 'absent']
 
 extends_documentation_fragment:
   - docker
@@ -287,9 +293,9 @@ class LoginManager(DockerBaseClass):
 def main():
 
     argument_spec = dict(
-        registry_url=dict(type='str', required=False, default=DEFAULT_DOCKER_REGISTRY, aliases=['registry', 'url']),
+        registry_url=dict(type='str', default=DEFAULT_DOCKER_REGISTRY, aliases=['registry', 'url']),
-        username=dict(type='str', required=False),
+        username=dict(type='str'),
-        password=dict(type='str', required=False, no_log=True),
+        password=dict(type='str', no_log=True),
         email=dict(type='str'),
         reauthorize=dict(type='bool', default=False, aliases=['reauth']),
         state=dict(type='str', default='present', choices=['present', 'absent']),

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

@@ -23,24 +23,28 @@ options:
   name:
     description:
       - Name of the network to operate on.
-    required: true
+    type: str
+    required: yes
     aliases:
       - network_name
 
   connected:
     description:
       - List of container names or container IDs to connect to a network.
+    type: list
     aliases:
       - containers
 
   driver:
     description:
       - Specify the type of network. Docker provides bridge and overlay drivers, but 3rd party drivers can also be used.
+    type: str
     default: bridge
 
   driver_options:
     description:
       - Dictionary of network settings. Consult docker docs for valid options and values.
+    type: dict
 
   force:
     description:
@@ -51,28 +55,27 @@ options:
         driver options and want an existing network to be updated to use the
         new options.
     type: bool
-    default: 'no'
+    default: no
 
   appends:
     description:
       - By default the connected list is canonical, meaning containers not on the list are removed from the network.
         Use C(appends) to leave existing containers connected.
     type: bool
-    default: 'no'
+    default: no
     aliases:
       - incremental
 
   enable_ipv6:
-    version_added: 2.8
     description:
       - Enable IPv6 networking.
     type: bool
-    default: null
+    version_added: 2.8
-    required: false
 
   ipam_driver:
     description:
       - Specify an IPAM driver.
+    type: str
 
   ipam_options:
     description:
@@ -80,16 +83,14 @@ options:
       - 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.
+    type: dict
 
   ipam_config:
-    version_added: 2.8
     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:
@@ -107,6 +108,7 @@ options:
         description:
           - Auxiliary IP addresses used by Network driver, as a mapping from hostname to IP.
         type: dict
+    version_added: 2.8
 
   state:
     description:
@@ -119,46 +121,39 @@ options:
         An empty list will leave no containers connected to the network. Use the
         C(appends) option to leave existing containers connected. Use the C(force)
         options to force re-creation of the network.
+    type: str
     default: present
     choices:
       - absent
       - present
 
   internal:
-    version_added: 2.8
     description:
       - Restrict external access to the network.
     type: bool
-    default: null
+    version_added: 2.8
-    required: false
 
   labels:
-    version_added: 2.8
     description:
       - Dictionary of labels.
     type: dict
-    default: null
+    version_added: 2.8
-    required: false
 
   scope:
-    version_added: 2.8
     description:
       - Specify the network's scope.
     type: str
-    default: null
-    required: false
     choices:
       - local
       - global
       - swarm
+    version_added: 2.8
 
   attachable:
-    version_added: 2.8
     description:
       - If enabled, and the network is in the global scope, non-service containers on worker nodes will be able to connect to the network.
     type: bool
-    default: null
+    version_added: 2.8
-    required: false
 
 extends_documentation_fragment:
   - docker
@@ -590,19 +585,19 @@ class DockerNetworkManager(object):
 def main():
     argument_spec = dict(
         network_name=dict(type='str', required=True, aliases=['name']),
-        connected=dict(type='list', default=[], aliases=['containers'], elements='str'),
+        connected=dict(type='list', default=[], elements='str', aliases=['containers']),
         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', options=dict(
+        ipam_options=dict(type='dict', default={}, options=dict(
             subnet=dict(type='str'),
             iprange=dict(type='str'),
             gateway=dict(type='str'),
             aux_addresses=dict(type='dict'),
-        )),
+        ), removed_in_version='2.12'),
         ipam_config=dict(type='list', elements='dict', options=dict(
             subnet=dict(type='str'),
             iprange=dict(type='str'),

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

@@ -30,7 +30,8 @@ options:
     description:
       - The name of the network to inspect.
       - When identifying an existing network name may be a name or a long or short network ID.
-    required: true
+    type: str
+    required: yes
 extends_documentation_fragment:
   - docker
   - docker.docker_py_1_documentation

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

@@ -25,14 +25,13 @@ options:
             - The hostname or ID of node as registered in Swarm.
             - If more than one node is registered using the same hostname the ID must be used,
               otherwise module will fail.
-        required: true
         type: str
+        required: yes
     labels:
         description:
             - User-defined key/value metadata that will be assigned as node attribute.
             - The actual state of labels assigned to the node when module completes its work depends on
               I(labels_state) and I(labels_to_remove) parameters values. See description below.
-        required: false
         type: dict
     labels_state:
         description:
@@ -43,12 +42,11 @@ options:
               If I(labels) is empty then no changes will be made.
             - Set to C(replace) to replace all assigned labels with provided ones. If I(labels) is empty then
               all labels assigned to the node will be removed.
+        type: str
+        default: 'merge'
         choices:
           - merge
           - replace
-        default: 'merge'
-        required: false
-        type: str
     labels_to_remove:
         description:
             - List of labels that will be removed from the node configuration. The list has to contain only label
@@ -58,7 +56,6 @@ options:
               assigned to the node.
             - If I(labels_state) is C(replace) and I(labels) is not provided or empty then all labels assigned to
               node are removed and I(labels_to_remove) is ignored.
-        required: false
         type: list
     availability:
         description: Node availability to assign. If not provided then node availability remains unchanged.
@@ -66,14 +63,12 @@ options:
           - active
           - pause
           - drain
-        required: false
         type: str
     role:
         description: Node role to assign. If not provided then node role remains unchanged.
         choices:
           - manager
           - worker
-        required: false
         type: str
 extends_documentation_fragment:
   - docker
@@ -262,7 +257,7 @@ def main():
     argument_spec = dict(
         hostname=dict(type='str', required=True),
         labels=dict(type='dict'),
-        labels_state=dict(type='str', choices=['merge', 'replace'], default='merge'),
+        labels_state=dict(type='str', default='merge', choices=['merge', 'replace']),
         labels_to_remove=dict(type='list', elements='str'),
         availability=dict(type='str', choices=['active', 'pause', 'drain']),
         role=dict(type='str', choices=['worker', 'manager']),

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

@@ -32,16 +32,14 @@ options:
       - If empty then return information of all nodes in Swarm cluster.
       - When identifying the node use either the hostname of the node (as registered in Swarm) or node ID.
       - If I(self) is C(true) then this parameter is ignored.
-    required: false
     type: list
   self:
     description:
       - If C(true), queries the node (i.e. the docker daemon) the module communicates with.
       - If C(true) then I(name) is ignored.
       - If C(false) then query depends on I(name) presence and value.
-    required: false
     type: bool
-    default: false
+    default: no
 extends_documentation_fragment:
   - docker
   - docker.docker_py_1_documentation
@@ -126,7 +124,7 @@ def get_node_facts(client):
 def main():
     argument_spec = dict(
         name=dict(type='list', elements='str'),
-        self=dict(type='bool', default='False'),
+        self=dict(type='bool', default=False),
     )
 
     client = AnsibleDockerSwarmClient(

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

@@ -30,7 +30,6 @@ options:
   data:
     description:
       - The value of the secret. Required when state is C(present).
-    required: false
     type: str
   data_is_b64:
     description:
@@ -38,30 +37,29 @@ options:
         decoded before being used.
       - To use binary C(data), it is better to keep it Base64 encoded and let it
         be decoded by this option.
-    default: false
     type: bool
+    default: no
     version_added: "2.8"
   labels:
     description:
       - "A map of key:value meta data, where both the I(key) and I(value) are expected to be a string."
       - If new meta data is provided, or existing meta data is modified, the secret will be updated by removing it and creating it again.
-    required: false
     type: dict
   force:
     description:
       - Use with state C(present) to always remove and recreate an existing secret.
       - If I(true), an existing secret will be replaced, even if it has not changed.
-    default: false
     type: bool
+    default: no
   name:
     description:
       - The name of the secret.
-    required: true
     type: str
+    required: yes
   state:
     description:
       - Set to C(present), if the secret should exist, and C(absent), if it should not.
-    required: false
+    type: str
     default: present
     choices:
       - absent
@@ -264,7 +262,7 @@ class SecretManager(DockerBaseClass):
 def main():
     argument_spec = dict(
         name=dict(type='str', required=True),
-        state=dict(type='str', choices=['absent', 'present'], default='present'),
+        state=dict(type='str', default='present', choices=['absent', 'present']),
         data=dict(type='str', no_log=True),
         data_is_b64=dict(type='bool', default=False),
         labels=dict(type='dict'),

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

@@ -19,58 +19,63 @@ author: "Dario Zanzico (@dariko)"
 short_description: docker stack module
 description:
   - Manage docker stacks using the 'docker stack' command
-    on the target node
+    on the target node (see examples).
-    (see examples)
 version_added: "2.8"
 options:
   name:
-        required: true
     description:
       - Stack name
+    type: str
+    required: yes
   state:
     description:
       - Service state.
+    type: str
     default: "present"
     choices:
       - present
       - absent
   compose:
-        default: []
     description:
       - List of compose definitions. Any element may be a string
         referring to the path of the compose file on the target host
         or the YAML contents of a compose file nested as dictionary.
+    type: list
+    default: []
   prune:
-        default: false
     description:
       - If true will add the C(--prune) option to the C(docker stack deploy) command.
         This will have docker remove the services not present in the
         current stack definition.
     type: bool
+    default: no
   with_registry_auth:
-        default: false
     description:
       - If true will add the C(--with-registry-auth) option to the C(docker stack deploy) command.
         This will have docker send registry authentication details to Swarm agents.
     type: bool
+    default: no
   resolve_image:
-        choices: ["always", "changed", "never"]
     description:
       - If set will add the C(--resolve-image) option to the C(docker stack deploy) command.
         This will have docker query the registry to resolve image digest and
         supported platforms. If not set, docker use "always" by default.
+    type: str
+    choices: ["always", "changed", "never"]
   absent_retries:
-        default: 0
     description:
       - If C(>0) and C(state==absent) the module will retry up to
         C(absent_retries) times to delete the stack until all the
         resources have been effectively deleted.
         If the last try still reports the stack as not completely
         removed the module will fail.
+    type: int
+    default: 0
   absent_retries_interval:
-        default: 1
     description:
       - Interval in seconds between C(absent_retries)
+    type: int
+    default: 1
 
 requirements:
   - jsondiff
@@ -204,12 +209,12 @@ def docker_stack_rm(module, stack_name, retries, interval):
 def main():
     module = AnsibleModule(
         argument_spec={
-            'name': dict(required=True, type='str'),
+            'name': dict(type='str', required=True),
-            'compose': dict(required=False, type='list', default=[]),
+            'compose': dict(type='list', default=[]),
-            'prune': dict(default=False, type='bool'),
+            'prune': dict(type='bool', default=False),
-            'with_registry_auth': dict(default=False, type='bool'),
+            'with_registry_auth': dict(type='bool', default=False),
             'resolve_image': dict(type='str', choices=['always', 'changed', 'never']),
-            'state': dict(default='present', choices=['present', 'absent']),
+            'state': dict(tpye='str', default='present', choices=['present', 'absent']),
             'absent_retries': dict(type='int', default=0),
             'absent_retries_interval': dict(type='int', default=1)
         },

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

@@ -29,6 +29,7 @@ options:
           the port number from the listen address is used.
       - If C(advertise_addr) is not specified, it will be automatically
           detected when possible.
+    type: str
   listen_addr:
     description:
       - Listen address used for inter-manager communication.
@@ -37,13 +38,14 @@ options:
           like C(eth0:4567).
       - If the port number is omitted, the default swarm listening port
           is used.
+    type: str
     default: 0.0.0.0:2377
   force:
     description:
       - Use with state C(present) to force creating a new Swarm, even if already part of one.
       - Use with state C(absent) to Leave the swarm even if this node is a manager.
     type: bool
-        default: 'no'
+    default: no
   state:
     description:
       - Set to C(present), to create/update a new cluster.
@@ -51,7 +53,8 @@ options:
       - Set to C(absent), to leave an existing cluster.
       - Set to C(remove), to remove an absent node from the cluster.
       - Set to C(inspect) to display swarm informations.
-        required: true
+    type: str
+    required: yes
     default: present
     choices:
       - present
@@ -63,62 +66,78 @@ options:
     description:
       - Swarm id of the node to remove.
       - Used with I(state=remove).
+    type: str
   join_token:
     description:
       - Swarm token used to join a swarm cluster.
       - Used with I(state=join).
+    type: str
   remote_addrs:
     description:
       - Remote address of a manager to connect to.
       - Used with I(state=join).
+    type: list
   task_history_retention_limit:
     description:
       - Maximum number of tasks history stored.
       - Docker default value is C(5).
+    type: int
   snapshot_interval:
     description:
       - Number of logs entries between snapshot.
       - Docker default value is C(10000).
+    type: int
   keep_old_snapshots:
     description:
       - Number of snapshots to keep beyond the current snapshot.
       - Docker default value is C(0).
+    type: int
   log_entries_for_slow_followers:
     description:
       - Number of log entries to keep around to sync up slow followers after a snapshot is created.
+    type: int
   heartbeat_tick:
     description:
       - Amount of ticks (in seconds) between each heartbeat.
       - Docker default value is C(1s).
+    type: int
   election_tick:
     description:
       - Amount of ticks (in seconds) needed without a leader to trigger a new election.
       - Docker default value is C(10s).
+    type: int
   dispatcher_heartbeat_period:
     description:
       - The delay for an agent to send a heartbeat to the dispatcher.
       - Docker default value is C(5s).
+    type: int
   node_cert_expiry:
     description:
       - Automatic expiry for nodes certificates.
       - Docker default value is C(3months).
+    type: int
   name:
     description:
       - The name of the swarm.
+    type: str
   labels:
     description:
       - User-defined key/value metadata.
+    type: dict
   signing_ca_cert:
     description:
       - The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format.
+    type: path
   signing_ca_key:
     description:
       - The desired signing CA key for all swarm node TLS leaf certificates, in PEM format.
+    type: path
   ca_force_rotate:
     description:
       - An integer whose purpose is to force swarm to generate a new signing CA certificate and key,
           if none have been specified.
       - Docker default value is C(0).
+    type: int
   autolock_managers:
     description:
       - If set, generate a key and use it to lock data stored on the managers.
@@ -127,11 +146,11 @@ options:
   rotate_worker_token:
     description: Rotate the worker join token.
     type: bool
-        default: 'no'
+    default: no
   rotate_manager_token:
     description: Rotate the manager join token.
     type: bool
-        default: 'no'
+    default: no
 extends_documentation_fragment:
   - docker
   - docker.docker_py_2_documentation
@@ -471,7 +490,7 @@ class SwarmManager(DockerBaseClass):
 def main():
     argument_spec = dict(
         advertise_addr=dict(type='str'),
-        state=dict(type='str', choices=['present', 'join', 'absent', 'remove', 'inspect'], default='present'),
+        state=dict(type='str', default='present', choices=['present', 'join', 'absent', 'remove', 'inspect']),
         force=dict(type='bool', default=False),
         listen_addr=dict(type='str', default='0.0.0.0:2377'),
         remote_addrs=dict(type='list', elements='str'),
@@ -486,8 +505,8 @@ def main():
         node_cert_expiry=dict(type='int'),
         name=dict(type='str'),
         labels=dict(type='dict'),
-        signing_ca_cert=dict(type='str'),
+        signing_ca_cert=dict(type='path'),
-        signing_ca_key=dict(type='str'),
+        signing_ca_key=dict(type='path'),
         ca_force_rotate=dict(type='int'),
         autolock_managers=dict(type='bool'),
         node_id=dict(type='str'),

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

@@ -14,34 +14,34 @@ DOCUMENTATION = '''
 module: docker_swarm_service
 author: "Dario Zanzico (@dariko), Jason Witkowski (@jwitko)"
 short_description: docker swarm service
-description: |
+description:
-  Manage docker services. Allows live altering of already defined services
+  - Manage docker services. Allows live altering of already defined services.
 version_added: "2.7"
 options:
   name:
-    required: true
-    type: str
     description:
       - Service name.
       - Corresponds to the C(--name) option of C(docker service create).
-  image:
-    required: true
     type: str
+    required: yes
+  image:
     description:
       - Service image path and tag.
       - Corresponds to the C(IMAGE) parameter of C(docker service create).
+    type: str
+    required: yes
   resolve_image:
-    type: bool
-    default: true
     description:
       - If the current image digest should be resolved from registry and updated if changed.
+    type: bool
+    default: yes
     version_added: 2.8
   state:
-    required: true
-    type: str
-    default: present
     description:
       - Service state.
+    type: str
+    required: yes
+    default: present
     choices:
       - present
       - absent
@@ -49,26 +49,27 @@ options:
     description:
       - List arguments to be passed to the container.
       - Corresponds to the C(ARG) parameter of C(docker service create).
+    type: list
   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
     version_added: 2.8
   constraints:
-    type: list
     description:
       - List of the service constraints.
       - Corresponds to the C(--constraint) option of C(docker service create).
-  placement_preferences:
     type: list
+  placement_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.
+    type: list
     version_added: 2.8
   healthcheck:
-    type: dict
     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)
@@ -76,93 +77,94 @@ options:
       - "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)."
       - Requires API version >= 1.25.
+    type: dict
     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).
+        type: raw
       interval:
-        type: str
         description:
           - Time between running the check.
-      timeout:
         type: str
+      timeout:
         description:
           - Maximum time to allow one check to run.
+        type: str
       retries:
-        type: int
         description:
           - Consecutive failures needed to report unhealthy. It accept integer value.
+        type: int
       start_period:
-        type: str
         description:
           - Start period for the container to initialize before starting health-retries countdown.
+        type: str
     version_added: "2.8"
   hostname:
-    type: str
     description:
       - Container hostname.
       - Corresponds to the C(--hostname) option of C(docker service create).
       - Requires API version >= 1.25.
+    type: str
   tty:
-    type: bool
     description:
       - Allocate a pseudo-TTY.
       - Corresponds to the C(--tty) option of C(docker service create).
       - Requires API version >= 1.25.
+    type: bool
   dns:
-    type: list
     description:
       - List of custom DNS servers.
       - Corresponds to the C(--dns) option of C(docker service create).
       - Requires API version >= 1.25.
-  dns_search:
     type: list
+  dns_search:
     description:
       - List of custom DNS search domains.
       - Corresponds to the C(--dns-search) option of C(docker service create).
       - Requires API version >= 1.25.
-  dns_options:
     type: list
+  dns_options:
     description:
       - List of custom DNS options.
       - Corresponds to the C(--dns-option) option of C(docker service create).
       - Requires API version >= 1.25.
+    type: list
   force_update:
-    type: bool
-    default: false
     description:
       - Force update even if no changes require it.
       - Corresponds to the C(--force) option of C(docker service update).
       - Requires API version >= 1.25.
+    type: bool
+    default: no
   groups:
-    type: list
     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).
       - Requires API version >= 1.25.
+    type: list
     version_added: "2.8"
   labels:
-    type: dict
     description:
       - Dictionary of key value pairs.
       - Corresponds to the C(--label) option of C(docker service create).
-  container_labels:
     type: dict
+  container_labels:
     description:
       - Dictionary of key value pairs.
       - Corresponds to the C(--container-label) option of C(docker service create).
+    type: dict
   endpoint_mode:
-    type: str
     description:
       - Service endpoint mode.
       - Corresponds to the C(--endpoint-mode) option of C(docker service create).
       - Requires API version >= 1.25.
+    type: str
     choices:
       - vip
       - dnsrr
   env:
-    type: raw
     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).
@@ -170,36 +172,36 @@ options:
         booleans or other types by the YAML parser must be quoted (e.g. C("true"))
         in order to avoid data loss.
       - Corresponds to the C(--env) option of C(docker service create).
+    type: raw
   env_files:
-    type: list
     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 I(env), then I(env) value will override.
+    type: list
     version_added: "2.8"
   log_driver:
-    type: str
     description:
       - Configure the logging driver for a service.
       - Corresponds to the C(--log-driver) option of C(docker service create).
+    type: str
   log_driver_options:
-    type: dict
     description:
       - Options for service logging driver.
       - Corresponds to the C(--log-opt) option of C(docker service create).
+    type: dict
   limit_cpu:
-    type: float
     description:
       - Service CPU limit. C(0) equals no limit.
       - Corresponds to the C(--limit-cpu) option of C(docker service create).
-  reserve_cpu:
     type: float
+  reserve_cpu:
     description:
       - Service CPU reservation. C(0) equals no reservation.
       - Corresponds to the C(--reserve-cpu) option of C(docker service create).
+    type: float
   limit_memory:
-    type: str
     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),
@@ -207,8 +209,8 @@ options:
       - C(0) equals no limit.
       - Omitting the unit defaults to bytes.
       - Corresponds to the C(--limit-memory) option of C(docker service create).
-  reserve_memory:
     type: str
+  reserve_memory:
     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),
@@ -216,241 +218,242 @@ options:
       - C(0) equals no reservation.
       - Omitting the unit defaults to bytes.
       - Corresponds to the C(--reserve-memory) option of C(docker service create).
-  mode:
     type: str
-    default: replicated
+  mode:
     description:
       - Service replication mode.
       - Corresponds to the C(--mode) option of C(docker service create).
+    type: str
+    default: replicated
   mounts:
-    type: list
     description:
       - List of dictionaries describing the service mounts.
       - Corresponds to the C(--mount) option of C(docker service create).
+    type: list
     suboptions:
       source:
-        type: str
-        required: true
         description:
           - Mount source (e.g. a volume name or a host path).
-      target:
         type: str
-        required: true
+        required: yes
+      target:
         description:
           - Container path.
+        type: str
+        required: yes
       type:
+        description:
+          - The mount type.
         type: str
         default: bind
         choices:
           - bind
           - volume
           - tmpfs
-        description:
-          - The mount type.
       readonly:
-        type: bool
-        default: false
         description:
           - Whether the mount should be read-only.
+        type: bool
+        default: no
   secrets:
-    type: list
     description:
       - List of dictionaries describing the service secrets.
       - Corresponds to the C(--secret) option of C(docker service create).
       - Requires API version >= 1.25.
+    type: list
     suboptions:
       secret_id:
-        type: str
-        required: true
         description:
           - Secret's ID.
-      secret_name:
         type: str
-        required: true
+        required: yes
+      secret_name:
         description:
           - Secret's name as defined at its creation.
-      filename:
         type: str
+        required: yes
+      filename:
         description:
           - Name of the file containing the secret. Defaults to the I(secret_name) if not specified.
+        type: str
       uid:
-        type: int
-        default: 0
         description:
           - UID of the secret file's owner.
-      gid:
         type: int
         default: 0
+      gid:
         description:
           - GID of the secret file's group.
-      mode:
         type: int
-        default: 0o444
+        default: 0
+      mode:
         description:
           - File access mode inside the container.
+        type: int
+        default: 0o444
   configs:
-    type: list
     description:
       - List of dictionaries describing the service configs.
       - Corresponds to the C(--config) option of C(docker service create).
       - Requires API version >= 1.30.
+    type: list
     suboptions:
       config_id:
-        type: str
-        required: true
         description:
           - Config's ID.
-      config_name:
         type: str
-        required: true
+        required: yes
+      config_name:
         description:
           - Config's name as defined at its creation.
-      filename:
         type: str
-        required: true
+        required: yes
+      filename:
         description:
           - Name of the file containing the config. Defaults to the I(config_name) if not specified.
+        type: str
+        required: yes
       uid:
-        type: int
-        default: 0
         description:
           - UID of the config file's owner.
-      gid:
         type: int
         default: 0
+      gid:
         description:
           - GID of the config file's group.
+        type: int
+        default: 0
       mode:
-        type: str
-        default: "0o444"
         description:
           - File access mode inside the container.
+        type: str
+        default: "0o444"
   networks:
-    type: list
     description:
       - List of the service networks names.
       - Corresponds to the C(--network) option of C(docker service create).
+    type: list
   stop_signal:
-    type: str
     description:
       - Override default signal used to stop the container.
       - Corresponds to the C(--stop-signal) option of C(docker service create).
+    type: str
     version_added: "2.8"
   publish:
-    type: list
     description:
       - List of dictionaries describing the service published ports.
       - Corresponds to the C(--publish) option of C(docker service create).
       - Requires API version >= 1.25.
+    type: list
     suboptions:
       published_port:
-        type: int
-        required: true
         description:
           - The port to make externally available.
-      target_port:
         type: int
-        required: true
+        required: yes
+      target_port:
         description:
           - The port inside the container to expose.
+        type: int
+        required: yes
       protocol:
-        type: str
-        default: tcp
         description:
           - What protocol to use.
+        type: str
+        default: tcp
         choices:
           - tcp
           - udp
       mode:
-        type: str
         description:
           - What publish mode to use.
           - Requires API version >= 1.32.
+        type: str
         choices:
           - ingress
           - host
   replicas:
-    type: int
-    default: -1
     description:
       - Number of containers instantiated in the service. Valid only if I(mode) is C(replicated).
       - If set to C(-1), and service is not present, service replicas will be set to C(1).
       - If set to C(-1), and service is present, service replicas will be unchanged.
       - Corresponds to the C(--replicas) option of C(docker service create).
+    type: int
+    default: -1
   restart_policy:
-    type: str
     description:
       - Restart condition of the service.
       - Corresponds to the C(--restart-condition) option of C(docker service create).
+    type: str
     choices:
       - none
       - on-failure
       - any
   restart_policy_attempts:
-    type: int
     description:
       - Maximum number of service restarts.
       - Corresponds to the C(--restart-condition) option of C(docker service create).
-  restart_policy_delay:
     type: int
+  restart_policy_delay:
     description:
       - Delay between restarts.
       - Corresponds to the C(--restart-delay) option of C(docker service create).
-  restart_policy_window:
     type: int
+  restart_policy_window:
     description:
       - Restart policy evaluation window.
       - Corresponds to the C(--restart-window) option of C(docker service create).
-  update_delay:
     type: int
+  update_delay:
     description:
       - Rolling update delay in nanoseconds.
       - Corresponds to the C(--update-delay) option of C(docker service create).
       - Before Ansible 2.8, the default value for this option was C(10).
-  update_parallelism:
     type: int
+  update_parallelism:
     description:
       - Rolling update parallelism.
       - Corresponds to the C(--update-parallelism) option of C(docker service create).
       - Before Ansible 2.8, the default value for this option was C(1).
+    type: int
   update_failure_action:
-    type: str
     description:
       - Action to take in case of container failure.
       - Corresponds to the C(--update-failure-action) option of C(docker service create).
+    type: str
     choices:
       - continue
       - pause
   update_monitor:
-    type: int
     description:
       - Time to monitor updated tasks for failures, in nanoseconds.
       - Corresponds to the C(--update-monitor) option of C(docker service create).
       - Requires API version >= 1.25.
+    type: int
   update_max_failure_ratio:
-    type: float
     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).
       - Requires API version >= 1.25.
+    type: float
   update_order:
-    type: str
     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.
-  user:
     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 C(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).
-  working_dir:
     type: str
+  working_dir:
     description:
       - Path to the working directory.
       - Corresponds to the C(--workdir) option of C(docker service create).
+    type: str
     version_added: "2.8"
 extends_documentation_fragment:
   - docker
@@ -1638,48 +1641,48 @@ def _detect_healthcheck_start_period(client):
 
 def main():
     argument_spec = dict(
-        name=dict(required=True),
+        name=dict(type='str', required=True),
         image=dict(type='str'),
-        state=dict(default='present', choices=['present', 'absent']),
+        state=dict(type='str', default='present', choices=['present', 'absent']),
         mounts=dict(type='list', elements='dict', options=dict(
             source=dict(type='str', required=True),
             target=dict(type='str', required=True),
             type=dict(
-                default='bind',
                 type='str',
+                default='bind',
                 choices=['bind', 'volume', 'tmpfs']
             ),
-            readonly=dict(default=False, type='bool'),
+            readonly=dict(type='bool', default=False),
         )),
         configs=dict(type='list', elements='dict', options=dict(
             config_id=dict(type='str', required=True),
             config_name=dict(type='str', required=True),
             filename=dict(type='str'),
-            uid=dict(default=0, type='int'),
+            uid=dict(type='int', default=0),
-            gid=dict(default=0, type='int'),
+            gid=dict(type='int', default=0),
-            mode=dict(default=0o444, type='int'),
+            mode=dict(type='int', default=0o444),
         )),
         secrets=dict(type='list', elements='dict', options=dict(
             secret_id=dict(type='str', required=True),
             secret_name=dict(type='str', required=True),
             filename=dict(type='str'),
-            uid=dict(default=0, type='int'),
+            uid=dict(type='int', default=0),
-            gid=dict(default=0, type='int'),
+            gid=dict(type='int', default=0),
-            mode=dict(default=0o444, type='int'),
+            mode=dict(type='int', default=0o444),
         )),
-        networks=dict(type='list'),
+        networks=dict(type='list', elements='str'),
         command=dict(type='raw'),
-        args=dict(type='list'),
+        args=dict(type='list', elements='str'),
         env=dict(type='raw'),
         env_files=dict(type='list', elements='path'),
-        force_update=dict(default=False, type='bool'),
+        force_update=dict(type='bool', default=False),
         groups=dict(type='list', elements='str'),
         log_driver=dict(type='str'),
         log_driver_options=dict(type='dict'),
         publish=dict(type='list', elements='dict', options=dict(
             published_port=dict(type='int', required=True),
             target_port=dict(type='int', required=True),
-            protocol=dict(default='tcp', type='str', choices=('tcp', 'udp')),
+            protocol=dict(type='str', default='tcp', choices=('tcp', 'udp')),
             mode=dict(type='str', choices=('ingress', 'host')),
         )),
         constraints=dict(type='list'),
@@ -1698,22 +1701,22 @@ def main():
         hostname=dict(type='str'),
         labels=dict(type='dict'),
         container_labels=dict(type='dict'),
-        mode=dict(default='replicated', type='str'),
+        mode=dict(type='str', default='replicated'),
-        replicas=dict(default=-1, type='int'),
+        replicas=dict(type='int', default=-1),
-        endpoint_mode=dict(choices=['vip', 'dnsrr']),
+        endpoint_mode=dict(type='str', choices=['vip', 'dnsrr']),
         stop_signal=dict(type='str'),
         limit_cpu=dict(type='float'),
         limit_memory=dict(type='str'),
         reserve_cpu=dict(type='float'),
         reserve_memory=dict(type='str'),
-        resolve_image=dict(default=True, type='bool'),
+        resolve_image=dict(type='bool', default=True),
-        restart_policy=dict(choices=['none', 'on-failure', 'any']),
+        restart_policy=dict(type='str', choices=['none', 'on-failure', 'any']),
         restart_policy_delay=dict(type='int'),
         restart_policy_attempts=dict(type='int'),
         restart_policy_window=dict(type='int'),
         update_delay=dict(type='int'),
         update_parallelism=dict(type='int'),
-        update_failure_action=dict(choices=['continue', 'pause']),
+        update_failure_action=dict(type='str', choices=['continue', 'pause']),
         update_monitor=dict(type='int'),
         update_max_failure_ratio=dict(type='float'),
         update_order=dict(type='str'),

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

@@ -24,16 +24,16 @@ options:
   volume_name:
     description:
       - Name of the volume to operate on.
-    required: true
     type: str
+    required: yes
     aliases:
       - name
 
   driver:
     description:
       - Specify the type of volume. Docker provides the C(local) driver, but 3rd party drivers can also be used.
-    default: local
     type: str
+    default: local
 
   driver_options:
     description:
@@ -67,16 +67,18 @@ options:
       - The value C(never) makes sure the volume will not be recreated.
       - The value C(options-changed) makes sure the volume will be recreated if the volume
         already exist and the driver, driver options or labels differ.
+    type: str
+    default: never
     choices:
     - always
     - never
     - options-changed
-    default: never
 
   state:
     description:
       - C(absent) deletes the volume.
       - C(present) creates the volume, if it does not already exist.
+    type: str
     default: present
     choices:
       - absent

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

@@ -23,8 +23,8 @@ options:
   name:
     description:
       - Name of the volume to inspect.
-    required: true
     type: str
+    required: yes
     aliases:
       - volume_name