github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Consul is a distributed, highly available, and data center aware solution to connect and configure applications across dynamic, distributed infrastructure.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
21161 Commits
1702 Branches
457 Tags
697 MiB
 
 
 
 
 
 
Branch: CC-7146/hcp-link-item-in-the-nav-bar
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'CC-7146/hcp-link-item-in-the-nav-bar'
${ noResults }
consul/website/content/api-docs/acl/roles.mdx

634 lines
18 KiB
Raw Permalink Blame History

---
layout: api
page_title: ACL Roles - HTTP API
description: The /acl/role endpoints manage Consul's ACL Roles.
---
# ACL Role HTTP API
-> **1.5.0+:** The role APIs are available in Consul versions 1.5.0 and newer.
The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role),
[update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles in Consul.
For more information on how to setup ACLs, refer to the following resources:
- [Access control list (ACL) overview](/consul/docs/security/acl)
- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
## Create a Role
This endpoint creates a new ACL role.
| Method | Path | Produces |
| ------ | ----------- | ------------------ |
| `PUT` | `/acl/role` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
The corresponding CLI command is [`consul acl role create`](/consul/commands/acl/role/create).
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you create.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
can contain alphanumeric characters, dashes `-`, and underscores `_`.
This name must be unique.
- `Description` `(string: "")` - Free form human readable description of the role.
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
applied to the role. A PolicyLink is an object with an "ID" and/or "Name"
field to specify a policy. With the PolicyLink, roles can be linked to
policies either by the policy name or by the policy ID. When policies are
linked by name they will be internally resolved to the policy ID. With
linking roles internally by IDs, Consul enables policy renaming without
breaking tokens.
- `TemplatedPolicies` `(list of maps)` - The list of [templated policies](/consul/docs/security/acl#templated-policies)
that should be applied to the role.
- `TemplateName` `(string: <required>)` - The templated policy name.
- `TemplateVariables` `(map of strings|maps: <optional>)` - The templated policy variables. Not all templated policies
require variables.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/consul/docs/security/acl#service-identities) that should be
applied to the role.
- `ServiceName` `(string: <required>)` - The name of the service. The name
must be no longer than 256 characters, must start and end with a lowercase
alphanumeric character, and can only contain lowercase alphanumeric
characters as well as `-` and `_`.
- `Datacenters` `(array<string>)` - Specifies the datacenters the effective
policy is valid within. When no datacenters are provided the effective
policy is valid in all datacenters including those which do not yet exist
but may in the future.
- `NodeIdentities` `(array<NodeIdentity>)` - The list of [node
identities](/consul/docs/security/acl#node-identities) that should be
applied to the role.
- `NodeName` `(string: <required>)` - The name of the node. The name
must be no longer than 256 characters, must start and end with a lowercase
alphanumeric character, and can only contain lowercase alphanumeric
characters as well as `-` and `_`.
- `Datacenter` `(string: <required>)` - Specifies the nodes datacenter. This
will result in effective policy only being valid in that datacenter.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you create.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### Sample Payload
```json
{
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765"
},
{
"Name": "node-read"
}
],
"TemplatedPolicies": [
{
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "api"
}
},
{
"TemplateName": "builtin/dns"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": ["dc1"]
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
]
}
```
### Sample Request
```shell-session
$ curl --request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/role
```
### Sample Response
```json
{
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": ["dc1"]
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
],
"TemplatedPolicies": [
{
"TemplateID": "00000000-0000-0000-0000-000000000003",
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "api"
}
},
{
"TemplateID": "00000000-0000-0000-0000-000000000005",
"TemplateName": "builtin/dns"
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
```
## Read a Role
This endpoint reads an ACL role with the given ID. If no role exists with the
given ID, a 404 is returned instead of a 200 response.
| Method | Path | Produces |
| ------ | --------------- | ------------------ |
| `GET` | `/acl/role/:id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
The corresponding CLI command is [`consul acl role read`](/consul/commands/acl/role/read).
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the role you lookup.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl --request GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4
```
### Sample Response
```json
{
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": ["dc1"]
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
],
"TemplatedPolicies": [
{
"TemplateID": "00000000-0000-0000-0000-000000000003",
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "api"
}
},
{
"TemplateID": "00000000-0000-0000-0000-000000000005",
"TemplateName": "builtin/dns"
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
```
## Read a Role by Name
This endpoint reads an ACL role with the given name. If no role exists with the
given name, a 404 is returned instead of a 200 response.
| Method | Path | Produces |
| ------ | ---------------------- | ------------------ |
| `GET` | `/acl/role/name/:name` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
The corresponding CLI command is [`consul acl role read -name=<string>`](/consul/commands/acl/role/read#name).
### Path Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL role to read.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you lookup.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl --request GET http://127.0.0.1:8500/v1/acl/role/name/example-role
```
### Sample Response
```json
{
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": ["dc1"]
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
],
"TemplatedPolicies": [
{
"TemplateID": "00000000-0000-0000-0000-000000000003",
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "api"
}
},
{
"TemplateID": "00000000-0000-0000-0000-000000000005",
"TemplateName": "builtin/dns"
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
```
## Update a Role
This endpoint updates an existing ACL role.
| Method | Path | Produces |
| ------ | --------------- | ------------------ |
| `PUT` | `/acl/role/:id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
The corresponding CLI command is [`consul acl role update`](/consul/commands/acl/role/update).
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the role you update.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `ID` `(string: <optional>)` - If specified, this field must be an exact match
with the `id` path parameter.
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
can only contain alphanumeric characters as well as `-` and `_` and must be
unique.
- `Description` `(string: "")` - Free form human readable description of the role.
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
applied to the role. A PolicyLink is an object with an "ID" and/or "Name"
field to specify a policy. With the PolicyLink, roles can be linked to
policies either by the policy name or by the policy ID. When policies are
linked by name they will be internally resolved to the policy ID. With
linking roles internally by IDs, Consul enables policy renaming without
breaking tokens.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/consul/docs/security/acl#service-identities) that should be
applied to the role. Added in Consul 1.5.0.
- `NodeIdentities` `(array<NodeIdentity>)` - The list of [node
identities](/consul/docs/security/acl#node-identities) that should be
applied to the role. Added in Consul 1.8.1.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you update.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
### Sample Payload
```json
{
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
"Name": "example-two",
"Policies": [
{
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "db"
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
],
"TemplatedPolicies": [
{
"TemplateName": "builtin/dns"
}
]
}
```
### Sample Request
```shell-session
$ curl --request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/role/8bec74a4-5ced-45ed-9c9d-bca6153490bb
```
### Sample Response
```json
{
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
"Name": "example-two",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "db"
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
],
"TemplatedPolicies": [
{
"TemplateID": "00000000-0000-0000-0000-000000000005",
"TemplateName": "builtin/dns"
}
],
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
"CreateIndex": 14,
"ModifyIndex": 28
}
```
## Delete a Role
This endpoint deletes an ACL role.
| Method | Path | Produces |
| -------- | --------------- | ------------------ |
| `DELETE` | `/acl/role/:id` | `application/json` |
Even though the return type is application/json, the value is either true or
false indicating whether the delete succeeded.
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
The corresponding CLI command is [`consul acl role delete`](/consul/commands/acl/role/delete).
### Path Parameters
- `id` `(string: <required>)` - Specifies the UUID of the role you delete.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the role you delete.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl --request DELETE \
http://127.0.0.1:8500/v1/acl/role/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
### Sample Response
```json
true
```
## List Roles
This endpoint lists all the ACL roles.
| Method | Path | Produces |
| ------ | ------------ | ------------------ |
| `GET` | `/acl/roles` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
The corresponding CLI command is [`consul acl role list`](/consul/commands/acl/role/list).
### Query Parameters
- `policy` `(string: "")` - Filters the role list to those roles that are
linked with this specific policy ID.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the roles in the specified namespace.
The namespace may be specified as '\*' to return results for all namespaces.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
## Sample Request
```shell-session
$ curl --request GET http://127.0.0.1:8500/v1/acl/roles
```
### Sample Response
```json
[
{
"ID": "5e52a099-4c90-c067-5478-980f06be9af5",
"Name": "node-read",
"Description": "",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"Hash": "K6AbfofgiZ1BEaKORBloZf7WPdg45J/PipHxQiBlK1U=",
"CreateIndex": 50,
"ModifyIndex": 50
},
{
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": ["dc1"]
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
]
```
## Methods to specify namespace <EnterpriseAlert inline />
ACL role endpoints
support several methods for specifying the namespace of the ACL role resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to [create](#create-a-role) and [update](#update-a-role) endpoints
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace