community.general.consul_agent_service module – Add, modify and delete services 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_service.

New in community.general 9.1.0

Synopsis 

Allows the addition, modification and deletion of services in a consul cluster via the agent.
There are currently no plans to create services and checks in one. This is because the Consul API does not provide checks for a service and the checks themselves do not match the module parameters. Therefore, only a service without checks can be created in this module.

Parameters 

Parameter	Comments
address string	The address to advertise that the service will be listening on. This value will be passed as the `address` parameter to Consul’s `/v1/agent/service/register` API method, so refer to the Consul API documentation for further details.
ca_path string	The CA bundle to use for https connections
enable_tag_override boolean	Specifies to disable the anti-entropy feature for this service’s tags. If EnableTagOverride is set to true then external agents can update this service in the catalog and modify the tags. Choices: `false` ← (default) `true`
host string	Host of the consul agent, defaults to `localhost`. Default: `"localhost"`
id string	Specifies a unique ID for this service. This must be unique per agent. This defaults to the `name` parameter if not provided. If `state=absent`, defaults to the service name if supplied.
meta dictionary	Optional meta data used for filtering. For keys, the characters `A-Z`, `a-z`, `0-9`, `_`, `-` are allowed. Not allowed characters are replaced with underscores.
name string	Unique name for the service on a node, must be unique per node, required if registering a service.
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_port integer	The port on which the service is listening. Can optionally be supplied for registration of a service, that is if `name` or `id` is set.
state string	Whether the service should be present or absent. Choices: `"present"` ← (default) `"absent"`
tags list / elements=string	Tags that will be attached to the service registration.
token string	The token to use for authorization.
validate_certs boolean	Whether to verify the TLS certificate of the consul agent. Choices: `false` `true` ← (default)
weights dictionary	Specifies weights for the service Default: `{"passing": 1, "warning": 1}`
passing integer	Weights for passing. Default: `1`
warning integer	Weights for warning. Default: `1`

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	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: partial In check mode the diff will miss operational attributes.	Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Examples 

- name: Register nginx service with the local consul agent
  community.general.consul_agent_service:
    host: consul1.example.com
    token: some_management_acl
    name: nginx
    service_port: 80

- name: Register nginx with a tcp check
  community.general.consul_agent_service:
    host: consul1.example.com
    token: some_management_acl
    name: nginx
    service_port: 80

- name: Register nginx with an http check
  community.general.consul_agent_service:
    host: consul1.example.com
    token: some_management_acl
    name: nginx
    service_port: 80

- name: Register external service nginx available at 10.1.5.23
  community.general.consul_agent_service:
    host: consul1.example.com
    token: some_management_acl
    name: nginx
    service_port: 80
    address: 10.1.5.23

- name: Register nginx with some service tags
  community.general.consul_agent_service:
    host: consul1.example.com
    token: some_management_acl
    name: nginx
    service_port: 80
    tags:
      - prod
      - webservers

- name: Register nginx with some service meta
  community.general.consul_agent_service:
    host: consul1.example.com
    token: some_management_acl
    name: nginx
    service_port: 80
    meta:
      nginx_version: 1.25.3

- name: Remove nginx service
  community.general.consul_agent_service:
    host: consul1.example.com
    token: some_management_acl
    service_id: nginx
    state: absent

- name: Register celery worker service
  community.general.consul_agent_service:
    host: consul1.example.com
    token: some_management_acl
    name: celery-worker
    tags:
      - prod
      - worker

Return Values 

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

Key	Description
operation string	The operation performed. Returned: changed Sample: `"update"`
service dictionary	The service as returned by the consul HTTP API. Returned: always Sample: `{"Address": "localhost", "ContentHash": "61a245cd985261ac", "Datacenter": "dc1", "EnableTagOverride": false, "ID": "nginx", "Meta": [{"nginx_version": "1.23.3"}], "Port": 80, "Service": "nginx", "Tags": ["http"], "Weights": {"Passing": 1, "Warning": 1}}`

Authors

Michael Ilg (@Ilgmi)

community.general.consul_agent_service module – Add, modify and delete services within a consul cluster

Synopsis

Parameters

Attributes

Examples

Return Values