community.general.consul_role module – Manipulate Consul roles

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

New in community.general 7.5.0

Synopsis

Parameters

Parameter

Comments

ca_path

string

The CA bundle to use for https connections

description

string

Description of the role.

If not specified, the assigned description will not be changed.

host

string

Host of the consul agent, defaults to localhost.

Default: "localhost"

name

string / required

A name used to identify the role.

node_identities

list / elements=dictionary

List of node identities to attach to the role.

If not specified, any node identities currently assigned will not be changed.

If the parameter is an empty array ([]), any node identities assigned will be unassigned.

datacenter

string / required

The nodes datacenter.

This will result in effective policy only being valid in this datacenter.

node_name

aliases: 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 _.

This suboption has been renamed from node_identities[].name to node_identities[].node_name in community.general 8.3.0. The old name can still be used.

policies

list / elements=dictionary

List of policies to attach to the role. Each policy is a dict.

If the parameter is left blank, any policies currently assigned will not be changed.

Any empty array ([]) will clear any policies previously set.

id

string

The ID of the policy to attach to this role; 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 role; 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.

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_identities

list / elements=dictionary

List of service identities to attach to the role.

If not specified, any service identities currently assigned will not be changed.

If the parameter is an empty array ([]), any node identities assigned will be unassigned.

datacenters

list / elements=string

The datacenters the policies will be effective.

This will result in effective policy only being valid in this datacenter.

If an empty array ([]) is specified, the policies will valid in all datacenters.

including those which do not yet exist but may in the future.

service_name

aliases: 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 _.

This suboption has been renamed from service_identities[].name to service_identities[].service_name in community.general 8.3.0. The old name can still be used.

state

string

whether the role should be present or absent.

Choices:

  • "present" ← (default)

  • "absent"

templated_policies

list / elements=dictionary

added in community.general 8.3.0

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.

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

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

added in community.general 8.3.0

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: Create a role with 2 policies
  community.general.consul_role:
    host: consul1.example.com
    token: some_management_acl
    name: foo-role
    policies:
      - id: 783beef3-783f-f41f-7422-7087dc272765
      - name: "policy-1"

- name: Create a role with service identity
  community.general.consul_role:
    host: consul1.example.com
    token: some_management_acl
    name: foo-role-2
    service_identities:
      - name: web
        datacenters:
          - dc1

- name: Create a role with node identity
  community.general.consul_role:
    host: consul1.example.com
    token: some_management_acl
    name: foo-role-3
    node_identities:
      - name: node-1
        datacenter: dc2

- name: Remove a role
  community.general.consul_role:
    host: consul1.example.com
    token: some_management_acl
    name: foo-role-3
    state: absent

Return Values

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

Key

Description

operation

string

The operation performed on the role.

Returned: changed

Sample: "update"

role

dictionary

The role object.

Returned: success

Sample: {"CreateIndex": 39, "Description": "", "Hash": "Trt0QJtxVEfvTTIcdTUbIJRr6Dsi6E4EcwSFxx9tCYM=", "ID": "9a300b8d-48db-b720-8544-a37c0f5dafb5", "ModifyIndex": 39, "Name": "foo-role", "Policies": [{"ID": "b1a00172-d7a1-0e66-a12e-7a4045c4b774", "Name": "foo-access"}]}

Authors

  • Håkon Lerring (@Hakon)