88 lines
2.3 KiB
Plaintext
88 lines
2.3 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: ACL Role'
|
|
description: |
|
|
The `consul acl role` command interacts with Consul's ACL roles. It exposes commands for creating, updating, reading, deleting, and listing roles. Roles consist of one or more ACL policies authorizing communication in the service mesh.
|
|
---
|
|
|
|
# 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"
|
|
```
|