# consul_acl – Manipulate Consul ACL keys and rules

- Synopsis
- Requirements
- Parameters
- Examples
- Return Values
- Status

## 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 - | Default: "localhost" | host of the consul agent defaults to localhost
mgmt_token - |  | a management token is required to manipulate the acl lists
name - |  | 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 |  | rules that should be associated with a given token
scheme - | Default: "http" | the protocol scheme on which the consul agent is running

state
-

Choices:
- present ←
- absent

whether the ACL pair should be present or absent

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

token_type
-

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
      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, 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': {'foo': {'policy': 'write'}, 'bar': {'policy': 'deny'}}}
token string | success | the token associated to the ACL (the ACL's ID) Sample: a2ec332f-04cf-6fba-e8b8-acf62444d3da

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

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

Hint

If you notice any issues in this documentation, you can edit this document to improve it.