A new platform for documentation and tutorials is launching soon.

We are migrating Consul documentation into HashiCorp Developer, our new developer experience.

Join Now
Type '/' to Search

»Consul ACL Roles

Command: consul acl role

The acl role command is used to manage Consul's ACL roles. It exposes commands for creating, updating, reading, deleting, and listing roles. This command is available in Consul 1.5.0 and newer.

ACL roles may also be managed via the HTTP API.

Note: All of the example subcommands in this document will require a valid Consul token with the appropriate permissions. Either set the CONSUL_HTTP_TOKEN environment variable to the token's secret ID or pass the secret ID as the value of the -token parameter.

»Usage

Usage: consul acl role <subcommand>

For the exact documentation for your Consul version, run consul acl role -h to view the complete list of subcommands.

Usage: consul acl role <subcommand> [options] [args]

  ...

Subcommands:
    create    Create an ACL role
    delete    Delete an ACL role
    list      Lists ACL roles
    read      Read an ACL role
    update    Update an ACL role

Usage: consul acl role <subcommand> [options] [args]

  ...

Subcommands:
    create    Create an ACL role
    delete    Delete an ACL role
    list      Lists ACL roles
    read      Read an ACL role
    update    Update an ACL role

For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar.

»Identifying Roles

Several of the subcommands need to operate on a specific role. Those subcommands support specifying the role by its ID using the -id parameter or by name using the -name parameter.

When specifying the role by its ID a unique role ID prefix may be specified instead of the entire UUID. As long as it is unique it will be resolved to the full UUID and used.

»Basic Examples

Create a new ACL role:

$ consul acl role create -name "new-role" \
                       -description "This is an example role" \
                       -policy-id 06acc965

$ consul acl role create -name "new-role" \
                       -description "This is an example role" \
                       -policy-id 06acc965

List all roles:

$ consul acl role list

$ consul acl role list

Update a role:

$ consul acl role update -name "other-role" -datacenter "dc1"

$ consul acl role update -name "other-role" -datacenter "dc1"

Read a role:

$ consul acl role read -id 0479e93e-091c-4475-9b06-79a004765c24

$ consul acl role read -id 0479e93e-091c-4475-9b06-79a004765c24

Delete a role

$ consul acl role delete -name "my-role"

$ consul acl role delete -name "my-role"