W3cubDocs

/Ansible

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