community.general.consul_agent_check module – Add, modify, and delete checks within a consul cluster

Note

This module is part of the community.general collection (version 9.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.consul_agent_check.

New in community.general 9.1.0

Synopsis

• Allows the addition, modification and deletion of checks in a consul cluster via the agent. For more details on using and configuring Checks, see https://developer.hashicorp.com/consul/api-docs/agent/check.

• 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.

Parameters

Parameter	Comments
args list / elements=string	Specifies command arguments to run to update the status of the check. Requires interval to be provided. Mutually exclusive with ttl, tcp and http.
ca_path string	The CA bundle to use for https connections
host string	Host of the consul agent, defaults to localhost. Default: "localhost"
http string	Checks can be registered with an HTTP endpoint. This means that consul will check that the http endpoint returns a successful HTTP status. Requires interval to be provided. Mutually exclusive with args, ttl and tcp.
id string	Specifies a unique ID for this check on the node. This defaults to the name parameter, but it may be necessary to provide an ID for uniqueness. This value will return in the response as “CheckId”.
interval string	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, for example 15s or 1m. If no suffix is supplied s will be used by default, for example 10 will be 10s. Required if one of the parameters args, http, or tcp is specified.
name string	Required name for the service check.
notes string	Notes to attach to check when registering it.
port integer	The port on which the consul agent is running. Default: 8500
scheme string	The protocol scheme on which the consul agent is running. Defaults to http and can be set to https for secure connections. Default: "http"
service_id string	The ID for the service, must be unique per node. If state=absent, defaults to the service name if supplied.
state string	Whether the check should be present or absent. Choices: "present" ← (default) "absent"
tcp string added in community.general 1.3.0	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 host:port, for example localhost:80. Requires interval to be provided. Mutually exclusive with args, ttl and http.
timeout string	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, for example 15s or 1m. If no suffix is supplied s will be used by default, for example 10 will be 10s.
token string	The token to use for authorization.
ttl string	Checks can be registered with a TTL instead of a args and 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, for example 15s or 1m. If no suffix is supplied s will be used by default, for example 10 will be 10s. Mutually exclusive with args, tcp and http.
validate_certs boolean	Whether to verify the TLS certificate of the consul agent. Choices: false true ← (default)

Attributes

Attribute	Support	Description
action_group	Action group: community.general.consul	Use group/community.general.consul in module_defaults to set defaults for this module.
check_mode	Support: full The result is the object as it is defined in the module options and not the object structure of the consul API. For a better overview of what the object structure looks like, take a look at https://developer.hashicorp.com/consul/api-docs/agent/check#list-checks.	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: partial In check mode the diff will show the object as it is defined in the module options and not the object structure of the consul API.	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Register tcp check for service 'nginx'
  community.general.consul_agent_check:
    name: nginx_tcp_check
    service_id: nginx
    interval: 60s
    tcp: localhost:80
    notes: "Nginx Check"

- name: Register http check for service 'nginx'
  community.general.consul_agent_check:
    name: nginx_http_check
    service_id: nginx
    interval: 60s
    http: http://localhost:80/status
    notes: "Nginx Check"

- name: Remove check for service 'nginx'
  community.general.consul_agent_check:
    state: absent
    id: nginx_http_check
    service_id: "{{ nginx_service.ID }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
check dictionary	The check as returned by the consul HTTP API. Returned: always Sample: {"CheckID": "nginx_check", "Interval": "30s", "Notes": "Nginx Check", "ServiceID": "nginx", "Type": "http"}
operation string	The operation performed. Returned: changed Sample: "update"

Authors

• Michael Ilg (@Ilgmi)

Collection links

• Issue Tracker
• Repository (Sources)
• Submit a bug report
• Request a feature
• Communication