consul modules: update documentation (#56408)

* consul modules: Python 2.6 is always required on managed node, document all types, improve parameter descriptions, fix typos
* consul_kv: add doc for retrieve parameter

lib/ansible/modules/clustering/consul.py

@@ -24,16 +24,15 @@ description:
    notify the health of the entire node to the cluster.
    Service level checks do not require a check name or id as these are derived
    by Consul from the Service name and id respectively by appending 'service:'
-   Node level checks require a check_name and optionally a check_id."
+   Node level checks require a I(check_name) and optionally a I(check_id)."
  - Currently, there is no complete way to retrieve the script, interval or ttl
    metadata for a registered check. Without this metadata it is  not possible to
    tell if the data supplied with ansible represents a change to a check. As a
    result this does not attempt to determine changes and will always report a
-   changed occurred. An api method is planned to supply this metadata so at that
+   changed occurred. An API method is planned to supply this metadata so at that
    stage change management will be added.
- - "See http://consul.io for more details."
+ - "See U(http://consul.io) for more details."
 requirements:
-  - "python >= 2.6"
   - python-consul
   - requests
 version_added: "2.0"
@@ -42,96 +41,112 @@ options:
     state:
         description:
           - register or deregister the consul service, defaults to present
-        required: true
+        default: present
         choices: ['present', 'absent']
     service_name:
+        type: str
         description:
           - Unique name for the service on a node, must be unique per node,
             required if registering a service. May be omitted if registering
             a node level check
     service_id:
+        type: str
         description:
-          - the ID for the service, must be unique per node, defaults to the
+          - the ID for the service, must be unique per node. If I(state=absent),
-            service name if the service name is supplied
+            defaults to the service name if supplied.
-        default: service_name if supplied
     host:
+        type: str
         description:
           - host of the consul agent defaults to localhost
         default: localhost
     port:
+        type: int
         description:
           - the port on which the consul agent is running
         default: 8500
     scheme:
+        type: str
         description:
           - the protocol scheme on which the consul agent is running
         default: http
         version_added: "2.1"
     validate_certs:
         description:
-          - whether to verify the tls certificate of the consul agent
+          - whether to verify the TLS certificate of the consul agent
         type: bool
         default: 'yes'
         version_added: "2.1"
     notes:
+        type: str
         description:
           - Notes to attach to check when registering it.
     service_port:
+        type: int
         description:
           - the port on which the service is listening. Can optionally be supplied for
-            registration of a service, i.e. if service_name or service_id is set
+            registration of a service, i.e. if I(service_name) or I(service_id) is set
     service_address:
+        type: str
         description:
           - the address to advertise that the service will be listening on.
-            This value will be passed as the I(Address) parameter to Consul's
+            This value will be passed as the I(address) parameter to Consul's
             U(/v1/agent/service/register) API method, so refer to the Consul API
             documentation for further details.
         version_added: "2.1"
     tags:
+        type: list
         description:
-          - a list of tags that will be attached to the service registration.
+          - tags that will be attached to the service registration.
     script:
+        type: str
         description:
           - the script/command that will be run periodically to check the health
-            of the service. Scripts require an interval and vise versa
+            of the service. Scripts require I(interval) and vice versa.
     interval:
+        type: str
         description:
           - the interval at which the service check will be run. This is a number
             with a s or m suffix to signify the units of seconds or minutes e.g
-            15s or 1m. If no suffix is supplied, m will be used by default e.g.
+            C(15s) or C(1m). If no suffix is supplied, m will be used by default e.g.
-            1 will be 1m. Required if the script param is specified.
+            C(1) will be C(1m). Required if the I(script) parameter is specified.
     check_id:
+        type: str
         description:
-          - an ID for the service check, defaults to the check name, ignored if
+          - an ID for the service check. If I(state=absent), defaults to
-            part of a service definition.
+            I(check_name). Ignored if part of a service definition.
     check_name:
+        type: str
         description:
-          - a name for the service check, defaults to the check id. required if
+          - a name for the service check. Required if standalone, ignored if
-            standalone, ignored if part of service definition.
+            part of service definition.
     ttl:
+        type: str
         description:
-          - checks can be registered with a ttl instead of a script and interval
+          - checks can be registered with a ttl instead of a I(script) and I(interval)
             this means that the service will check in with the agent before the
             ttl expires. If it doesn't the check will be considered failed.
             Required if registering a check and the script an interval are missing
             Similar to the interval this is a number with a s or m suffix to
-            signify the units of seconds or minutes e.g 15s or 1m. If no suffix
+            signify the units of seconds or minutes e.g C(15s) or C(1m). If no suffix
-            is supplied, m will be used by default e.g. 1 will be 1m
+            is supplied, C(m) will be used by default e.g. C(1) will be C(1m)
     http:
+        type: str
         description:
-          - checks can be registered with an http endpoint. This means that consul
+          - checks can be registered with an HTTP endpoint. This means that consul
-            will check that the http endpoint returns a successful http status.
+            will check that the http endpoint returns a successful HTTP status.
-            Interval must also be provided with this option.
+            I(interval) must also be provided with this option.
         version_added: "2.0"
     timeout:
+        type: str
         description:
           - A custom HTTP check timeout. The consul default is 10 seconds.
-            Similar to the interval this is a number with a s or m suffix to
+            Similar to the interval this is a number with a C(s) or C(m) suffix to
-            signify the units of seconds or minutes, e.g. 15s or 1m.
+            signify the units of seconds or minutes, e.g. C(15s) or C(1m).
         version_added: "2.0"
     token:
+        type: str
         description:
-          - the token key indentifying an ACL rule set. May be required to register services.
+          - the token key identifying an ACL rule set. May be required to register services.
 """
 
 EXAMPLES = '''

lib/ansible/modules/clustering/consul_acl.py

@@ -34,7 +34,7 @@ options:
     default: present
   token_type:
     description:
-      - the type of token that should be created, either management or client
+      - the type of token that should be created
     choices: ['client', 'management']
     default: client
   name:
@@ -48,8 +48,9 @@ options:
         this will be a UUID
     required: false
   rules:
+    type: list
     description:
-      - a list of the rules that should be associated with a given token
+      - rules that should be associated with a given token
     required: false
   host:
     description:
@@ -57,6 +58,7 @@ options:
     required: false
     default: localhost
   port:
+    type: int
     description:
       - the port on which the consul agent is running
     required: false
@@ -68,13 +70,13 @@ options:
     default: http
     version_added: "2.1"
   validate_certs:
+    type: bool
     description:
       - whether to verify the tls certificate of the consul agent
     required: false
     default: True
     version_added: "2.1"
 requirements:
-  - "python >= 2.6"
   - python-consul
   - pyhcl
   - requests
@@ -469,7 +471,7 @@ class Configuration:
         self.scheme = scheme    # type: str
         self.validate_certs = validate_certs    # type: bool
         self.name = name    # type: str
-        self.port = port    # type: bool
+        self.port = port    # type: int
         self.rules = rules    # type: RuleCollection
         self.state = state    # type: str
         self.token = token    # type: str

lib/ansible/modules/clustering/consul_kv.py

@@ -19,12 +19,11 @@ short_description: Manipulate entries in the key/value store of a consul cluster
 description:
   - Allows the retrieval, addition, modification and deletion of key/value entries in a
     consul cluster via the agent. The entire contents of the record, including
-    the indices, flags and session are returned as 'value'.
+    the indices, flags and session are returned as C(value).
-  - If the key represents a prefix then Note that when a value is removed, the existing
+  - If the C(key) represents a prefix then note that when a value is removed, the existing
     value if any is returned as part of the results.
   - See http://www.consul.io/docs/agent/http.html#kv for more details.
 requirements:
-  - python >= 2.6
   - python-consul
   - requests
 version_added: "2.0"
@@ -49,11 +48,13 @@ options:
     key:
         description:
           - The key at which the value should be stored.
+        type: str
         required: yes
     value:
         description:
           - The value should be associated with the given key, required if C(state)
             is C(present).
+        type: str
         required: yes
     recurse:
         description:
@@ -61,34 +62,47 @@ options:
             retrieved by setting this to C(yes).
         type: bool
         default: 'no'
+    retrieve:
+        description:
+            - If the I(state) is C(present) and I(value) is set, perform a
+              read after setting the value and return this value.
+        default: True
+        type: bool
     session:
         description:
           - The session that should be used to acquire or release a lock
             associated with a key/value pair.
+        type: str
     token:
         description:
           - The token key indentifying an ACL rule set that controls access to
             the key value pair
+        type: str
     cas:
         description:
           - Used when acquiring a lock with a session. If the C(cas) is C(0), then
             Consul will only put the key if it does not already exist. If the
             C(cas) value is non-zero, then the key is only set if the index matches
             the ModifyIndex of that key.
+        type: str
     flags:
         description:
-          - Opaque integer value that can be passed when setting a value.
+          - Opaque positive integer value that can be passed when setting a value.
+        type: str
     host:
         description:
           - Host of the consul agent.
+        type: str
         default: localhost
     port:
         description:
           - The port on which the consul agent is running.
+        type: int
         default: 8500
     scheme:
         description:
           - The protocol scheme on which the consul agent is running.
+        type: str
         default: http
         version_added: "2.1"
     validate_certs:

test/sanity/validate-modules/ignore.txt

@@ -309,9 +309,6 @@ lib/ansible/modules/cloud/vmware/vmware_guest.py E322
 lib/ansible/modules/cloud/vmware/vsphere_copy.py E322
 lib/ansible/modules/cloud/vmware/vsphere_copy.py E309
 lib/ansible/modules/clustering/consul.py E322
-lib/ansible/modules/clustering/consul.py E324
-lib/ansible/modules/clustering/consul_kv.py E322
-lib/ansible/modules/clustering/consul_kv.py E324
 lib/ansible/modules/clustering/consul_session.py E322
 lib/ansible/modules/clustering/etcd3.py E326
 lib/ansible/modules/clustering/znode.py E326