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.
This commit is contained in:
James Rasell 2022-08-31 16:13:47 +02:00 committed by GitHub
parent 5f3665230b
commit 986355bcd9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
25 changed files with 851 additions and 136 deletions

View file

@ -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.

View file

@ -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
```

View file

@ -11,9 +11,9 @@ For more details about ACLs, please see the [ACL Guide](https://learn.hashicorp.
## Bootstrap Token ## Bootstrap Token
This endpoint is used to bootstrap the ACL system and provide the initial 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 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. 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. 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 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. 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 ### Parameters
- `Name` `(string: <optional>)` - Specifies the human readable name of the token. - `Name` `(string: <optional>)` - Specifies the human-readable name of the token.
- `Type` `(string: <required>)` - Specifies the type of token. Must be either `client` or `management`. - `Type` `(string: <required>)` - Specifies the type of token. Must be either
`client` or `management`.
- `Policies` `(array<string>: <required>)` - Must be null or blank for `management` type tokens, otherwise must specify at least one policy for `client` type tokens. - `Policies` `(array<string>: <required>)` - Must be null or blank for
`management` type tokens, otherwise must specify at least one policy for
`client` type tokens.
- `Global` `(bool: <optional>)` - If true, indicates this token should be replicated globally to all regions. Otherwise, this token is created local to the target region. - `Global` `(bool: <optional>)` - 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 ### Sample Payload

View file

@ -23,6 +23,11 @@ subcommands are available:
- [`acl policy delete`][policydelete] - Delete an existing ACL policies - [`acl policy delete`][policydelete] - Delete an existing ACL policies
- [`acl policy info`][policyinfo] - Fetch information on an existing ACL policy - [`acl policy info`][policyinfo] - Fetch information on an existing ACL policy
- [`acl policy list`][policylist] - List available ACL policies - [`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 create`][tokencreate] - Create new ACL token
- [`acl token delete`][tokendelete] - Delete an existing ACL token - [`acl token delete`][tokendelete] - Delete an existing ACL token
- [`acl token info`][tokeninfo] - Get info on 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 - [`acl token update`][tokenupdate] - Update existing ACL token
[bootstrap]: /docs/commands/acl/bootstrap [bootstrap]: /docs/commands/acl/bootstrap
[policyapply]: /docs/commands/acl/policy-apply [policyapply]: /docs/commands/acl/policy/apply
[policydelete]: /docs/commands/acl/policy-delete [policydelete]: /docs/commands/acl/policy/delete
[policyinfo]: /docs/commands/acl/policy-info [policyinfo]: /docs/commands/acl/policy/info
[policylist]: /docs/commands/acl/policy-list [policylist]: /docs/commands/acl/policy/list
[tokencreate]: /docs/commands/acl/token-create [tokencreate]: /docs/commands/acl/token/create
[tokenupdate]: /docs/commands/acl/token-update [tokenupdate]: /docs/commands/acl/token/update
[tokendelete]: /docs/commands/acl/token-delete [tokendelete]: /docs/commands/acl/token/delete
[tokeninfo]: /docs/commands/acl/token-info [tokeninfo]: /docs/commands/acl/token/info
[tokenlist]: /docs/commands/acl/token-list [tokenlist]: /docs/commands/acl/token/list
[tokenself]: /docs/commands/acl/token-self [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 [secure-guide]: https://learn.hashicorp.com/collections/nomad/access-control

View file

@ -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 = <none>
Policies = example-acl-policy
Create Index = 71
Modify Index = 71
```

View file

@ -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] <role_id>
```
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
```

View file

@ -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] <role_id> or <role_name>
```
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 = <none>
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 = <none>
Policies = general-write
Create Index = 71
Modify Index = 71
```

View file

@ -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 <none> general-write
```

View file

@ -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] <role_id>
```
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 = <none>
Policies = general-write
Create Index = 71
Modify Index = 80
```

View file

@ -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
```

View file

@ -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 = <none>
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
<none>
```

View file

@ -27,14 +27,18 @@ The `acl token info` command requires an existing token's AccessorID.
Fetch information about an existing ACL token: Fetch information about an existing ACL token:
```shell-session ```shell-session
$ nomad acl token info d532c40a-30f1-695c-19e5-c35b882b0efd $ nomad acl token info 1b60edc8-e4ed-08ef-208d-ecc18a90ccc3
Accessor ID = d532c40a-30f1-695c-19e5-c35b882b0efd Accessor ID = 1b60edc8-e4ed-08ef-208d-ecc18a90ccc3
Secret ID = 85310d07-9afa-ef53-0933-0c043cd673c7 Secret ID = e4c7c80e-870b-c6a6-43d2-dbfa90130c06
Name = my token Name = example-acl-token
Type = client Type = client
Global = false Global = false
Policies = [foo bar] Create Time = 2022-08-23 12:17:35.45067293 +0000 UTC
Create Time = 2017-09-15 05:04:41.814954949 +0000 UTC Expiry Time = 2022-08-23 20:17:35.45067293 +0000 UTC
Create Index = 8 Create Index = 142
Modify Index = 8 Modify Index = 142
Policies = [example-acl-policy]
Roles
<none>
``` ```

View file

@ -30,7 +30,7 @@ List all ACL tokens:
```shell-session ```shell-session
$ nomad acl token list $ nomad acl token list
Name Type Global Accessor ID Name Type Global Accessor ID Expired
Bootstrap Token management true 32b61154-47f1-3694-1430-a5544bafcd3e Bootstrap Token management true 9c2d1b3a-cbc3-d9a0-3df9-5a382545a819 false
<none> client false fcf2bf84-a257-8f39-9d16-a954ed25b5be example-acl-token client false ef851ca0-b331-da5d-bbeb-7ede8f7c9151 false
``` ```

View file

@ -29,13 +29,15 @@ Fetch information about an existing ACL token:
$ export NOMAD_TOKEN=85310d07-9afa-ef53-0933-0c043cd673c7 $ export NOMAD_TOKEN=85310d07-9afa-ef53-0933-0c043cd673c7
$ nomad acl token self $ 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 Secret ID = 85310d07-9afa-ef53-0933-0c043cd673c7
Name = my token Name = Bootstrap Token
Type = client Type = management
Global = false Global = true
Policies = [foo bar] Create Time = 2022-08-23 10:35:32.371025521 +0000 UTC
Create Time = 2017-09-15 05:04:41.814954949 +0000 UTC Expiry Time = <none>
Create Index = 8 Create Index = 8
Modify Index = 8 Modify Index = 8
Policies = n/a
Roles = n/a
``` ```

View file

@ -39,14 +39,19 @@ The `acl token update` command requires an existing token's accessor ID.
Update an existing ACL token: Update an existing ACL token:
```shell-session ```shell-session
$ nomad acl token update -name="my updated token" -policy=foo -policy=bar d532c40a-30f1-695c-19e5-c35b882b0efd $ nomad acl token update -name="example-acl-token-updated" ef851ca0-b331-da5d-bbeb-7ede8f7c9151
Accessor ID = d532c40a-30f1-695c-19e5-c35b882b0efd Accessor ID = ef851ca0-b331-da5d-bbeb-7ede8f7c9151
Secret ID = 85310d07-9afa-ef53-0933-0c043cd673c7 Secret ID = 11d5348a-8768-5baa-6185-c154980e1488
Name = my updated token Name = example-acl-token-updated
Type = client Type = client
Global = false Global = false
Policies = [foo bar] Create Time = 2022-08-23 12:16:09.680699039 +0000 UTC
Create Time = 2017-09-15 05:04:41.814954949 +0000 UTC Expiry Time = <never>
Create Index = 8 Create Index = 140
Modify Index = 8 Modify Index = 151
Policies = [example-acl-policy]
Roles
ID Name
2fe0c403-4502-e99d-4c79-a2821355e66d example-acl-role-updated
``` ```

View file

@ -16,8 +16,8 @@ Nomad with Access Control guide][secure-guide].
```hcl ```hcl
acl { acl {
enabled = true enabled = true
token_ttl = "30s" token_ttl = "30s"
policy_ttl = "60s" policy_ttl = "60s"
} }
``` ```
@ -46,5 +46,13 @@ acl {
to use for replicating policies and tokens. This is used by servers in non-authoritative 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]. 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 [secure-guide]: https://learn.hashicorp.com/collections/nomad/access-control
[authoritative-region]: /docs/configuration/server#authoritative_region [authoritative-region]: /docs/configuration/server#authoritative_region

View file

@ -107,6 +107,10 @@ server {
CSI plugin before it is eligible for garbage collection if not in use. CSI plugin before it is eligible for garbage collection if not in use.
This is specified using a label suffix like "30s" or "1h". 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` <code>([scheduler_configuration][update-scheduler-config]: - `default_scheduler_config` <code>([scheduler_configuration][update-scheduler-config]:
nil)</code> - Specifies the initial default scheduler config when nil)</code> - Specifies the initial default scheduler config when
bootstrapping cluster. The parameter is ignored once the cluster is bootstrapped or bootstrapping cluster. The parameter is ignored once the cluster is bootstrapped or

View file

@ -18,12 +18,25 @@
"divider": true "divider": true
}, },
{ {
"title": "ACL Policies", "title": "ACL",
"path": "acl-policies" "routes": [
}, {
{ "title": "Overview",
"title": "ACL Tokens", "path": "acl"
"path": "acl-tokens" },
{
"title": "Policies",
"path": "acl/policies"
},
{
"title": "Roles",
"path": "acl/roles"
},
{
"title": "Tokens",
"path": "acl/tokens"
}
]
}, },
{ {
"title": "Agent", "title": "Agent",

View file

@ -237,44 +237,79 @@
"path": "commands/acl/bootstrap" "path": "commands/acl/bootstrap"
}, },
{ {
"title": "policy apply", "title": "policy",
"path": "commands/acl/policy-apply" "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", "title": "role",
"path": "commands/acl/policy-delete" "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", "title": "token",
"path": "commands/acl/policy-info" "routes": [
}, {
{ "title": "create",
"title": "policy list", "path": "commands/acl/token/create"
"path": "commands/acl/policy-list" },
}, {
{ "title": "delete",
"title": "token create", "path": "commands/acl/token/delete"
"path": "commands/acl/token-create" },
}, {
{ "title": "info",
"title": "token delete", "path": "commands/acl/token/info"
"path": "commands/acl/token-delete" },
}, {
{ "title": "list",
"title": "token info", "path": "commands/acl/token/list"
"path": "commands/acl/token-info" },
}, {
{ "title": "self",
"title": "token list", "path": "commands/acl/token/self"
"path": "commands/acl/token-list" },
}, {
{ "title": "update",
"title": "token self", "path": "commands/acl/token/update"
"path": "commands/acl/token-self" }
}, ]
{
"title": "token update",
"path": "commands/acl/token-update"
} }
] ]
}, },