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" + } + ] } ] },