From 4117b2dd297b170d7b81bdcf613ae71049a4139e Mon Sep 17 00:00:00 2001 From: Thierry BOUVET Date: Tue, 17 Apr 2018 17:51:56 +0200 Subject: [PATCH] Fix documentation fragments for docker (#38378) --- lib/ansible/module_utils/docker_common.py | 22 ++++++++------- .../modules/cloud/docker/docker_container.py | 28 +++++++++++-------- .../modules/cloud/docker/docker_image.py | 9 +++--- .../modules/cloud/docker/docker_secret.py | 3 +- .../modules/cloud/docker/docker_service.py | 13 +++++++-- .../utils/module_docs_fragments/docker.py | 11 +++++++- test/sanity/validate-modules/ignore.txt | 27 ------------------ 7 files changed, 54 insertions(+), 59 deletions(-) diff --git a/lib/ansible/module_utils/docker_common.py b/lib/ansible/module_utils/docker_common.py index eb00d28a0d..b97fa3f35d 100644 --- a/lib/ansible/module_utils/docker_common.py +++ b/lib/ansible/module_utils/docker_common.py @@ -37,7 +37,7 @@ try: from docker import __version__ as docker_version from docker.errors import APIError, TLSParameterError, NotFound from docker.tls import TLSConfig - from docker.constants import DEFAULT_TIMEOUT_SECONDS, DEFAULT_DOCKER_API_VERSION + from docker.constants import DEFAULT_DOCKER_API_VERSION from docker import auth if LooseVersion(docker_version) >= LooseVersion('3.0.0'): @@ -78,21 +78,23 @@ except ImportError: DEFAULT_DOCKER_HOST = 'unix://var/run/docker.sock' DEFAULT_TLS = False DEFAULT_TLS_VERIFY = False +DEFAULT_TLS_HOSTNAME = 'localhost' MIN_DOCKER_VERSION = "1.7.0" +DEFAULT_SSL_VERSION = "1.0" +DEFAULT_TIMEOUT_SECONDS = 60 DOCKER_COMMON_ARGS = dict( - docker_host=dict(type='str', aliases=['docker_url']), - tls_hostname=dict(type='str'), - api_version=dict(type='str', aliases=['docker_api_version']), - timeout=dict(type='int'), + docker_host=dict(type='str', aliases=['docker_url'], default=DEFAULT_DOCKER_HOST), + tls_hostname=dict(type='str', default=DEFAULT_TLS_HOSTNAME), + api_version=dict(type='str', aliases=['docker_api_version'], default='auto'), + timeout=dict(type='int', default=DEFAULT_TIMEOUT_SECONDS), cacert_path=dict(type='str', aliases=['tls_ca_cert']), cert_path=dict(type='str', aliases=['tls_client_cert']), key_path=dict(type='str', aliases=['tls_client_key']), - ssl_version=dict(type='str'), - tls=dict(type='bool'), - tls_verify=dict(type='bool'), - debug=dict(type='bool', default=False), - filter_logger=dict(type='bool', default=False), + ssl_version=dict(type='str', default=DEFAULT_SSL_VERSION), + tls=dict(type='bool', default=DEFAULT_TLS), + tls_verify=dict(type='bool', default=DEFAULT_TLS_VERIFY), + debug=dict(type='bool', default=False) ) DOCKER_MUTUALLY_EXCLUSIVE = [ diff --git a/lib/ansible/modules/cloud/docker/docker_container.py b/lib/ansible/modules/cloud/docker/docker_container.py index cc0b5662f5..a49fdfdc3d 100644 --- a/lib/ansible/modules/cloud/docker/docker_container.py +++ b/lib/ansible/modules/cloud/docker/docker_container.py @@ -69,10 +69,15 @@ options: 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 devices: description: - "List of host device bindings to add to the container. Each binding is a mapping expressed in the format: ::" + dns_opts: + description: + - list of DNS options dns_servers: description: - List of custom DNS servers. @@ -107,11 +112,14 @@ options: need to be exposed again. aliases: - exposed + - expose force_kill: description: - Use the kill command when stopping a running container. type: bool default: 'no' + aliases: + - forcekill groups: description: - List of additional group names and/or IDs that the container process will run as. @@ -175,6 +183,8 @@ options: description: - Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/ for details. + aliases: + - log_opt mac_address: description: - Container MAC address (e.g. 92:d0:c6:0a:29:33) @@ -182,7 +192,7 @@ options: description: - "Memory limit (format: []). Number is a positive integer. Unit can be one of b, k, m, or g" - default: 0 + default: '0' memory_reservation: description: - "Memory soft limit (format: []). Number is a positive integer. @@ -204,12 +214,7 @@ options: required: true network_mode: description: - - Connect the container to a network. - choices: - - bridge - - container: - - host - - none + - Connect the container to a network. Choices are "bridge", "host", "none" or "container:" userns_mode: description: - User namespace to use @@ -293,11 +298,10 @@ options: description: - Container restart policy. Place quotes around I(no) option. choices: - - always - - no - - on-failure - - unless-stopped - default: on-failure + - 'no' + - 'on-failure' + - 'always' + - 'unless-stopped' restart_retries: description: - Use with restart policy to control maximum number of restart attempts. diff --git a/lib/ansible/modules/cloud/docker/docker_image.py b/lib/ansible/modules/cloud/docker/docker_image.py index 19f4574399..cfa7175a32 100644 --- a/lib/ansible/modules/cloud/docker/docker_image.py +++ b/lib/ansible/modules/cloud/docker/docker_image.py @@ -38,7 +38,6 @@ options: dockerfile: description: - Use with state C(present) to provide an alternate name for the Dockerfile to use when building an image. - default: Dockerfile required: false version_added: "2.0" force: @@ -156,10 +155,10 @@ options: C(encrypt) to use TLS. And set to C(verify) to use TLS and verify that the server's certificate is valid for the server. NOTE: If you specify this option, it will set the value of the tls or tls_verify parameters." choices: - - no - - encrypt - - verify - default: no + - 'no' + - 'encrypt' + - 'verify' + default: 'no' required: false version_added: "2.0" diff --git a/lib/ansible/modules/cloud/docker/docker_secret.py b/lib/ansible/modules/cloud/docker/docker_secret.py index e2ec547c4a..d7d6a28bb1 100644 --- a/lib/ansible/modules/cloud/docker/docker_secret.py +++ b/lib/ansible/modules/cloud/docker/docker_secret.py @@ -38,9 +38,10 @@ options: required: false force: description: - - Boolean. Use with state C(present) to always remove and recreate an existing secret. + - 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 name: description: - The name of the secret. diff --git a/lib/ansible/modules/cloud/docker/docker_service.py b/lib/ansible/modules/cloud/docker/docker_service.py index f4dbb2e8ef..75f9f0615a 100755 --- a/lib/ansible/modules/cloud/docker/docker_service.py +++ b/lib/ansible/modules/cloud/docker/docker_service.py @@ -110,6 +110,9 @@ options: remove_images: description: - Use with state I(absent) to remove the all images or only local images. + choices: + - 'all' + - 'local' remove_volumes: description: - Use with state I(absent) to remove data volumes. @@ -125,11 +128,15 @@ options: - Use with state I(present) to restart all containers. type: bool default: 'no' - debug: + remove_orphans: description: - - Include I(actions) in the return values. + - Remove containers for services not defined in the compose file. type: bool - default: 'no' + default: false + timeout: + description: + - timeout in seconds for container shutdown when attached or when containers are already running. + default: 10 extends_documentation_fragment: - docker diff --git a/lib/ansible/utils/module_docs_fragments/docker.py b/lib/ansible/utils/module_docs_fragments/docker.py index a1649ed75c..1078a4c467 100644 --- a/lib/ansible/utils/module_docs_fragments/docker.py +++ b/lib/ansible/utils/module_docs_fragments/docker.py @@ -37,7 +37,7 @@ options: description: - The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by docker-py. - default: default provided by docker-py + default: 'auto' aliases: - docker_api_version timeout: @@ -67,9 +67,18 @@ options: description: - Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. + default: false + type: bool tls_verify: description: - Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. + default: false + type: bool + debug: + description: + - Debug mode + default: false + type: bool notes: - Connect to the Docker daemon by providing parameters with each task or by defining environment variables. diff --git a/test/sanity/validate-modules/ignore.txt b/test/sanity/validate-modules/ignore.txt index b6e0efbd52..2d7f9d7d36 100644 --- a/test/sanity/validate-modules/ignore.txt +++ b/test/sanity/validate-modules/ignore.txt @@ -317,33 +317,6 @@ lib/ansible/modules/cloud/dimensiondata/dimensiondata_network.py E325 lib/ansible/modules/cloud/dimensiondata/dimensiondata_network.py E326 lib/ansible/modules/cloud/dimensiondata/dimensiondata_vlan.py E325 lib/ansible/modules/cloud/dimensiondata/dimensiondata_vlan.py E326 -lib/ansible/modules/cloud/docker/docker_container.py E322 -lib/ansible/modules/cloud/docker/docker_container.py E324 -lib/ansible/modules/cloud/docker/docker_container.py E325 -lib/ansible/modules/cloud/docker/docker_container.py E326 -lib/ansible/modules/cloud/docker/docker_image.py E322 -lib/ansible/modules/cloud/docker/docker_image.py E324 -lib/ansible/modules/cloud/docker/docker_image.py E325 -lib/ansible/modules/cloud/docker/docker_image.py E326 -lib/ansible/modules/cloud/docker/docker_image_facts.py E322 -lib/ansible/modules/cloud/docker/docker_image_facts.py E324 -lib/ansible/modules/cloud/docker/docker_image_facts.py E325 -lib/ansible/modules/cloud/docker/docker_login.py E322 -lib/ansible/modules/cloud/docker/docker_login.py E324 -lib/ansible/modules/cloud/docker/docker_login.py E325 -lib/ansible/modules/cloud/docker/docker_network.py E322 -lib/ansible/modules/cloud/docker/docker_network.py E324 -lib/ansible/modules/cloud/docker/docker_network.py E325 -lib/ansible/modules/cloud/docker/docker_secret.py E322 -lib/ansible/modules/cloud/docker/docker_secret.py E324 -lib/ansible/modules/cloud/docker/docker_secret.py E325 -lib/ansible/modules/cloud/docker/docker_service.py E322 -lib/ansible/modules/cloud/docker/docker_service.py E324 -lib/ansible/modules/cloud/docker/docker_service.py E325 -lib/ansible/modules/cloud/docker/docker_service.py E326 -lib/ansible/modules/cloud/docker/docker_volume.py E322 -lib/ansible/modules/cloud/docker/docker_volume.py E324 -lib/ansible/modules/cloud/docker/docker_volume.py E325 lib/ansible/modules/cloud/google/gc_storage.py E322 lib/ansible/modules/cloud/google/gc_storage.py E324 lib/ansible/modules/cloud/google/gc_storage.py E325