From 8388c89a29a889330934b7fd93a93ec0e30eb970 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 18 Feb 2019 21:40:52 +0100 Subject: [PATCH] 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 | 4 +- .../modules/cloud/docker/docker_compose.py | 183 +++++++------ .../modules/cloud/docker/docker_config.py | 12 +- .../modules/cloud/docker/docker_container.py | 226 ++++++++++------ .../cloud/docker/docker_container_facts.py | 3 +- .../modules/cloud/docker/docker_image.py | 61 +++-- .../cloud/docker/docker_image_facts.py | 3 +- .../modules/cloud/docker/docker_login.py | 20 +- .../modules/cloud/docker/docker_network.py | 43 ++- .../cloud/docker/docker_network_facts.py | 3 +- .../modules/cloud/docker/docker_node.py | 13 +- .../modules/cloud/docker/docker_node_facts.py | 6 +- .../modules/cloud/docker/docker_secret.py | 12 +- .../modules/cloud/docker/docker_stack.py | 121 +++++---- .../modules/cloud/docker/docker_swarm.py | 255 ++++++++++-------- .../cloud/docker/docker_swarm_service.py | 233 ++++++++-------- .../modules/cloud/docker/docker_volume.py | 8 +- .../cloud/docker/docker_volume_facts.py | 2 +- 18 files changed, 647 insertions(+), 561 deletions(-) diff --git a/lib/ansible/module_utils/docker/common.py b/lib/ansible/module_utils/docker/common.py index 6daafeb743d..f3ec6767e1d 100644 --- a/lib/ansible/module_utils/docker/common.py +++ b/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']), diff --git a/lib/ansible/modules/cloud/docker/docker_compose.py b/lib/ansible/modules/cloud/docker/docker_compose.py index 74cfda01196..a66b93e1a21 100644 --- a/lib/ansible/modules/cloud/docker/docker_compose.py +++ b/lib/ansible/modules/cloud/docker/docker_compose.py @@ -32,111 +32,120 @@ description: options: project_src: - description: - - 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. + description: + - 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. + 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. + 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). - choices: - - absent - - present - default: present + 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 services: - description: - - When C(state) is I(present) run I(docker-compose up) on a subset of 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. + 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' + description: + - When C(state) is I(present) specify whether or not to include linked services. + type: bool + 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). + 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' + description: + - Whether or not to check the Docker daemon's hostname against the name provided in the client certificate. + type: bool + 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 - choices: - - always - - never - - smart - default: smart + 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. + type: str + default: smart + choices: + - always + - never + - smart build: - description: - - Use with state I(present) to always build images prior to starting the application. - - Same as running docker-compose build with the pull option. - - Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents. - - 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' + description: + - Use with state I(present) to always build images prior to starting the application. + - Same as running docker-compose build with the pull option. + - Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents. + - 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 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' - version_added: "2.2" + 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 + version_added: "2.2" nocache: - description: - - Use with the build option to ignore the cache during the image build process. - type: bool - default: 'no' - version_added: "2.2" + description: + - Use with the build option to ignore the cache during the image build process. + type: bool + default: no + version_added: "2.2" remove_images: - description: - - Use with state I(absent) to remove the all images or only local images. - choices: - - 'all' - - 'local' + description: + - Use with state I(absent) to remove the all images or only local images. + type: str + choices: + - 'all' + - 'local' remove_volumes: - description: - - Use with state I(absent) to remove data volumes. - type: bool - default: 'no' + description: + - Use with state I(absent) to remove data volumes. + type: bool + default: no stopped: - description: - - Use with state I(present) to leave the containers in an exited or non-running state. - type: bool - default: 'no' + description: + - Use with state I(present) to leave the containers in an exited or non-running state. + type: bool + default: no restarted: - description: - - Use with state I(present) to restart all containers. - type: bool - default: 'no' + description: + - Use with state I(present) to restart all containers. + type: bool + default: no remove_orphans: - description: - - Remove containers for services not defined in the compose file. - type: bool - default: false + description: + - Remove containers for services not defined in the compose file. + type: bool + 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), diff --git a/lib/ansible/modules/cloud/docker/docker_config.py b/lib/ansible/modules/cloud/docker/docker_config.py index 8113d389efd..042a7f72b65 100644 --- a/lib/ansible/modules/cloud/docker/docker_config.py +++ b/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'), diff --git a/lib/ansible/modules/cloud/docker/docker_container.py b/lib/ansible/modules/cloud/docker/docker_container.py index 1e173cc5067..65f4a27bbe6 100644 --- a/lib/ansible/modules/cloud/docker/docker_container.py +++ b/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: ::" + 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 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 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:' 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 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. + 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 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,61 +362,67 @@ 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 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:" + type: str userns_mode: - description: - - Set the user namespace mode for the container. Currently, the only valid value is C(host). - version_added: "2.5" + 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: - - List of networks the container belongs to. - - 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. + description: + - List of networks the container belongs to. + - 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)). + type: list + suboptions: + name: + description: + - The network's name. + type: str + required: yes + ipv4_address: + description: + - The container's IPv4 address in this network. + type: str + ipv6_address: + description: + - The container's IPv6 address in this network. + type: str + links: + description: + - A list of containers to link to. + 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' @@ -482,10 +522,12 @@ options: - 'unless-stopped' restart_retries: description: - - Use with restart policy to control maximum number of restart attempts. + - 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), - runtime=dict(type='str', default=None), + restart_retries=dict(type='int'), + 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'), diff --git a/lib/ansible/modules/cloud/docker/docker_container_facts.py b/lib/ansible/modules/cloud/docker/docker_container_facts.py index 32ba15e3ae1..f974850710e 100644 --- a/lib/ansible/modules/cloud/docker/docker_container_facts.py +++ b/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 diff --git a/lib/ansible/modules/cloud/docker/docker_image.py b/lib/ansible/modules/cloud/docker/docker_image.py index 9dbe587280c..3b7d1b7245b 100644 --- a/lib/ansible/modules/cloud/docker/docker_image.py +++ b/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 - version_added: "2.1" + type: dict 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( diff --git a/lib/ansible/modules/cloud/docker/docker_image_facts.py b/lib/ansible/modules/cloud/docker/docker_image_facts.py index e9af968fa26..98ecba35686 100644 --- a/lib/ansible/modules/cloud/docker/docker_image_facts.py +++ b/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 diff --git a/lib/ansible/modules/cloud/docker/docker_login.py b/lib/ansible/modules/cloud/docker/docker_login.py index 19ebc0d4335..ade62d819c7 100644 --- a/lib/ansible/modules/cloud/docker/docker_login.py +++ b/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']), - username=dict(type='str', required=False), - password=dict(type='str', required=False, no_log=True), + registry_url=dict(type='str', default=DEFAULT_DOCKER_REGISTRY, aliases=['registry', 'url']), + username=dict(type='str'), + 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']), diff --git a/lib/ansible/modules/cloud/docker/docker_network.py b/lib/ansible/modules/cloud/docker/docker_network.py index af5d5d40d0b..4684da2cad5 100644 --- a/lib/ansible/modules/cloud/docker/docker_network.py +++ b/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 - required: false + version_added: 2.8 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 - required: false + version_added: 2.8 labels: - version_added: 2.8 description: - Dictionary of labels. type: dict - default: null - required: false + version_added: 2.8 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 - required: false + version_added: 2.8 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'), diff --git a/lib/ansible/modules/cloud/docker/docker_network_facts.py b/lib/ansible/modules/cloud/docker/docker_network_facts.py index 31027095d06..2115c1b792f 100644 --- a/lib/ansible/modules/cloud/docker/docker_network_facts.py +++ b/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 diff --git a/lib/ansible/modules/cloud/docker/docker_node.py b/lib/ansible/modules/cloud/docker/docker_node.py index c18d8a9d764..d6fcdb3c863 100644 --- a/lib/ansible/modules/cloud/docker/docker_node.py +++ b/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']), diff --git a/lib/ansible/modules/cloud/docker/docker_node_facts.py b/lib/ansible/modules/cloud/docker/docker_node_facts.py index 2762cb90ecb..4b1db0d8b35 100644 --- a/lib/ansible/modules/cloud/docker/docker_node_facts.py +++ b/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( diff --git a/lib/ansible/modules/cloud/docker/docker_secret.py b/lib/ansible/modules/cloud/docker/docker_secret.py index d789e041202..b4b321c6781 100644 --- a/lib/ansible/modules/cloud/docker/docker_secret.py +++ b/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'), diff --git a/lib/ansible/modules/cloud/docker/docker_stack.py b/lib/ansible/modules/cloud/docker/docker_stack.py index 787fb8b4f4b..9f9f0c2adbe 100644 --- a/lib/ansible/modules/cloud/docker/docker_stack.py +++ b/lib/ansible/modules/cloud/docker/docker_stack.py @@ -18,63 +18,68 @@ module: docker_stack author: "Dario Zanzico (@dariko)" short_description: docker stack module description: -- Manage docker stacks using the 'docker stack' command - on the target node - (see examples) + - Manage docker stacks using the 'docker stack' command + on the target node (see examples). version_added: "2.8" options: - name: - required: true - description: - - Stack name - state: - description: - - Service state. - 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. - 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 - 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 - 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. - 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. - absent_retries_interval: - default: 1 - description: - - Interval in seconds between C(absent_retries) + name: + description: + - Stack name + type: str + required: yes + state: + description: + - Service state. + type: str + default: "present" + choices: + - present + - absent + compose: + 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: + 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: + 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: + 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: + 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: + description: + - Interval in seconds between C(absent_retries) + type: int + default: 1 requirements: -- jsondiff -- pyyaml + - jsondiff + - pyyaml ''' RETURN = ''' @@ -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'), - 'compose': dict(required=False, type='list', default=[]), - 'prune': dict(default=False, type='bool'), - 'with_registry_auth': dict(default=False, type='bool'), + 'name': dict(type='str', required=True), + 'compose': dict(type='list', default=[]), + 'prune': dict(type='bool', default=False), + '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) }, diff --git a/lib/ansible/modules/cloud/docker/docker_swarm.py b/lib/ansible/modules/cloud/docker/docker_swarm.py index 3a632de81db..2ae13671ad8 100644 --- a/lib/ansible/modules/cloud/docker/docker_swarm.py +++ b/lib/ansible/modules/cloud/docker/docker_swarm.py @@ -16,122 +16,141 @@ module: docker_swarm short_description: Manage Swarm cluster version_added: "2.7" description: - - Create a new Swarm cluster. - - Add/Remove nodes or managers to an existing cluster. + - Create a new Swarm cluster. + - Add/Remove nodes or managers to an existing cluster. options: - advertise_addr: - description: - - Externally reachable address advertised to other nodes. - - This can either be an address/port combination - in the form C(192.168.1.1:4567), or an interface followed by a - port number, like C(eth0:4567). - - If the port number is omitted, - the port number from the listen address is used. - - If C(advertise_addr) is not specified, it will be automatically - detected when possible. - listen_addr: - description: - - Listen address used for inter-manager communication. - - This can either be an address/port combination in the form - C(192.168.1.1:4567), or an interface followed by a port number, - like C(eth0:4567). - - If the port number is omitted, the default swarm listening port - is used. - 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' - state: - description: - - Set to C(present), to create/update a new cluster. - - Set to C(join), to join an existing cluster. - - 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 - default: present - choices: - - present - - join - - absent - - remove - - inspect - node_id: - description: - - Swarm id of the node to remove. - - Used with I(state=remove). - join_token: - description: - - Swarm token used to join a swarm cluster. - - Used with I(state=join). - remote_addrs: - description: - - Remote address of a manager to connect to. - - Used with I(state=join). - task_history_retention_limit: - description: - - Maximum number of tasks history stored. - - Docker default value is C(5). - snapshot_interval: - description: - - Number of logs entries between snapshot. - - Docker default value is C(10000). - keep_old_snapshots: - description: - - Number of snapshots to keep beyond the current snapshot. - - Docker default value is C(0). - log_entries_for_slow_followers: - description: - - Number of log entries to keep around to sync up slow followers after a snapshot is created. - heartbeat_tick: - description: - - Amount of ticks (in seconds) between each heartbeat. - - Docker default value is C(1s). - election_tick: - description: - - Amount of ticks (in seconds) needed without a leader to trigger a new election. - - Docker default value is C(10s). - dispatcher_heartbeat_period: - description: - - The delay for an agent to send a heartbeat to the dispatcher. - - Docker default value is C(5s). - node_cert_expiry: - description: - - Automatic expiry for nodes certificates. - - Docker default value is C(3months). - name: - description: - - The name of the swarm. - labels: - description: - - User-defined key/value metadata. - signing_ca_cert: - description: - - The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format. - signing_ca_key: - description: - - The desired signing CA key for all swarm node TLS leaf certificates, in PEM format. - 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). - autolock_managers: - description: - - If set, generate a key and use it to lock data stored on the managers. - - Docker default value is C(no). - type: bool - rotate_worker_token: - description: Rotate the worker join token. - type: bool - default: 'no' - rotate_manager_token: - description: Rotate the manager join token. - type: bool - default: 'no' + advertise_addr: + description: + - Externally reachable address advertised to other nodes. + - This can either be an address/port combination + in the form C(192.168.1.1:4567), or an interface followed by a + port number, like C(eth0:4567). + - If the port number is omitted, + 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. + - This can either be an address/port combination in the form + C(192.168.1.1:4567), or an interface followed by a port number, + 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 + state: + description: + - Set to C(present), to create/update a new cluster. + - Set to C(join), to join an existing cluster. + - 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. + type: str + required: yes + default: present + choices: + - present + - join + - absent + - remove + - inspect + node_id: + 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. + - Docker default value is C(no). + type: bool + rotate_worker_token: + description: Rotate the worker join token. + type: bool + default: no + rotate_manager_token: + description: Rotate the manager join token. + type: bool + 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_key=dict(type='str'), + signing_ca_cert=dict(type='path'), + signing_ca_key=dict(type='path'), ca_force_rotate=dict(type='int'), autolock_managers=dict(type='bool'), node_id=dict(type='str'), diff --git a/lib/ansible/modules/cloud/docker/docker_swarm_service.py b/lib/ansible/modules/cloud/docker/docker_swarm_service.py index 3b2465d4c68..8cde570ace6 100644 --- a/lib/ansible/modules/cloud/docker/docker_swarm_service.py +++ b/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: | - Manage docker services. Allows live altering of already defined services +description: + - 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 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 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'), - gid=dict(default=0, type='int'), - mode=dict(default=0o444, type='int'), + uid=dict(type='int', default=0), + gid=dict(type='int', default=0), + 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'), - gid=dict(default=0, type='int'), - mode=dict(default=0o444, type='int'), + uid=dict(type='int', default=0), + gid=dict(type='int', default=0), + 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'), - replicas=dict(default=-1, type='int'), - endpoint_mode=dict(choices=['vip', 'dnsrr']), + mode=dict(type='str', default='replicated'), + replicas=dict(type='int', default=-1), + 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'), - restart_policy=dict(choices=['none', 'on-failure', 'any']), + resolve_image=dict(type='bool', default=True), + 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'), diff --git a/lib/ansible/modules/cloud/docker/docker_volume.py b/lib/ansible/modules/cloud/docker/docker_volume.py index 54d2372608c..f8c3d50a77a 100644 --- a/lib/ansible/modules/cloud/docker/docker_volume.py +++ b/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 diff --git a/lib/ansible/modules/cloud/docker/docker_volume_facts.py b/lib/ansible/modules/cloud/docker/docker_volume_facts.py index 0fc0f5b1758..7bb6c3bbd2a 100644 --- a/lib/ansible/modules/cloud/docker/docker_volume_facts.py +++ b/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