community.general.consul_token module – Manipulate Consul tokens

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

New in community.general 8.3.0

Synopsis

• Allows the addition, modification and deletion of tokens in a Consul cluster using the agent. For more details on using and configuring ACLs, see https://www.consul.io/docs/guides/acl.html.

Parameters

Parameter	Comments
accessor_id string	Specifies a UUID to use as the token’s Accessor ID. If not specified a UUID is generated for this field.
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.
description string	Free form human readable description of the token.
expiration_ttl string	This is a convenience field and if set it initializes the expiration_time. Can be specified in the form of 60s or 5m (that is, 60 seconds or 5 minutes, respectively). Ingored when the token is updated!
host string	Host of the Consul agent. If unset, the host component of url is used, and localhost when url is not set either.
local boolean	If true, indicates that the token should not be replicated globally and instead be local to the current datacenter. Choices: false true
node_identities list / elements=dictionary	List of node identities to attach to the token. If not specified, any node identities currently assigned are not changed. If the parameter is an empty array ([]), any node identities assigned are unassigned.
datacenter string / required	The nodes datacenter. This results in effective token only being valid in this datacenter.
node_name string / required	The name of the node. Must not be longer than 256 characters, must start and end with a lowercase alphanumeric character. May only contain lowercase alphanumeric characters as well as - and _.
policies list / elements=dictionary	List of policies to attach to the token. Each policy is a dict. If the parameter is left blank, any policies currently assigned are not changed. Any empty array ([]) clears any policies previously set.
id string	The ID of the policy to attach to this token; see community.general.consul_policy for more info. Either this or policies[].name must be specified.
name string	The name of the policy to attach to this token; see community.general.consul_policy for more info. Either this or policies[].id must be specified.
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.
roles list / elements=dictionary	List of roles to attach to the token. Each role is a dict. If the parameter is left blank, any roles currently assigned are not changed. Any empty array ([]) clears any roles previously set.
id string	The ID of the role to attach to this token; see community.general.consul_role for more info. Either this or roles[].name must be specified.
name string	The name of the role to attach to this token; see community.general.consul_role for more info. Either this or roles[].id must be specified.
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.
secret_id string	Specifies a UUID to use as the token’s Secret ID. If not specified a UUID is generated for this field.
service_identities list / elements=dictionary	List of service identities to attach to the token. If not specified, any service identities currently assigned are not changed. If the parameter is an empty array ([]), any node identities assigned are unassigned.
datacenters list / elements=string	The datacenters where the token is effective. If an empty array ([]) is specified, the token is valid in all datacenters. Including those which do not yet exist but may in the future.
service_name string / required	The name of the service. Must not be longer than 256 characters, must start and end with a lowercase alphanumeric character. May only contain lowercase alphanumeric characters as well as - and _.
state string	Whether the token should be present or absent. Choices: "present" ← (default) "absent"
templated_policies list / elements=dictionary	The list of templated policies that should be applied to the role.
template_name string / required	The templated policy name.
template_variables dictionary	The templated policy variables. Not all templated policies require variables.
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.
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 added in community.general 8.3.0	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 misses operational attributes.	Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Create / Update a token by accessor_id
  community.general.consul_token:
    state: present
    accessor_id: 07a7de84-c9c7-448a-99cc-beaf682efd21
    token: 8adddd91-0bd6-d41d-ae1a-3b49cfa9a0e8
    roles:
      - name: role1
      - name: role2
    service_identities:
      - service_name: service1
        datacenters: [dc1, dc2]
    node_identities:
      - node_name: node1
        datacenter: dc1
    expiration_ttl: 50m

- name: Delete a token
  community.general.consul_token:
    state: absent
    accessor_id: 07a7de84-c9c7-448a-99cc-beaf682efd21
    token: 8adddd91-0bd6-d41d-ae1a-3b49cfa9a0e8

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"
token dictionary	The token as returned by the Consul HTTP API. Returned: always Sample: {"AccessorID": "07a7de84-c9c7-448a-99cc-beaf682efd21", "CreateIndex": 632, "CreateTime": "2024-01-14T21:53:01.402749174+01:00", "Description": "Testing", "Hash": "rj5PeDHddHslkpW7Ij4OD6N4bbSXiecXFmiw2SYXg2A=", "Local": false, "ModifyIndex": 633, "SecretID": "bd380fba-da17-7cee-8576-8d6427c6c930", "ServiceIdentities": [{"ServiceName": "test"}]}

Authors

• Florian Apolloner (@apollo13)

Collection links

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