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

Note

This plugin is part of the community.general collection (version 2.5.1).

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)