mirror of https://github.com/hashicorp/consul
86 lines
2.1 KiB
Markdown
86 lines
2.1 KiB
Markdown
---
|
|
layout: commands
|
|
page_title: 'Commands: ACL Role'
|
|
---
|
|
|
|
# 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](/consul/api-docs/acl/roles).
|
|
|
|
-> **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.
|
|
|
|
```text
|
|
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:
|
|
|
|
```shell-session
|
|
$ consul acl role create -name "new-role" \
|
|
-description "This is an example role" \
|
|
-policy-id 06acc965
|
|
```
|
|
|
|
List all roles:
|
|
|
|
```shell-session
|
|
$ consul acl role list
|
|
```
|
|
|
|
Update a role:
|
|
|
|
```shell-session
|
|
$ consul acl role update -name "other-role" -datacenter "dc1"
|
|
```
|
|
|
|
Read a role:
|
|
|
|
```shell-session
|
|
$ consul acl role read -id 0479e93e-091c-4475-9b06-79a004765c24
|
|
```
|
|
|
|
Delete a role
|
|
|
|
```shell-session
|
|
$ consul acl role delete -name "my-role"
|
|
```
|