From 98246f603223f6776e124d98204b42eea28594af Mon Sep 17 00:00:00 2001 From: Pilou Date: Thu, 16 May 2019 18:54:05 +0000 Subject: [PATCH] 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 | 71 ++++++++++++-------- lib/ansible/modules/clustering/consul_acl.py | 10 +-- lib/ansible/modules/clustering/consul_kv.py | 22 ++++-- test/sanity/validate-modules/ignore.txt | 3 - 4 files changed, 67 insertions(+), 39 deletions(-) diff --git a/lib/ansible/modules/clustering/consul.py b/lib/ansible/modules/clustering/consul.py index 1afe20dc0f1..c1754b181e9 100644 --- a/lib/ansible/modules/clustering/consul.py +++ b/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 - service name if the service name is supplied - default: service_name if supplied + - the ID for the service, must be unique per node. If I(state=absent), + defaults to the 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. - 1 will be 1m. Required if the script param is specified. + C(15s) or C(1m). If no suffix is supplied, m will be used by default e.g. + 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 - part of a service definition. + - an ID for the service check. If I(state=absent), defaults to + 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 - standalone, ignored if part of service definition. + - a name for the service check. Required if standalone, ignored if + 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 - is supplied, m will be used by default e.g. 1 will be 1m + signify the units of seconds or minutes e.g C(15s) or C(1m). If no suffix + 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 - will check that the http endpoint returns a successful http status. - Interval must also be provided with this option. + - checks can be registered with an HTTP endpoint. This means that consul + will check that the http endpoint returns a successful HTTP status. + 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 - signify the units of seconds or minutes, e.g. 15s or 1m. + 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. 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 = ''' diff --git a/lib/ansible/modules/clustering/consul_acl.py b/lib/ansible/modules/clustering/consul_acl.py index 8d1d93bf0a6..6c0c52e279d 100644 --- a/lib/ansible/modules/clustering/consul_acl.py +++ b/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 diff --git a/lib/ansible/modules/clustering/consul_kv.py b/lib/ansible/modules/clustering/consul_kv.py index dcd46fc0c47..ff89d3c7af8 100644 --- a/lib/ansible/modules/clustering/consul_kv.py +++ b/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'. - - If the key represents a prefix then Note that when a value is removed, the existing + the indices, flags and session are returned as C(value). + - 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: diff --git a/test/sanity/validate-modules/ignore.txt b/test/sanity/validate-modules/ignore.txt index e9954bf6a4e..5d4170758f2 100644 --- a/test/sanity/validate-modules/ignore.txt +++ b/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