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 10.0.1).

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)