Documentation

consul_acl - Manipulate Consul ACL keys and rules

New in version 2.0.

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 (on host that executes module)

  • python >= 2.6
  • python-consul
  • pyhcl
  • requests

Options

parameter required default choices comments
host
 no localhost
host of the consul agent defaults to localhost
mgmt_token
 no
a management token is required to manipulate the acl lists
name
 no
the name that should be associated with the acl key, this is opaque to Consul
port
 no 8500
the port on which the consul agent is running
rules
 no
a list of the rules that should be associated with a given token
scheme
(added in 2.1)
 no http
the protocol scheme on which the consul agent is running
state
 no present
  • present
  • absent
whether the ACL pair should be present or absent
token
 no
the token key indentifying an ACL rule set. If generated by consul this will be a UUID
token_type
 no client
  • client
  • management
the type of token that should be created, either management or client
validate_certs
(added in 2.1)
 no True
whether to verify the tls certificate of the consul agent

Examples

- name: create an ACL with rules
  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
  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
  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
  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 Return Values, the following are the fields unique to this module:

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


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.