cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

consul modules: update documentation (#56408)

Browse source 
* 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
This commit is contained in:
Pilou 2019-05-16 18:54:05 +00:00 committed by Alicia Cozine
parent 7e997fdca2
commit 98246f6032
4 changed files with 67 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
lib/ansible/modules/clustering/consul.py
View file

@ -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 = '''

10
lib/ansible/modules/clustering/consul_acl.py
View file

@ -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

22
lib/ansible/modules/clustering/consul_kv.py
View file

@ -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:

3
test/sanity/validate-modules/ignore.txt
View file

@ -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