open-nomad/website/content/api-docs/acl/roles.mdx

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

341 lines
9.2 KiB
Plaintext
Raw Normal View History

---
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
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| 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
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| 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
[blocking queries](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
| 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
[blocking queries](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
| 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
[blocking queries](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
| 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
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| 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
```