community.general.consul_acl module – Manipulate Consul ACL keys and rules

Note

This module is part of the community.general collection (version 6.6.2).

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. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.consul_acl.

Synopsis

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

Requirements

The below requirements are needed on the host that executes this module.

  • python-consul

  • pyhcl

  • requests

Parameters

Parameter

Comments

host

string

host of the consul agent defaults to localhost

Default: "localhost"

mgmt_token

string / required

a management token is required to manipulate the acl lists

name

string

the name that should be associated with the acl key, this is opaque to Consul

port

integer

the port on which the consul agent is running

Default: 8500

rules

list / elements=dictionary

rules that should be associated with a given token

scheme

string

the protocol scheme on which the consul agent is running

Default: "http"

state

string

whether the ACL pair should be present or absent

Choices:

  • "present" ← (default)

  • "absent"

token

string

the token key identifying an ACL rule set. If generated by consul this will be a UUID

token_type

string

the type of token that should be created

Choices:

  • "client" ← (default)

  • "management"

validate_certs

boolean

whether to verify the tls certificate of the consul agent

Choices:

  • false

  • true ← (default)

Attributes

Attribute

Support

Description

check_mode

Support: none

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Create an ACL with rules
  community.general.consul_acl:
    host: consul1.example.com
    mgmt_token: some_management_acl
    name: Foo access
    rules:
      - key: "foo"
        policy: read
      - key: "private/foo"
        policy: deny

- name: Create an ACL with a specific token
  community.general.consul_acl:
    host: consul1.example.com
    mgmt_token: some_management_acl
    name: Foo access
    token: my-token
    rules:
      - key: "foo"
        policy: read

- name: Update the rules associated to an ACL token
  community.general.consul_acl:
    host: consul1.example.com
    mgmt_token: some_management_acl
    name: Foo access
    token: some_client_token
    rules:
      - event: "bbq"
        policy: write
      - key: "foo"
        policy: read
      - key: "private"
        policy: deny
      - keyring: write
      - node: "hgs4"
        policy: write
      - operator: read
      - query: ""
        policy: write
      - service: "consul"
        policy: write
      - session: "standup"
        policy: write

- name: Remove a token
  community.general.consul_acl:
    host: consul1.example.com
    mgmt_token: some_management_acl
    token: 172bd5c8-9fe9-11e4-b1b0-3c15c2c9fd5e
    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 ACL

Returned: changed

Sample: "update"

rules

dictionary

the HCL JSON representation of the rules associated to the ACL, in the format described in the Consul documentation (https://www.consul.io/docs/guides/acl.html#rule-specification).

Returned: status == “present”

Sample: {"key": {"bar": {"policy": "deny"}, "foo": {"policy": "write"}}}

token

string

the token associated to the ACL (the ACL’s ID)

Returned: success

Sample: "a2ec332f-04cf-6fba-e8b8-acf62444d3da"

Authors

  • Steve Gargan (@sgargan)

  • Colin Nolan (@colin-nolan)