Docs4dev
Docs
ansible / 2.6 / modules / consul_acl_module.html

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

The below requirements are needed on the host that executes this module.

  • python >= 2.6
  • 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 Default:
8500
the port on which the consul agent is running
rules
a list of the rules that should be associated with a given token
scheme
(added in 2.1)
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 indentifying 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, either management or client
validate_certs
(added in 2.1)
Default:
"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 flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

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

Hint

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

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.6/modules/consul_acl_module.html