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

Note

This plugin is part of the community.general collection (version 3.8.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_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	Choices/Defaults	Comments
host string	Default: "localhost"	host of the consul agent defaults to 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	Default: 8500	the port on which the consul agent is running
rules list / elements=dictionary		rules that should be associated with a given token
scheme string	Default: "http"	the protocol scheme on which the consul agent is running
state string	Choices: present ← absent	whether the ACL pair should be present or absent
token string		the token key identifying an ACL rule set. If generated by consul this will be a UUID
token_type string	Choices: client ← management	the type of token that should be created
validate_certs boolean	Choices: no yes ←	whether to verify the tls certificate of the consul agent

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	Returned	Description
operation string	changed	the operation performed on the ACL Sample: update
rules string	status == "present"	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). Sample: {'key': {'bar': {'policy': 'deny'}, 'foo': {'policy': 'write'}}}
token string	success	the token associated to the ACL (the ACL's ID) Sample: a2ec332f-04cf-6fba-e8b8-acf62444d3da

Authors

Steve Gargan (@sgargan)
Colin Nolan (@colin-nolan)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/consul_acl_module.html

Docs

Docs4dev

Title here