mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-05-30 04:49:09 -07:00
c*.py: normalize docs (#9418)
* c*.py: normalize docs * fix copy/paste mistake * Apply suggestions from code review Co-authored-by: Felix Fontein <felix@fontein.de> --------- Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Alexei Znamensky
GitHub
parent
912065ad0e
commit
43599c6850
36 changed files with 1437 additions and 1614 deletions
|
|
@ -9,26 +9,21 @@ from __future__ import absolute_import, division, print_function
|
|||
__metaclass__ = type
|
||||
|
||||
|
||||
DOCUMENTATION = '''
|
||||
DOCUMENTATION = r"""
|
||||
module: consul
|
||||
short_description: Add, modify & delete services within a consul cluster
|
||||
short_description: Add, modify & delete services within a Consul cluster
|
||||
description:
|
||||
- Registers services and checks for an agent with a consul cluster.
|
||||
A service is some process running on the agent node that should be advertised by
|
||||
consul's discovery mechanism. It may optionally supply a check definition,
|
||||
a periodic service test to notify the consul cluster of service's health.
|
||||
- "Checks may also be registered per node e.g. disk usage, or cpu usage and
|
||||
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 O(check_name) and optionally a O(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
|
||||
stage change management will be added.
|
||||
- "See U(http://consul.io) for more details."
|
||||
- Registers services and checks for an agent with a Consul cluster. A service is some process running on the agent node
|
||||
that should be advertised by Consul's discovery mechanism. It may optionally supply a check definition, a periodic service
|
||||
test to notify the Consul cluster of service's health.
|
||||
- Checks may also be registered per node, for example disk usage, or cpu usage and 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 V(service:) Node level checks require a O(check_name) and optionally a O(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 stage change management will be added.
|
||||
- See U(http://consul.io) for more details.
|
||||
requirements:
|
||||
- python-consul
|
||||
- requests
|
||||
|
|
@ -41,139 +36,127 @@ attributes:
|
|||
diff_mode:
|
||||
support: none
|
||||
options:
|
||||
state:
|
||||
type: str
|
||||
description:
|
||||
- Register or deregister the consul service, defaults to present.
|
||||
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. If O(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
|
||||
validate_certs:
|
||||
description:
|
||||
- Whether to verify the TLS certificate of the consul agent.
|
||||
type: bool
|
||||
default: true
|
||||
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, that is if O(service_name) or O(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 C(address) parameter to Consul's
|
||||
C(/v1/agent/service/register) API method, so refer to the Consul API
|
||||
documentation for further details.
|
||||
tags:
|
||||
type: list
|
||||
elements: str
|
||||
description:
|
||||
- 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.
|
||||
- Requires O(interval) to be provided.
|
||||
- Mutually exclusive with O(ttl), O(tcp) and O(http).
|
||||
interval:
|
||||
type: str
|
||||
description:
|
||||
- The interval at which the service check will be run.
|
||||
This is a number with a V(s) or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m).
|
||||
If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
|
||||
- Required if one of the parameters O(script), O(http), or O(tcp) is specified.
|
||||
check_id:
|
||||
type: str
|
||||
description:
|
||||
- An ID for the service check. If O(state=absent), defaults to
|
||||
O(check_name). Ignored if part of a service definition.
|
||||
check_name:
|
||||
type: str
|
||||
description:
|
||||
- Name for the service check. Required if standalone, ignored if
|
||||
part of service definition.
|
||||
check_node:
|
||||
description:
|
||||
- Node name.
|
||||
# TODO: properly document!
|
||||
type: str
|
||||
check_host:
|
||||
description:
|
||||
- Host name.
|
||||
# TODO: properly document!
|
||||
type: str
|
||||
ttl:
|
||||
type: str
|
||||
description:
|
||||
- Checks can be registered with a TTL instead of a O(script) and O(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 V(s) or V(m) suffix to
|
||||
signify the units of seconds or minutes, for example V(15s) or V(1m).
|
||||
If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
|
||||
- Mutually exclusive with O(script), O(tcp) and O(http).
|
||||
tcp:
|
||||
type: str
|
||||
description:
|
||||
- Checks can be registered with a TCP port. This means that consul
|
||||
will check if the connection attempt to that port is successful (that is, the port is currently accepting connections).
|
||||
The format is V(host:port), for example V(localhost:80).
|
||||
- Requires O(interval) to be provided.
|
||||
- Mutually exclusive with O(script), O(ttl) and O(http).
|
||||
version_added: '1.3.0'
|
||||
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.
|
||||
- Requires O(interval) to be provided.
|
||||
- Mutually exclusive with O(script), O(ttl) and O(tcp).
|
||||
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 V(s) or V(m) suffix to
|
||||
signify the units of seconds or minutes, for example V(15s) or V(1m).
|
||||
If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
|
||||
token:
|
||||
type: str
|
||||
description:
|
||||
- The token key identifying an ACL rule set. May be required to register services.
|
||||
'''
|
||||
state:
|
||||
type: str
|
||||
description:
|
||||
- Register or deregister the Consul service, defaults to present.
|
||||
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. If O(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
|
||||
validate_certs:
|
||||
description:
|
||||
- Whether to verify the TLS certificate of the Consul agent.
|
||||
type: bool
|
||||
default: true
|
||||
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, that is if O(service_name)
|
||||
or O(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 C(address) parameter
|
||||
to Consul's C(/v1/agent/service/register) API method, so refer to the Consul API documentation for further details.
|
||||
tags:
|
||||
type: list
|
||||
elements: str
|
||||
description:
|
||||
- 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.
|
||||
- Requires O(interval) to be provided.
|
||||
- Mutually exclusive with O(ttl), O(tcp) and O(http).
|
||||
interval:
|
||||
type: str
|
||||
description:
|
||||
- The interval at which the service check will be run. This is a number with a V(s) or V(m) suffix to signify the units
|
||||
of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used by default, for example
|
||||
V(10) will be V(10s).
|
||||
- Required if one of the parameters O(script), O(http), or O(tcp) is specified.
|
||||
check_id:
|
||||
type: str
|
||||
description:
|
||||
- An ID for the service check. If O(state=absent), defaults to O(check_name). Ignored if part of a service definition.
|
||||
check_name:
|
||||
type: str
|
||||
description:
|
||||
- Name for the service check. Required if standalone, ignored if part of service definition.
|
||||
check_node:
|
||||
description:
|
||||
- Node name.
|
||||
type: str
|
||||
check_host:
|
||||
description:
|
||||
- Host name.
|
||||
type: str
|
||||
ttl:
|
||||
type: str
|
||||
description:
|
||||
- Checks can be registered with a TTL instead of a O(script) and O(interval) this means that the service will check
|
||||
in with the agent before the TTL expires. If it does not 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 V(s) or V(m) suffix
|
||||
to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s) will be used
|
||||
by default, for example V(10) will be V(10s).
|
||||
- Mutually exclusive with O(script), O(tcp) and O(http).
|
||||
tcp:
|
||||
type: str
|
||||
description:
|
||||
- Checks can be registered with a TCP port. This means that Consul will check if the connection attempt to that port
|
||||
is successful (that is, the port is currently accepting connections). The format is V(host:port), for example V(localhost:80).
|
||||
- Requires O(interval) to be provided.
|
||||
- Mutually exclusive with O(script), O(ttl) and O(http).
|
||||
version_added: '1.3.0'
|
||||
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.
|
||||
- Requires O(interval) to be provided.
|
||||
- Mutually exclusive with O(script), O(ttl) and O(tcp).
|
||||
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 V(s)
|
||||
or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m). If no suffix is supplied V(s)
|
||||
will be used by default, for example V(10) will be V(10s).
|
||||
token:
|
||||
type: str
|
||||
description:
|
||||
- The token key identifying an ACL rule set. May be required to register services.
|
||||
"""
|
||||
|
||||
EXAMPLES = '''
|
||||
- name: Register nginx service with the local consul agent
|
||||
EXAMPLES = r"""
|
||||
- name: Register nginx service with the local Consul agent
|
||||
community.general.consul:
|
||||
service_name: nginx
|
||||
service_port: 80
|
||||
|
|
@ -239,7 +222,7 @@ EXAMPLES = '''
|
|||
service_id: nginx
|
||||
interval: 60s
|
||||
http: http://localhost:80/morestatus
|
||||
'''
|
||||
"""
|
||||
|
||||
try:
|
||||
import consul
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue