consul/website/pages/api-docs/acl/roles.mdx

483 lines
14 KiB
Plaintext
Raw Normal View History

---
layout: api
page_title: ACL Roles - HTTP API
2020-04-07 18:55:19 +00:00
sidebar_title: 'Roles'
sidebar_current: api-acl-roles
2020-04-07 18:55:19 +00:00
description: The /acl/role endpoints manage Consul's ACL Roles.
---
# ACL Role HTTP API
2020-04-07 18:55:19 +00:00
-> **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),
2020-04-06 20:27:35 +00:00
[update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles in Consul.
For more information on how to setup ACLs, please see
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
## Create a Role
This endpoint creates a new ACL role.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ----------- | ------------------ |
| `PUT` | `/acl/role` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
2020-04-06 20:27:35 +00:00
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.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
2020-04-06 20:27:35 +00:00
applied to the role. Added in Consul 1.5.0.
- `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.
2020-04-06 20:27:35 +00:00
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
create the role. If not provided in the JSON body, the value of
2020-04-06 20:27:35 +00:00
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
If not provided at all, the namespace will be inherited from the request's ACL
token or will default to the `default` namespace. Added in Consul 1.7.0.
### Sample Payload
```json
{
2020-04-06 20:27:35 +00:00
"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"]
}
]
}
```
### Sample Request
2020-04-07 23:56:08 +00:00
```shell
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/role
```
### Sample Response
```json
{
2020-04-06 20:27:35 +00:00
"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"]
}
],
"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.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | --------------- | ------------------ |
| `GET` | `/acl/role/:id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
### Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
2020-04-06 20:27:35 +00:00
read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
2020-04-06 20:27:35 +00:00
the role. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request
2020-04-07 23:56:08 +00:00
```shell
$ curl -X GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4
```
### Sample Response
```json
{
2020-04-06 20:27:35 +00:00
"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"]
}
],
"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.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ---------------------- | ------------------ |
| `GET` | `/acl/role/name/:name` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
### Parameters
- `name` `(string: <required>)` - Specifies the Name of the ACL role to
2020-04-06 20:27:35 +00:00
read. This is required and is specified as part of the URL path.
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
2020-04-06 20:27:35 +00:00
the role. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request
2020-04-07 23:56:08 +00:00
```shell
$ curl -X GET http://127.0.0.1:8500/v1/acl/role/name/example-role
```
### Sample Response
```json
{
2020-04-06 20:27:35 +00:00
"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"]
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
```
## Update a Role
This endpoint updates an existing ACL role.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | --------------- | ------------------ |
| `PUT` | `/acl/role/:id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `ID` `(string: <required>)` - Specifies the ID of the role to update. This is
2020-04-06 20:27:35 +00:00
required in the URL path but may also be specified in the JSON body. If specified
in both places then they must match exactly.
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
can only contain alphanumeric characters as well as `-` and `_` and must be
2020-04-06 20:27:35 +00:00
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](/docs/acl/acl-system.html#acl-service-identities) that should be
2020-04-06 20:27:35 +00:00
applied to the role. Added in Consul 1.5.0.
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
the role to update. If not provided in the JSON body, the value of
2020-04-06 20:27:35 +00:00
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
If not provided at all, the namespace will be inherited from the request's ACL
token or will default to the `default` namespace. Added in Consul 1.7.0.
### Sample Payload
```json
{
2020-04-06 20:27:35 +00:00
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
"Name": "example-two",
"Policies": [
{
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "db"
}
]
}
```
### Sample Request
2020-04-07 23:56:08 +00:00
```shell
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/role/8bec74a4-5ced-45ed-9c9d-bca6153490bb
```
### Sample Response
```json
{
2020-04-06 20:27:35 +00:00
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
"Name": "example-two",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "db"
}
],
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
"CreateIndex": 14,
"ModifyIndex": 28
}
```
## Delete a Role
This endpoint deletes an ACL role.
2020-04-06 20:27:35 +00:00
| 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](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
delete. This is required and is specified as part of the URL path.
2020-04-06 20:27:35 +00:00
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
2020-04-06 20:27:35 +00:00
role to delete. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
to the `default` namespace. Added in Consul 1.7.0.
### Sample Request
2020-04-07 23:56:08 +00:00
```shell
$ curl -X DELETE \
http://127.0.0.1:8500/v1/acl/role/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
### Sample Response
2020-04-06 20:27:35 +00:00
```json
true
```
## List Roles
This endpoint lists all the ACL roles.
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | ------------ | ------------------ |
| `GET` | `/acl/roles` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
## Parameters
- `policy` `(string: "")` - Filters the role list to those roles that are
linked with the specific policy ID.
2020-04-06 20:27:35 +00:00
### Parameters
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
2020-04-06 20:27:35 +00:00
the roles for. This value can be specified as the `ns` URL query
parameter or the `X-Consul-Namespace` header. If not provided by either,
the namespace will be inherited from the request's ACL token or will default
2020-04-06 20:27:35 +00:00
to the `default` namespace. The namespace may be specified as '\*' and then
results will be returned for all namespaces. Added in Consul 1.7.0.
## Sample Request
2020-04-07 23:56:08 +00:00
```shell
$ curl -X GET http://127.0.0.1:8500/v1/acl/roles
```
### Sample Response
```json
[
2020-04-06 20:27:35 +00:00
{
"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"]
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
]
```