From 20f71cf3e45c9502995b536661e99c4f26c8438a Mon Sep 17 00:00:00 2001 From: James Rasell Date: Wed, 31 Aug 2022 16:13:47 +0200 Subject: [PATCH] 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. --- website/content/api-docs/acl/index.mdx | 15 + .../{acl-policies.mdx => acl/policies.mdx} | 0 website/content/api-docs/acl/roles.mdx | 340 ++++++++++++++++++ .../{acl-tokens.mdx => acl/tokens.mdx} | 27 +- website/content/docs/commands/acl/index.mdx | 30 +- .../{policy-apply.mdx => policy/apply.mdx} | 0 .../{policy-delete.mdx => policy/delete.mdx} | 0 .../acl/{policy-info.mdx => policy/info.mdx} | 0 .../acl/{policy-list.mdx => policy/list.mdx} | 0 .../content/docs/commands/acl/role/create.mdx | 53 +++ .../content/docs/commands/acl/role/delete.mdx | 30 ++ .../content/docs/commands/acl/role/info.mdx | 58 +++ .../content/docs/commands/acl/role/list.mdx | 35 ++ .../content/docs/commands/acl/role/update.mdx | 56 +++ .../docs/commands/acl/token-create.mdx | 52 --- .../docs/commands/acl/token/create.mdx | 86 +++++ .../{token-delete.mdx => token/delete.mdx} | 0 .../acl/{token-info.mdx => token/info.mdx} | 20 +- .../acl/{token-list.mdx => token/list.mdx} | 6 +- .../acl/{token-self.mdx => token/self.mdx} | 14 +- .../{token-update.mdx => token/update.mdx} | 21 +- website/content/docs/configuration/acl.mdx | 12 +- website/content/docs/configuration/server.mdx | 4 + website/data/api-docs-nav-data.json | 25 +- website/data/docs-nav-data.json | 103 ++++-- 25 files changed, 851 insertions(+), 136 deletions(-) create mode 100644 website/content/api-docs/acl/index.mdx rename website/content/api-docs/{acl-policies.mdx => acl/policies.mdx} (100%) create mode 100644 website/content/api-docs/acl/roles.mdx rename website/content/api-docs/{acl-tokens.mdx => acl/tokens.mdx} (94%) rename website/content/docs/commands/acl/{policy-apply.mdx => policy/apply.mdx} (100%) rename website/content/docs/commands/acl/{policy-delete.mdx => policy/delete.mdx} (100%) rename website/content/docs/commands/acl/{policy-info.mdx => policy/info.mdx} (100%) rename website/content/docs/commands/acl/{policy-list.mdx => policy/list.mdx} (100%) create mode 100644 website/content/docs/commands/acl/role/create.mdx create mode 100644 website/content/docs/commands/acl/role/delete.mdx create mode 100644 website/content/docs/commands/acl/role/info.mdx create mode 100644 website/content/docs/commands/acl/role/list.mdx create mode 100644 website/content/docs/commands/acl/role/update.mdx delete mode 100644 website/content/docs/commands/acl/token-create.mdx create mode 100644 website/content/docs/commands/acl/token/create.mdx rename website/content/docs/commands/acl/{token-delete.mdx => token/delete.mdx} (100%) rename website/content/docs/commands/acl/{token-info.mdx => token/info.mdx} (60%) rename website/content/docs/commands/acl/{token-list.mdx => token/list.mdx} (68%) rename website/content/docs/commands/acl/{token-self.mdx => token/self.mdx} (72%) rename website/content/docs/commands/acl/{token-update.mdx => token/update.mdx} (66%) diff --git a/website/content/api-docs/acl/index.mdx b/website/content/api-docs/acl/index.mdx new file mode 100644 index 000000000..b9b8af4b6 --- /dev/null +++ b/website/content/api-docs/acl/index.mdx @@ -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. diff --git a/website/content/api-docs/acl-policies.mdx b/website/content/api-docs/acl/policies.mdx similarity index 100% rename from website/content/api-docs/acl-policies.mdx rename to website/content/api-docs/acl/policies.mdx diff --git a/website/content/api-docs/acl/roles.mdx b/website/content/api-docs/acl/roles.mdx new file mode 100644 index 000000000..25fa92f24 --- /dev/null +++ b/website/content/api-docs/acl/roles.mdx @@ -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: )` - 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: )` - A free form human-readable description + of the ACL Role. It must not exceed 256 characters. + +- `Policies` `(array)` 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: " \ + --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: )` - Specifies the ACL Role, by ID, that is being + updated. Must match payload body and request path. + +- `Name` `(string: )` - 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: )` - A free form human-readable description + of the ACL Role. It must not exceed 256 characters. + +- `Policies` `(array)` 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: " \ + --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.
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: " \ + https://localhost:4646/v1/acl/roles +``` + +```shell-session +$ curl \ + --header "X-Nomad-Token: " \ + 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: )` - Specifies the ID of the ACL Role. This is + specified as part of the path. + +### Sample Request + +```shell-session +$ curl \ + --header "X-Nomad-Token: " \ + 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: )` - Specifies the Name of the ACL Role. This is + specified as part of the path. + +### Sample Request + +```shell-session +$ curl \ + --header "X-Nomad-Token: " \ + 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: )` - 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: " \ + https://localhost:4646/v1/acl/role/77c50812-fcdd-701b-9f1a-6cf55387b09d +``` diff --git a/website/content/api-docs/acl-tokens.mdx b/website/content/api-docs/acl/tokens.mdx similarity index 94% rename from website/content/api-docs/acl-tokens.mdx rename to website/content/api-docs/acl/tokens.mdx index 095fd66ca..6e08f4844 100644 --- a/website/content/api-docs/acl-tokens.mdx +++ b/website/content/api-docs/acl/tokens.mdx @@ -11,9 +11,9 @@ For more details about ACLs, please see the [ACL Guide](https://learn.hashicorp. ## Bootstrap Token -This endpoint is used to bootstrap the ACL system and provide the initial management token. -An operator created token can be provided in the body of the request to bootstrap the cluster -if required. If no header is provided the cluster will return a generated management token. +This endpoint is used to bootstrap the ACL system and provide the initial management token. +An operator created token can be provided in the body of the request to bootstrap the cluster +if required. If no header is provided the cluster will return a generated management token. The provided token should be presented in a UUID format. This request is always forwarded to the authoritative region. It can only be invoked once until a [bootstrap reset](https://learn.hashicorp.com/tutorials/nomad/access-control-bootstrap#re-bootstrap-acl-system) is performed. @@ -182,13 +182,26 @@ The table below shows this endpoint's support for ### Parameters -- `Name` `(string: )` - Specifies the human readable name of the token. +- `Name` `(string: )` - Specifies the human-readable name of the token. -- `Type` `(string: )` - Specifies the type of token. Must be either `client` or `management`. +- `Type` `(string: )` - Specifies the type of token. Must be either + `client` or `management`. -- `Policies` `(array: )` - Must be null or blank for `management` type tokens, otherwise must specify at least one policy for `client` type tokens. +- `Policies` `(array: )` - Must be null or blank for + `management` type tokens, otherwise must specify at least one policy for + `client` type tokens. -- `Global` `(bool: )` - If true, indicates this token should be replicated globally to all regions. Otherwise, this token is created local to the target region. +- `Global` `(bool: )` - If true, indicates this token should be + replicated globally to all regions. Otherwise, this token is created local to + the target region. + +- `ExpirationTime` `(time: "")` - If set, this represents the point after which + a token should be considered revoked and is eligible for destruction. The + default unset value represents NO expiration. + +- `ExpirationTTL` `(duration: 0s)` - This is a convenience field and if set will + initialize the `ExpirationTime` field to a value of `CreateTime` + + `ExpirationTTL`. ### Sample Payload diff --git a/website/content/docs/commands/acl/index.mdx b/website/content/docs/commands/acl/index.mdx index a10acdb42..d08a4301c 100644 --- a/website/content/docs/commands/acl/index.mdx +++ b/website/content/docs/commands/acl/index.mdx @@ -23,6 +23,11 @@ subcommands are available: - [`acl policy delete`][policydelete] - Delete an existing ACL policies - [`acl policy info`][policyinfo] - Fetch information on an existing ACL policy - [`acl policy list`][policylist] - List available ACL policies +- [`acl role create`][rolecreate] - Create a new ACL role +- [`acl role delete`][roledelete] - Delete an existing ACL role +- [`acl role info`][roleinfo] - Get info on an existing ACL role +- [`acl role list`][rolelist] - List available ACL roles +- [`acl role update`][roleupdate] - Update existing ACL role - [`acl token create`][tokencreate] - Create new ACL token - [`acl token delete`][tokendelete] - Delete an existing ACL token - [`acl token info`][tokeninfo] - Get info on an existing ACL token @@ -31,14 +36,19 @@ subcommands are available: - [`acl token update`][tokenupdate] - Update existing ACL token [bootstrap]: /docs/commands/acl/bootstrap -[policyapply]: /docs/commands/acl/policy-apply -[policydelete]: /docs/commands/acl/policy-delete -[policyinfo]: /docs/commands/acl/policy-info -[policylist]: /docs/commands/acl/policy-list -[tokencreate]: /docs/commands/acl/token-create -[tokenupdate]: /docs/commands/acl/token-update -[tokendelete]: /docs/commands/acl/token-delete -[tokeninfo]: /docs/commands/acl/token-info -[tokenlist]: /docs/commands/acl/token-list -[tokenself]: /docs/commands/acl/token-self +[policyapply]: /docs/commands/acl/policy/apply +[policydelete]: /docs/commands/acl/policy/delete +[policyinfo]: /docs/commands/acl/policy/info +[policylist]: /docs/commands/acl/policy/list +[tokencreate]: /docs/commands/acl/token/create +[tokenupdate]: /docs/commands/acl/token/update +[tokendelete]: /docs/commands/acl/token/delete +[tokeninfo]: /docs/commands/acl/token/info +[tokenlist]: /docs/commands/acl/token/list +[tokenself]: /docs/commands/acl/token/self +[rolecreate]: /docs/commands/acl/role/create +[roleupdate]: /docs/commands/acl/role/update +[roledelete]: /docs/commands/acl/role/delete +[roleinfo]: /docs/commands/acl/role/info +[rolelist]: /docs/commands/acl/role/list [secure-guide]: https://learn.hashicorp.com/collections/nomad/access-control diff --git a/website/content/docs/commands/acl/policy-apply.mdx b/website/content/docs/commands/acl/policy/apply.mdx similarity index 100% rename from website/content/docs/commands/acl/policy-apply.mdx rename to website/content/docs/commands/acl/policy/apply.mdx diff --git a/website/content/docs/commands/acl/policy-delete.mdx b/website/content/docs/commands/acl/policy/delete.mdx similarity index 100% rename from website/content/docs/commands/acl/policy-delete.mdx rename to website/content/docs/commands/acl/policy/delete.mdx diff --git a/website/content/docs/commands/acl/policy-info.mdx b/website/content/docs/commands/acl/policy/info.mdx similarity index 100% rename from website/content/docs/commands/acl/policy-info.mdx rename to website/content/docs/commands/acl/policy/info.mdx diff --git a/website/content/docs/commands/acl/policy-list.mdx b/website/content/docs/commands/acl/policy/list.mdx similarity index 100% rename from website/content/docs/commands/acl/policy-list.mdx rename to website/content/docs/commands/acl/policy/list.mdx diff --git a/website/content/docs/commands/acl/role/create.mdx b/website/content/docs/commands/acl/role/create.mdx new file mode 100644 index 000000000..64d72c4b0 --- /dev/null +++ b/website/content/docs/commands/acl/role/create.mdx @@ -0,0 +1,53 @@ +--- +layout: docs +page_title: 'Commands: acl role create' +description: The role create command is used to create new ACL Roles. +--- + +# Command: acl role create + +The `acl role create` command is used to create new ACL Roles. + +## Usage + +```plaintext +nomad acl role create [options] +``` + +The `acl role create` command requires the correct setting of the create options +via flags detailed below. + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Create Options + +- `-name`: Sets the human-readable name for the ACL Role. It is required and + can contain alphanumeric characters, dashes, and underscores. This name must + be unique and must not exceed 128 characters. + +- `-description`: A free form text description of the role that must not exceed + 256 characters. + +- `-policy`: Specifies a policy to associate with the role identified by their + name. This flag can be specified multiple times and must be specified at + least once. + +- `-json`: Output the ACL role in a JSON format. + +- `-t`: Format and display the ACL role using a Go template. + +## Examples + +Create a new ACL Role: + +```shell-session +$ nomad acl role create -name="example-acl-role" -policy=example-acl-policy +ID = a53b0095-c28a-6181-0586-807b82e665e4 +Name = example-acl-role +Description = +Policies = example-acl-policy +Create Index = 71 +Modify Index = 71 +``` diff --git a/website/content/docs/commands/acl/role/delete.mdx b/website/content/docs/commands/acl/role/delete.mdx new file mode 100644 index 000000000..f4e4a93b9 --- /dev/null +++ b/website/content/docs/commands/acl/role/delete.mdx @@ -0,0 +1,30 @@ +--- +layout: docs +page_title: 'Commands: acl role delete' +description: The role delete command is used to delete existing ACL Roles. +--- + +# Command: acl role delete + +The `acl role delete` command is used to delete existing ACL Roles. + +## Usage + +```plaintext +nomad acl role delete [options] +``` + +The `acl role delete` command requires an existing role's ID. + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Examples + +Delete an existing ACL Role: + +```shell-session +$ nomad acl role delete a53b0095-c28a-6181-0586-807b82e665e4 +ACL role a53b0095-c28a-6181-0586-807b82e665e4 successfully deleted +``` diff --git a/website/content/docs/commands/acl/role/info.mdx b/website/content/docs/commands/acl/role/info.mdx new file mode 100644 index 000000000..7a2f40a8b --- /dev/null +++ b/website/content/docs/commands/acl/role/info.mdx @@ -0,0 +1,58 @@ +--- +layout: docs +page_title: 'Commands: acl role info' +description: | + The role info command is used to fetch information about an existing ACL + Role. +--- + +# Command: acl role info + +The `acl role info` command is used to fetch information about an existing ACL Role. + +## Usage + +```plaintext +nomad acl role info [options] or +``` + +The `acl role info` command requires an existing role's ID or name. + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Info Options + +- `-by-name`: Look up the ACL role using its name as the identifier. The + command defaults to expecting the ACL ID as the argument. + +- `-json`: Output the ACL role in a JSON format. + +- `-t`: Format and display the ACL role using a Go template. + +## Examples + +Fetch information about an existing ACL Role using its ID: + +```shell-session +$ nomad acl role info a53b0095-c28a-6181-0586-807b82e665e4 +ID = a53b0095-c28a-6181-0586-807b82e665e4 +Name = example-acl-role +Description = +Policies = general-write +Create Index = 71 +Modify Index = 71 +``` + +Fetch information about an existing ACL Role using its name: + +```shell-session +$ nomad acl role info -by-name example-acl-role +ID = a53b0095-c28a-6181-0586-807b82e665e4 +Name = example-acl-role +Description = +Policies = general-write +Create Index = 71 +Modify Index = 71 +``` diff --git a/website/content/docs/commands/acl/role/list.mdx b/website/content/docs/commands/acl/role/list.mdx new file mode 100644 index 000000000..6f36f8d06 --- /dev/null +++ b/website/content/docs/commands/acl/role/list.mdx @@ -0,0 +1,35 @@ +--- +layout: docs +page_title: 'Commands: acl role list' +description: The role list command is used to list existing ACL Roles. +--- + +# Command: acl role list + +The `acl role list` command is used to list existing ACL Roles. + +## Usage + +```plaintext +nomad acl role list [options] +``` + +## General Options + +@include 'general_options_no_namespace.mdx' + +## List Options + +- `-json` : Output the ACL roles in a JSON format. + +- `-t` : Format and display the ACL roles using a Go template. + +## Examples + +List all ACL Roles: + +```shell-session +$ nomad acl role list +ID Name Description Policies +a53b0095-c28a-6181-0586-807b82e665e4 example-acl-role general-write +``` diff --git a/website/content/docs/commands/acl/role/update.mdx b/website/content/docs/commands/acl/role/update.mdx new file mode 100644 index 000000000..cc808f838 --- /dev/null +++ b/website/content/docs/commands/acl/role/update.mdx @@ -0,0 +1,56 @@ +--- +layout: docs +page_title: 'Commands: acl role update' +description: The role update command is used to update existing ACL Roles. +--- + +# Command: acl role update + +The `acl role update` command is used to update existing ACL Roles. + +## Usage + +```plaintext +nomad acl role update [options] +``` + +The `acl role update` command requires an existing role's ID. + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Update Options + +- `-name`: Sets the human-readable name for the ACL Role. It is required and + can contain alphanumeric characters, dashes, and underscores. This name must + be unique and must not exceed 128 characters. + +- `-description`: A free form text description of the role that must not exceed + 256 characters. + +- `-policy`: Specifies a policy to associate with the role identified by their + name. This flag can be specified multiple times and must be specified at + least once. + +- `-no-merge`: Do not merge the current role information with what is provided + to the command. Instead, overwrite all fields with the exception of the role + ID which is immutable. + +- `-json`: Output the ACL role in a JSON format. + +- `-t`: Format and display the ACL role using a Go template. + +## Examples + +Update an existing ACL token: + +```shell-session +$ nomad acl role update -name="example-acl-role-updated" a53b0095-c28a-6181-0586-807b82e665e4 +ID = a53b0095-c28a-6181-0586-807b82e665e4 +Name = example-acl-role-updated +Description = +Policies = general-write +Create Index = 71 +Modify Index = 80 +``` diff --git a/website/content/docs/commands/acl/token-create.mdx b/website/content/docs/commands/acl/token-create.mdx deleted file mode 100644 index 13f30637b..000000000 --- a/website/content/docs/commands/acl/token-create.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: docs -page_title: 'Commands: acl token create' -description: | - The token create command is used to create new ACL tokens. ---- - -# Command: acl token create - -The `acl token create` command is used to create new ACL tokens. - -## Usage - -```plaintext -nomad acl token create [options] -``` - -The `acl token create` command requires no arguments. - -## General Options - -@include 'general_options_no_namespace.mdx' - -## Create Options - -- `-name`: Sets the human readable name for the ACL token. - -- `-type`: Sets the type of token. Must be one of "client" (default), or - "management". - -- `-global`: Toggles the global mode of the token. Global tokens are replicated - to all regions. Defaults false. - -- `-policy`: Specifies a policy to associate with the token. Can be specified - multiple times, but only with client type tokens. - -## Examples - -Create a new ACL token: - -```shell-session -$ nomad acl token create -name="my token" -policy=foo -policy=bar -Accessor ID = d532c40a-30f1-695c-19e5-c35b882b0efd -Secret ID = 85310d07-9afa-ef53-0933-0c043cd673c7 -Name = my token -Type = client -Global = false -Policies = [foo bar] -Create Time = 2017-09-15 05:04:41.814954949 +0000 UTC -Create Index = 8 -Modify Index = 8 -``` diff --git a/website/content/docs/commands/acl/token/create.mdx b/website/content/docs/commands/acl/token/create.mdx new file mode 100644 index 000000000..aeac4ee87 --- /dev/null +++ b/website/content/docs/commands/acl/token/create.mdx @@ -0,0 +1,86 @@ +--- +layout: docs +page_title: 'Commands: acl token create' +description: | + The token create command is used to create new ACL tokens. +--- + +# Command: acl token create + +The `acl token create` command is used to create new ACL tokens. + +## Usage + +```plaintext +nomad acl token create [options] +``` + +The `acl token create` command requires no arguments. + +## General Options + +@include 'general_options_no_namespace.mdx' + +## Create Options + +- `-name`: Sets the human readable name for the ACL token. + +- `-type`: Sets the type of token. Must be one of "client" (default), or + "management". + +- `-global`: Toggles the global mode of the token. Global tokens are replicated + to all regions. Defaults false. + +- `-policy`: Specifies a policy to associate with the token. Can be specified + multiple times, but only with client type tokens. + +- `-role-id`: ID of a role to use for this token. May be specified multiple + times. + +- `-role-name`: Name of a role to use for this token. May be specified multiple + times. + +- `-ttl`: Specifies the time-to-live of the created ACL token. This takes the + form of a time duration such as "5m" and "1h". By default, tokens will be + created without a TTL and therefore never expire. + +## Examples + +Create a new ACL token linked to an ACL Policy and Role: + +```shell-session +$ nomad acl token create -name="example-acl-token" -policy=example-acl-policy -role-name=example-acl-role +Accessor ID = ef851ca0-b331-da5d-bbeb-7ede8f7c9151 +Secret ID = 11d5348a-8768-5baa-6185-c154980e1488 +Name = example-acl-token +Type = client +Global = false +Create Time = 2022-08-23 12:16:09.680699039 +0000 UTC +Expiry Time = +Create Index = 140 +Modify Index = 140 +Policies = [example-acl-policy] + +Roles +ID Name +2fe0c403-4502-e99d-4c79-a2821355e66d example-acl-policy +``` + +Create a new ACL token with an expiry: + +```shell-session +$ nomad acl token create -name="example-acl-token" -policy=example-acl-policy -ttl=8h +Accessor ID = 1b60edc8-e4ed-08ef-208d-ecc18a90ccc3 +Secret ID = e4c7c80e-870b-c6a6-43d2-dbfa90130c06 +Name = example-acl-token +Type = client +Global = false +Create Time = 2022-08-23 12:17:35.45067293 +0000 UTC +Expiry Time = 2022-08-23 20:17:35.45067293 +0000 UTC +Create Index = 142 +Modify Index = 142 +Policies = [example-acl-policy] + +Roles + +``` diff --git a/website/content/docs/commands/acl/token-delete.mdx b/website/content/docs/commands/acl/token/delete.mdx similarity index 100% rename from website/content/docs/commands/acl/token-delete.mdx rename to website/content/docs/commands/acl/token/delete.mdx diff --git a/website/content/docs/commands/acl/token-info.mdx b/website/content/docs/commands/acl/token/info.mdx similarity index 60% rename from website/content/docs/commands/acl/token-info.mdx rename to website/content/docs/commands/acl/token/info.mdx index 43b28f8d5..33e442126 100644 --- a/website/content/docs/commands/acl/token-info.mdx +++ b/website/content/docs/commands/acl/token/info.mdx @@ -27,14 +27,18 @@ The `acl token info` command requires an existing token's AccessorID. Fetch information about an existing ACL token: ```shell-session -$ nomad acl token info d532c40a-30f1-695c-19e5-c35b882b0efd -Accessor ID = d532c40a-30f1-695c-19e5-c35b882b0efd -Secret ID = 85310d07-9afa-ef53-0933-0c043cd673c7 -Name = my token +$ nomad acl token info 1b60edc8-e4ed-08ef-208d-ecc18a90ccc3 +Accessor ID = 1b60edc8-e4ed-08ef-208d-ecc18a90ccc3 +Secret ID = e4c7c80e-870b-c6a6-43d2-dbfa90130c06 +Name = example-acl-token Type = client Global = false -Policies = [foo bar] -Create Time = 2017-09-15 05:04:41.814954949 +0000 UTC -Create Index = 8 -Modify Index = 8 +Create Time = 2022-08-23 12:17:35.45067293 +0000 UTC +Expiry Time = 2022-08-23 20:17:35.45067293 +0000 UTC +Create Index = 142 +Modify Index = 142 +Policies = [example-acl-policy] + +Roles + ``` diff --git a/website/content/docs/commands/acl/token-list.mdx b/website/content/docs/commands/acl/token/list.mdx similarity index 68% rename from website/content/docs/commands/acl/token-list.mdx rename to website/content/docs/commands/acl/token/list.mdx index c99073608..fb8fc94ac 100644 --- a/website/content/docs/commands/acl/token-list.mdx +++ b/website/content/docs/commands/acl/token/list.mdx @@ -30,7 +30,7 @@ List all ACL tokens: ```shell-session $ nomad acl token list -Name Type Global Accessor ID -Bootstrap Token management true 32b61154-47f1-3694-1430-a5544bafcd3e - client false fcf2bf84-a257-8f39-9d16-a954ed25b5be +Name Type Global Accessor ID Expired +Bootstrap Token management true 9c2d1b3a-cbc3-d9a0-3df9-5a382545a819 false +example-acl-token client false ef851ca0-b331-da5d-bbeb-7ede8f7c9151 false ``` diff --git a/website/content/docs/commands/acl/token-self.mdx b/website/content/docs/commands/acl/token/self.mdx similarity index 72% rename from website/content/docs/commands/acl/token-self.mdx rename to website/content/docs/commands/acl/token/self.mdx index 0611a736d..b58a7193b 100644 --- a/website/content/docs/commands/acl/token-self.mdx +++ b/website/content/docs/commands/acl/token/self.mdx @@ -29,13 +29,15 @@ Fetch information about an existing ACL token: $ export NOMAD_TOKEN=85310d07-9afa-ef53-0933-0c043cd673c7 $ nomad acl token self -Accessor ID = d532c40a-30f1-695c-19e5-c35b882b0efd +Accessor ID = 9c2d1b3a-cbc3-d9a0-3df9-5a382545a819 Secret ID = 85310d07-9afa-ef53-0933-0c043cd673c7 -Name = my token -Type = client -Global = false -Policies = [foo bar] -Create Time = 2017-09-15 05:04:41.814954949 +0000 UTC +Name = Bootstrap Token +Type = management +Global = true +Create Time = 2022-08-23 10:35:32.371025521 +0000 UTC +Expiry Time = Create Index = 8 Modify Index = 8 +Policies = n/a +Roles = n/a ``` diff --git a/website/content/docs/commands/acl/token-update.mdx b/website/content/docs/commands/acl/token/update.mdx similarity index 66% rename from website/content/docs/commands/acl/token-update.mdx rename to website/content/docs/commands/acl/token/update.mdx index 4988a4b77..e74a72f61 100644 --- a/website/content/docs/commands/acl/token-update.mdx +++ b/website/content/docs/commands/acl/token/update.mdx @@ -39,14 +39,19 @@ The `acl token update` command requires an existing token's accessor ID. Update an existing ACL token: ```shell-session -$ nomad acl token update -name="my updated token" -policy=foo -policy=bar d532c40a-30f1-695c-19e5-c35b882b0efd -Accessor ID = d532c40a-30f1-695c-19e5-c35b882b0efd -Secret ID = 85310d07-9afa-ef53-0933-0c043cd673c7 -Name = my updated token +$ nomad acl token update -name="example-acl-token-updated" ef851ca0-b331-da5d-bbeb-7ede8f7c9151 +Accessor ID = ef851ca0-b331-da5d-bbeb-7ede8f7c9151 +Secret ID = 11d5348a-8768-5baa-6185-c154980e1488 +Name = example-acl-token-updated Type = client Global = false -Policies = [foo bar] -Create Time = 2017-09-15 05:04:41.814954949 +0000 UTC -Create Index = 8 -Modify Index = 8 +Create Time = 2022-08-23 12:16:09.680699039 +0000 UTC +Expiry Time = +Create Index = 140 +Modify Index = 151 +Policies = [example-acl-policy] + +Roles +ID Name +2fe0c403-4502-e99d-4c79-a2821355e66d example-acl-role-updated ``` diff --git a/website/content/docs/configuration/acl.mdx b/website/content/docs/configuration/acl.mdx index 90e733ee0..9cfd8abeb 100644 --- a/website/content/docs/configuration/acl.mdx +++ b/website/content/docs/configuration/acl.mdx @@ -16,8 +16,8 @@ Nomad with Access Control guide][secure-guide]. ```hcl acl { - enabled = true - token_ttl = "30s" + enabled = true + token_ttl = "30s" policy_ttl = "60s" } ``` @@ -46,5 +46,13 @@ acl { to use for replicating policies and tokens. This is used by servers in non-authoritative region to mirror the policies and tokens into the local region from [authoritative_region][authoritative-region]. +- `token_min_expiration_ttl` `(string: "1m")` - Specifies the lowest acceptable + TTL value for an ACL token when setting expiration. This is used by the Nomad + servers to validate ACL tokens. + +- `token_max_expiration_ttl` `(string: "24h")` - Specifies the highest acceptable + TTL value for an ACL token when setting expiration. This is used by the Nomad + servers to validate ACL tokens. + [secure-guide]: https://learn.hashicorp.com/collections/nomad/access-control [authoritative-region]: /docs/configuration/server#authoritative_region diff --git a/website/content/docs/configuration/server.mdx b/website/content/docs/configuration/server.mdx index f433efa20..75f768b08 100644 --- a/website/content/docs/configuration/server.mdx +++ b/website/content/docs/configuration/server.mdx @@ -107,6 +107,10 @@ server { CSI plugin before it is eligible for garbage collection if not in use. This is specified using a label suffix like "30s" or "1h". +- `acl_token_gc_threshold` `(string: "1h")` - Specifies the minimum age of an + expired ACL token before it is eligible for garbage collection. This is + specified using a label suffix like "30s" or "1h". + - `default_scheduler_config` ([scheduler_configuration][update-scheduler-config]: nil) - Specifies the initial default scheduler config when bootstrapping cluster. The parameter is ignored once the cluster is bootstrapped or diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 95efba8cc..7dec54398 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -18,12 +18,25 @@ "divider": true }, { - "title": "ACL Policies", - "path": "acl-policies" - }, - { - "title": "ACL Tokens", - "path": "acl-tokens" + "title": "ACL", + "routes": [ + { + "title": "Overview", + "path": "acl" + }, + { + "title": "Policies", + "path": "acl/policies" + }, + { + "title": "Roles", + "path": "acl/roles" + }, + { + "title": "Tokens", + "path": "acl/tokens" + } + ] }, { "title": "Agent", diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index cd1bd9d8a..b9628c4d4 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -237,44 +237,79 @@ "path": "commands/acl/bootstrap" }, { - "title": "policy apply", - "path": "commands/acl/policy-apply" + "title": "policy", + "routes": [ + { + "title": "apply", + "path": "commands/acl/policy/apply" + }, + { + "title": "delete", + "path": "commands/acl/policy/delete" + }, + { + "title": "info", + "path": "commands/acl/policy/info" + }, + { + "title": "list", + "path": "commands/acl/policy/list" + } + ] }, { - "title": "policy delete", - "path": "commands/acl/policy-delete" + "title": "role", + "routes": [ + { + "title": "create", + "path": "commands/acl/role/create" + }, + { + "title": "delete", + "path": "commands/acl/role/delete" + }, + { + "title": "info", + "path": "commands/acl/role/info" + }, + { + "title": "list", + "path": "commands/acl/role/list" + }, + { + "title": "update", + "path": "commands/acl/role/update" + } + ] }, { - "title": "policy info", - "path": "commands/acl/policy-info" - }, - { - "title": "policy list", - "path": "commands/acl/policy-list" - }, - { - "title": "token create", - "path": "commands/acl/token-create" - }, - { - "title": "token delete", - "path": "commands/acl/token-delete" - }, - { - "title": "token info", - "path": "commands/acl/token-info" - }, - { - "title": "token list", - "path": "commands/acl/token-list" - }, - { - "title": "token self", - "path": "commands/acl/token-self" - }, - { - "title": "token update", - "path": "commands/acl/token-update" + "title": "token", + "routes": [ + { + "title": "create", + "path": "commands/acl/token/create" + }, + { + "title": "delete", + "path": "commands/acl/token/delete" + }, + { + "title": "info", + "path": "commands/acl/token/info" + }, + { + "title": "list", + "path": "commands/acl/token/list" + }, + { + "title": "self", + "path": "commands/acl/token/self" + }, + { + "title": "update", + "path": "commands/acl/token/update" + } + ] } ] },