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
GitHub
parent
5f3665230b
commit
986355bcd9
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -182,13 +182,26 @@ The table below shows this endpoint's support for
|
|||
|
||||
### 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
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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>
|
||||
```
|
||||
|
|
@ -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
|
||||
<none>
|
||||
```
|
||||
|
|
@ -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
|
||||
<none> 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
|
||||
```
|
||||
|
|
@ -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 = <none>
|
||||
Create Index = 8
|
||||
Modify Index = 8
|
||||
Policies = n/a
|
||||
Roles = n/a
|
||||
```
|
||||
|
|
@ -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 = <never>
|
||||
Create Index = 140
|
||||
Modify Index = 151
|
||||
Policies = [example-acl-policy]
|
||||
|
||||
Roles
|
||||
ID Name
|
||||
2fe0c403-4502-e99d-4c79-a2821355e66d example-acl-role-updated
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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` <code>([scheduler_configuration][update-scheduler-config]:
|
||||
nil)</code> - Specifies the initial default scheduler config when
|
||||
bootstrapping cluster. The parameter is ignored once the cluster is bootstrapped or
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in New Issue