-
Notifications
You must be signed in to change notification settings - Fork 2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add documentation for ACL token expiration and ACL roles. (#14332)
The ACL command docs are now found within a sub-dir like the operator command docs. Updates to the ACL token commands to accommodate token expiry have also been added. The ACL API docs are now found within a sub-dir like the operator API docs. The ACL docs now include the ACL roles endpoint as well as updated ACL token endpoints for token expiration. The configuration section is also updated to accommodate the new ACL and server parameters for the new ACL features.
- Loading branch information
Showing
25 changed files
with
851 additions
and
136 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| --- | ||
| layout: api | ||
| page_title: ACL - HTTP API | ||
| description: |- | ||
| The /acl endpoints provide access to the ACL subsystem. | ||
| --- | ||
|
|
||
| # ACL HTTP API | ||
|
|
||
| The `/acl` endpoints provide access to the ACL subsystem which includes | ||
| ACL bootstrapping, ACL Policies, ACL Roles, and ACL Tokens. For more details | ||
| about ACLs, please see the | ||
| [ACL Guide](https://learn.hashicorp.com/collections/nomad/access-control). | ||
|
|
||
| Please choose a subsection in the navigation for more information. |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,340 @@ | ||
| --- | ||
| 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](/api-docs#blocking-queries) and | ||
| [required ACLs](/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](/api-docs#blocking-queries) and | ||
| [required ACLs](/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](/api-docs#blocking-queries), | ||
| [consistency modes](/api-docs#consistency-modes) and | ||
| [required ACLs](/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](/api-docs#blocking-queries), | ||
| [consistency modes](/api-docs#consistency-modes) and | ||
| [required ACLs](/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](/api-docs#blocking-queries), | ||
| [consistency modes](/api-docs#consistency-modes) and | ||
| [required ACLs](/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](/api-docs#blocking-queries) and | ||
| [required ACLs](/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 | ||
| ``` |
Oops, something went wrong.