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 14.0.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 using 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, the module does not attempt to determine changes and it always reports a changed occurred. An API method is planned to supply this metadata so at that stage change management is to 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. If unset, the value of the CONSUL_CACERT environment variable is used when set. This is supported since community.general 13.4.0.
host string	Host of the Consul agent. If unset, the host component of url is used, and localhost when url is not set either.
http string	Checks can be registered with an HTTP endpoint. This means that Consul checks 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 is returned in the response as CheckId.
interval string	The interval at which the service check is 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 is used by default, for example 10 is equivalent to 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. If unset, the port component of url is used, and 8500 when that does not specify one either.
scheme string	The protocol scheme on which the Consul agent is running. If unset, a true value in the CONSUL_HTTP_SSL environment variable selects https, otherwise the scheme component of url is used, and http when that does not specify one either. A false CONSUL_HTTP_SSL does not downgrade an https url.
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 is used by default, for example 10 is equivalent to 10s.
token string	The token to use for authorization. If unset, the value of the CONSUL_HTTP_TOKEN environment variable is used. This is supported since community.general 13.4.0.
ttl string	Checks can be registered with a TTL instead of a args and interval this means that the service checks in with the agent before the TTL expires. If it does not the check is 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 is used by default, for example 10 is equivalent to 10s. Mutually exclusive with args, tcp and http.
url string added in community.general 13.4.0	The address of the Consul agent, in the host:port or scheme://host:port form. The scheme and the port are optional, the host is not. host, port and scheme take precedence over the components of this option. If unset, the value of the CONSUL_HTTP_ADDR environment variable is used when set. An address these modules cannot use, a unix:// socket for example, makes the module fail, unless host, port and scheme are all set, in which case the address is not consulted at all.
validate_certs boolean	Whether to verify the TLS certificate of the Consul agent. If unset, the value of the CONSUL_HTTP_SSL_VERIFY environment variable is used when set. This is supported since community.general 13.4.0. 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 shows the object as it is defined in the module options and not the object structure of the Consul API.	Returns 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)
• Ask for help
• Submit a bug report
• Request a feature
• Communication