2022-08-31 14:13:47 +00:00
|
|
|
---
|
|
|
|
layout: api
|
|
|
|
page_title: ACL Roles - HTTP API
|
|
|
|
description: The /acl/roles endpoints are used to configure and manage ACL roles.
|
|
|
|
---
|
|
|
|
|
|
|
|
# ACL Roles HTTP API
|
|
|
|
|
|
|
|
The `/acl/roles` and `/acl/role/` endpoints are used to manage ACL Roles.
|
|
|
|
|
|
|
|
## Create Role
|
|
|
|
|
|
|
|
This endpoint creates an ACL Role. The request is always forwarded to the
|
|
|
|
authoritative region.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ----------- | ------------------ |
|
|
|
|
| `POST` | `/acl/role` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2022-08-31 14:13:47 +00:00
|
|
|
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------ |
|
|
|
|
| `NO` | `management` |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `Name` `(string: <required>)` - Specifies the human-readable name of the ACL
|
|
|
|
Role. The name can contain alphanumeric characters, dashes, and underscores.
|
|
|
|
This name must be unique and must not exceed 128 characters.
|
|
|
|
|
|
|
|
- `Description` `(string: <optional>)` - A free form human-readable description
|
|
|
|
of the ACL Role. It must not exceed 256 characters.
|
|
|
|
|
|
|
|
- `Policies` `(array<ACLRolePolicyLink>)` The list of policies that should be
|
|
|
|
applied to the role. An `ACLRolePolicyLink` is an object with a `"Name"` field
|
|
|
|
to specify a policy.
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Name": "example-acl-role",
|
|
|
|
"Description": "my example ACL Role",
|
|
|
|
"Policies": [
|
|
|
|
{
|
|
|
|
"Name": "example-acl-policy"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--request POST \
|
|
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
|
|
--data @payload.json \
|
|
|
|
https://localhost:4646/v1/acl/role
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"CreateIndex": 26,
|
|
|
|
"Description": "my example ACL Role",
|
|
|
|
"ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
|
|
|
|
"ModifyIndex": 26,
|
|
|
|
"Name": "example-acl-role",
|
|
|
|
"Policies": [
|
|
|
|
{
|
|
|
|
"Name": "example-acl-policy"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Update Token
|
|
|
|
|
|
|
|
This endpoint updates an existing ACL Role. The request is always forwarded to the
|
|
|
|
authoritative region.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | -------------------- | ------------------ |
|
|
|
|
| `POST` | `/acl/role/:role_id` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2022-08-31 14:13:47 +00:00
|
|
|
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------ |
|
|
|
|
| `NO` | `management` |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `ID` `(string: <required>)` - Specifies the ACL Role, by ID, that is being
|
|
|
|
updated. Must match payload body and request path.
|
|
|
|
|
|
|
|
- `Name` `(string: <required>)` - Specifies the human-readable name of the ACL
|
|
|
|
Role. The name can contain alphanumeric characters, dashes, and underscores.
|
|
|
|
This name must be unique a must not exceed 128 characters.
|
|
|
|
|
|
|
|
- `Description` `(string: <optional>)` - A free form human-readable description
|
|
|
|
of the ACL Role. It must not exceed 256 characters.
|
|
|
|
|
|
|
|
- `Policies` `(array<ACLRolePolicyLink>)` The list of policies that should be
|
|
|
|
applied to the role. An `ACLRolePolicyLink` is an object with a `"Name"` field
|
|
|
|
to specify a policy.
|
|
|
|
|
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
|
|
|
|
"Name": "example-acl-role",
|
|
|
|
"Description": "my example ACL Role",
|
|
|
|
"Policies": [
|
|
|
|
{
|
|
|
|
"Name": "example-acl-policy"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--request POST \
|
|
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
|
|
--data @payload.json \
|
|
|
|
https://localhost:4646/v1/acl/role/77c50812-fcdd-701b-9f1a-6cf55387b09d
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"CreateIndex": 26,
|
|
|
|
"Description": "my example ACL Role",
|
|
|
|
"ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
|
|
|
|
"ModifyIndex": 26,
|
|
|
|
"Name": "example-acl-role",
|
|
|
|
"Policies": [
|
|
|
|
{
|
|
|
|
"Name": "example-acl-policy"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## List Roles
|
|
|
|
|
|
|
|
This endpoint lists all ACL Roles. This lists the roles that have been replicated
|
|
|
|
to the region, and may lag behind the authoritative region.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | ------------ | ------------------ |
|
|
|
|
| `GET` | `/acl/roles` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries),
|
|
|
|
[consistency modes](/nomad/api-docs#consistency-modes) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2022-08-31 14:13:47 +00:00
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
| ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
|
|
| `YES` | `all` | `management` for all roles.<br />Output when given a non-management token will be limited to the roles on the token itself |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `prefix` `(string: "")` - Specifies a string to filter ACL Roles based on an
|
|
|
|
ID prefix. This is specified as a query string parameter. Because the value
|
|
|
|
is decoded to bytes, the prefix must have an even number of hexadecimal
|
|
|
|
characters (`0-9a-f`).
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
|
|
https://localhost:4646/v1/acl/roles
|
|
|
|
```
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
|
|
https://localhost:4646/v1/acl/roles?prefix=25ba81
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
{
|
|
|
|
"CreateIndex": 26,
|
|
|
|
"Description": "my example ACL Role",
|
|
|
|
"ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
|
|
|
|
"ModifyIndex": 26,
|
|
|
|
"Name": "example-acl-role",
|
|
|
|
"Policies": [
|
|
|
|
{
|
|
|
|
"Name": "example-acl-policy"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Read Role by ID
|
|
|
|
|
|
|
|
This endpoint reads an ACL Role with the given ID. This queries the role that
|
|
|
|
has been replicated to the region, and may lag behind the authoritative region.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | -------------------- | ------------------ |
|
|
|
|
| `GET` | `/acl/role/:role_id` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries),
|
|
|
|
[consistency modes](/nomad/api-docs#consistency-modes) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2022-08-31 14:13:47 +00:00
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ----------------------------------------- |
|
|
|
|
| `YES` | `all` | `management` or token with access to role |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:role_id` `(string: <required>)` - Specifies the ID of the ACL Role. This is
|
|
|
|
specified as part of the path.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
|
|
https://localhost:4646/v1/acl/role/77c50812-fcdd-701b-9f1a-6cf55387b09d
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"CreateIndex": 26,
|
|
|
|
"Description": "my example ACL Role",
|
|
|
|
"ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
|
|
|
|
"ModifyIndex": 26,
|
|
|
|
"Name": "example-acl-role",
|
|
|
|
"Policies": [
|
|
|
|
{
|
|
|
|
"Name": "example-acl-policy"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Read Role by Name
|
|
|
|
|
|
|
|
This endpoint reads an ACL Role with the given name. This queries the role that
|
|
|
|
has been replicated to the region, and may lag behind the authoritative region.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------------------- | ------------------ |
|
|
|
|
| `GET` | `/acl/role/name/:role_name` | `application/json` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries),
|
|
|
|
[consistency modes](/nomad/api-docs#consistency-modes) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2022-08-31 14:13:47 +00:00
|
|
|
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ----------------------------------------- |
|
|
|
|
| `YES` | `all` | `management` or token with access to role |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `:role_name` `(string: <required>)` - Specifies the Name of the ACL Role. This is
|
|
|
|
specified as part of the path.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
|
|
https://localhost:4646/v1/acl/role/name/example-acl-role
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"CreateIndex": 26,
|
|
|
|
"Description": "my example ACL Role",
|
|
|
|
"ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
|
|
|
|
"ModifyIndex": 26,
|
|
|
|
"Name": "example-acl-role",
|
|
|
|
"Policies": [
|
|
|
|
{
|
|
|
|
"Name": "example-acl-policy"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Delete Role
|
|
|
|
|
|
|
|
This endpoint deletes the ACL role as identified by the ID. This request is
|
|
|
|
always forwarded to the authoritative region.
|
|
|
|
|
|
|
|
| Method | Path | Produces |
|
|
|
|
| -------- | -------------------- | -------------- |
|
|
|
|
| `DELETE` | `/acl/role/:role_id` | `(empty body)` |
|
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2022-08-31 14:13:47 +00:00
|
|
|
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------ |
|
|
|
|
| `NO` | `management` |
|
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `role_id` `(string: <required>)` - Specifies the ID of role to delete and is
|
|
|
|
specified as part of the path.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ curl \
|
|
|
|
--request DELETE \
|
|
|
|
--header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
|
|
|
|
https://localhost:4646/v1/acl/role/77c50812-fcdd-701b-9f1a-6cf55387b09d
|
|
|
|
```
|