mirror of
https://github.com/kemko/nomad.git
synced 2026-01-06 02:15:43 +03:00
website: Document ACL APIs and configuration
This commit is contained in:
Armon Dadgar
161
website/source/api/acl-policies.html.md
Normal file
161
website/source/api/acl-policies.html.md
Normal file
@@ -0,0 +1,161 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: ACL Policies - HTTP API
|
||||
sidebar_current: api-acl-policies
|
||||
description: |-
|
||||
The /acl/policy endpoints are used to configure and manage ACL policies.
|
||||
---
|
||||
|
||||
# ACL Policies HTTP API
|
||||
|
||||
The `/acl/policies` and `/acl/policy/` endpoints are used to manage ACL policies.
|
||||
|
||||
## List Policies
|
||||
|
||||
This endpoint lists all ACL policies. This lists the policies that have been replicated
|
||||
to the region, and may lag behind the authoritative region.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/acl/policies` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries), [consistency modes](/api/index.html#consistency-modes) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ------------ |
|
||||
| `YES` | `all` | `management` |
|
||||
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/v1/acl/policies
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"Name": "foo",
|
||||
"Description": "",
|
||||
"CreateIndex": 12,
|
||||
"ModifyIndex": 13,
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Create or Update Policy
|
||||
|
||||
This endpoint creates or updates an ACL Policy. This request is always forwarded to the
|
||||
authoritative region.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `POST` | `/acl/policy/:policy_name` | `(empty body)` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | ACL Required |
|
||||
| ---------------- | ------------------ |
|
||||
| `NO` | `management` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `Name` `(string: <required>)` - Specifies the name of the policy.
|
||||
Creates the policy if the name does not exist, otherwise updates the existing policy.
|
||||
|
||||
- `Description` `(string: <optional>)` - Specifies a human readable description.
|
||||
|
||||
- `Rules` `(string: <required>)` - Specifies the Policy rules in HCL or JSON format.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "my-policy",
|
||||
"Description": "This is a great policy",
|
||||
"Rules": ""
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://nomad.rocks/v1/acl/policy/my-policy
|
||||
```
|
||||
|
||||
## Read Policy
|
||||
|
||||
This endpoint reads an ACL policy with the given name. This queries the policy that have been
|
||||
replicated to the region, and may lag behind the authoritative region.
|
||||
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/acl/policy/:policy_name` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries), [consistency modes](/api/index.html#consistency-modes) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ------------ |
|
||||
| `YES` | `all` | `management` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/v1/acl/policy/foo
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "foo",
|
||||
"Rules": "",
|
||||
"Description": "",
|
||||
"CreateIndex": 12,
|
||||
"ModifyIndex": 13
|
||||
}
|
||||
```
|
||||
|
||||
## Delete Policy
|
||||
|
||||
This endpoint deletes the named ACL policy. This request is always forwarded to the
|
||||
authoritative region.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| `DELETE` | `/acl/policy/:policy_name` | `(empty body)` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | ACL Required |
|
||||
| ---------------- | ------------- |
|
||||
| `NO` | `management` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `policy_name` `(string: <required>)` - Specifies the policy name to delete.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request DELETE \
|
||||
https://nomad.rocks/v1/acl/policy/foo
|
||||
```
|
||||
|
||||
297
website/source/api/acl-tokens.html.md
Normal file
297
website/source/api/acl-tokens.html.md
Normal file
@@ -0,0 +1,297 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: ACL Tokens - HTTP API
|
||||
sidebar_current: api-acl-tokens
|
||||
description: |-
|
||||
The /acl/token/ endpoints are used to configure and manage ACL tokens.
|
||||
---
|
||||
|
||||
# ACL Tokens HTTP API
|
||||
|
||||
The `/acl/bootstrap`, `/acl/tokens`, and `/acl/token/` endpoints are used to manage ACL tokens.
|
||||
|
||||
## Bootstrap Token
|
||||
|
||||
This endpoint is used to bootstrap the ACL system and provide the initial management token.
|
||||
This request is always forwarded to the authoritative region. It can only be invoked once.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `POST` | `/acl/bootstrap` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | ACL Required |
|
||||
| ---------------- | ------------------ |
|
||||
| `NO` | `none` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request POST \
|
||||
https://nomad.rocks/v1/acl/bootstrap
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"AccessorID":"b780e702-98ce-521f-2e5f-c6b87de05b24",
|
||||
"SecretID":"3f4a0fcd-7c42-773c-25db-2d31ba0c05fe",
|
||||
"Name":"Bootstrap Token",
|
||||
"Type":"management",
|
||||
"Policies":null,
|
||||
"Global":true,
|
||||
"CreateTime":"2017-08-23T22:47:14.695408057Z",
|
||||
"CreateIndex":7,
|
||||
"ModifyIndex":7
|
||||
}
|
||||
```
|
||||
|
||||
## List Tokens
|
||||
|
||||
This endpoint lists all ACL tokens. This lists the local tokens and the global
|
||||
tokens which have been replicated to the region, and may lag behind the authoritative region.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/acl/tokens` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries), [consistency modes](/api/index.html#consistency-modes) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ------------ |
|
||||
| `YES` | `all` | `management` |
|
||||
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/v1/acl/tokens
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
|
||||
"Name": "Bootstrap Token",
|
||||
"Type": "management",
|
||||
"Policies": null,
|
||||
"Global": true,
|
||||
"CreateTime": "2017-08-23T22:47:14.695408057Z",
|
||||
"CreateIndex": 7,
|
||||
"ModifyIndex": 7
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Create Token
|
||||
|
||||
This endpoint creates an ACL Token. If the token is a global token, the request
|
||||
is forwarded to the authoritative region.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `POST` | `/acl/token` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | ACL Required |
|
||||
| ---------------- | ------------------ |
|
||||
| `NO` | `management` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `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`.
|
||||
|
||||
- `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.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "Readonly token",
|
||||
"Type": "client",
|
||||
"Policies": ["readonly"],
|
||||
"Global": false
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://nomad.rocks/v1/acl/token
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
||||
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
|
||||
"Name": "Readonly token",
|
||||
"Type": "client",
|
||||
"Policies": [
|
||||
"readonly"
|
||||
],
|
||||
"Global": false,
|
||||
"CreateTime": "2017-08-23T23:25:41.429154233Z",
|
||||
"CreateIndex": 52,
|
||||
"ModifyIndex": 52
|
||||
}
|
||||
```
|
||||
|
||||
## Update Token
|
||||
|
||||
This endpoint updates an existing ACL Token. If the token is a global token, the request
|
||||
is forwarded to the authoritative region. Note that a token cannot be switched from global
|
||||
to local or visa versa.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `POST` | `/acl/token/:accessor_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | ACL Required |
|
||||
| ---------------- | ------------------ |
|
||||
| `NO` | `management` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `AccessorID` `(string: <required>)` - Specifies the token (by accessor) that is being updated. Must match payload body and request path.
|
||||
|
||||
- `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`.
|
||||
|
||||
- `Policies` `(array<string>: <required>)` - Must be null or blank for `management` type tokens, otherwise must specify at least one policy for `client` type tokens.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
||||
"Name": "Read-write token",
|
||||
"Type": "client",
|
||||
"Policies": ["readwrite"],
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://nomad.rocks/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
||||
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
|
||||
"Name": "Read-write token",
|
||||
"Type": "client",
|
||||
"Policies": [
|
||||
"readwrite"
|
||||
],
|
||||
"Global": false,
|
||||
"CreateTime": "2017-08-23T23:25:41.429154233Z",
|
||||
"CreateIndex": 52,
|
||||
"ModifyIndex": 64
|
||||
}
|
||||
```
|
||||
|
||||
## Read Token
|
||||
|
||||
This endpoint reads an ACL token with the given accessor. If the token is a global token
|
||||
which has been replicated to the region it may lag behind the authoritative region.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ---------------------------- | -------------------------- |
|
||||
| `GET` | `/acl/token/:accessor_id` | `application/json` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries), [consistency modes](/api/index.html#consistency-modes) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | Consistency Modes | ACL Required |
|
||||
| ---------------- | ----------------- | ------------ |
|
||||
| `YES` | `all` | `management` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
https://nomad.rocks/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
||||
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
|
||||
"Name": "Read-write token",
|
||||
"Type": "client",
|
||||
"Policies": [
|
||||
"readwrite"
|
||||
],
|
||||
"Global": false,
|
||||
"CreateTime": "2017-08-23T23:25:41.429154233Z",
|
||||
"CreateIndex": 52,
|
||||
"ModifyIndex": 64
|
||||
}
|
||||
```
|
||||
|
||||
## Delete Token
|
||||
|
||||
This endpoint deletes the ACL token by accessor. This request is forwarded to the
|
||||
authoritative region for global tokens.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| -------- | ---------------------------- | -------------------------- |
|
||||
| `DELETE` | `/acl/token/:accessor_id` | `(empty body)` |
|
||||
|
||||
The table below shows this endpoint's support for
|
||||
[blocking queries](/api/index.html#blocking-queries) and
|
||||
[required ACLs](/api/index.html#acls).
|
||||
|
||||
| Blocking Queries | ACL Required |
|
||||
| ---------------- | ------------- |
|
||||
| `NO` | `management` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `accessor_id` `(string: <required>)` - Specifies the ACL token accessor ID.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```text
|
||||
$ curl \
|
||||
--request DELETE \
|
||||
https://nomad.rocks/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
|
||||
```
|
||||
|
||||
50
website/source/docs/agent/configuration/acl.html.md
Normal file
50
website/source/docs/agent/configuration/acl.html.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
layout: "docs"
|
||||
page_title: "acl Stanza - Agent Configuration"
|
||||
sidebar_current: "docs-agent-configuration-acl"
|
||||
description: |-
|
||||
The "acl" stanza configures the Nomad agent to enable ACLs and tune various parameters.
|
||||
---
|
||||
|
||||
# `acl` Stanza
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th width="120">Placement</th>
|
||||
<td>
|
||||
<code>**acl**</code>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
The `acl` stanza configures the Nomad agent to enable ACLs and tunes various ACL parameters.
|
||||
|
||||
```hcl
|
||||
acl {
|
||||
enabled = true
|
||||
token_ttl = "30s"
|
||||
policy_ttl = "60s"
|
||||
}
|
||||
```
|
||||
|
||||
## `acl` Parameters
|
||||
|
||||
- `enabled` `(bool: false)` - Specifies if ACL enforcement is enabled. All other
|
||||
client configuration options depend on this value.
|
||||
|
||||
- `token_ttl` `(string: "30s")` - Specifies the maximum time-to-live (TTL) for
|
||||
cached ACL tokens. This does not affect servers, since they do not cache tokens.
|
||||
Setting this value lower reduces how stale a token can be, but increases
|
||||
the request load against servers. If a client cannot reach a server, for example
|
||||
because of an outage, the TTL will be ignored and the cached value used.
|
||||
|
||||
- `policy_ttl` `(string: "30s")` - Specifies the maximum time-to-live (TTL) for
|
||||
cached ACL policies. This does not affect servers, since they do not cache policies.
|
||||
Setting this value lower reduces how stale a policy can be, but increases
|
||||
the request load against servers. If a client cannot reach a server, for example
|
||||
because of an outage, the TTL will be ignored and the cached value used.
|
||||
|
||||
- `replication_token` `(string: "")` - Specifies the Secret ID of the ACL token
|
||||
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.
|
||||
|
||||
@@ -74,6 +74,8 @@ testing.
|
||||
|
||||
## General Parameters
|
||||
|
||||
- `acl` <code>([ACL][acl]: nil)</code> - Specifies configuration which is specific to ACLs.
|
||||
|
||||
- `addresses` `(Addresses: see below)` - Specifies the bind address for
|
||||
individual network services. Any values configured in this stanza take
|
||||
precedence over the default [bind_addr](#bind_addr).
|
||||
@@ -230,3 +232,4 @@ http_api_response_headers {
|
||||
[tls]: /docs/agent/configuration/tls.html "Nomad Agent tls Configuration"
|
||||
[client]: /docs/agent/configuration/client.html "Nomad Agent client Configuration"
|
||||
[server]: /docs/agent/configuration/server.html "Nomad Agent server Configuration"
|
||||
[acl]: /docs/agent/configuration/acl.html "Nomad Agent ACL Configuration"
|
||||
|
||||
@@ -34,6 +34,11 @@ server {
|
||||
|
||||
## `server` Parameters
|
||||
|
||||
- `authoritative_region` `(string: "")` - Specifies the authoritative region, which
|
||||
provides a single source of truth for global configurations such as ACL Policies and
|
||||
global ACL tokens. Non-authoritative regions will replicate from the authoritative
|
||||
to act as a mirror. By default, the local region is assumed to be authoritative.
|
||||
|
||||
- `bootstrap_expect` `(int: required)` - Specifies the number of server nodes to
|
||||
wait for before bootstrapping. It is most common to use the odd-numbered
|
||||
integers `3` or `5` for this value, depending on the cluster size. A value of
|
||||
|
||||
@@ -15,6 +15,14 @@
|
||||
|
||||
<hr>
|
||||
|
||||
<li<%= sidebar_current("api-acl-policies") %>>
|
||||
<a href="/api/acl-policies.html">ACL Policies</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("api-acl-tokens") %>>
|
||||
<a href="/api/acl-tokens.html">ACL Tokens</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("api-agent") %>>
|
||||
<a href="/api/agent.html">Agent</a>
|
||||
</li>
|
||||
|
||||
@@ -300,6 +300,9 @@
|
||||
<li<%= sidebar_current("docs-agent-configuration") %>>
|
||||
<a href="/docs/agent/configuration/index.html">Configuration</a>
|
||||
<ul class="nav">
|
||||
<li <%= sidebar_current("docs-agent-configuration-acl") %>>
|
||||
<a href="/docs/agent/configuration/acl.html">acl</a>
|
||||
</li>
|
||||
<li <%= sidebar_current("docs-agent-configuration-client") %>>
|
||||
<a href="/docs/agent/configuration/client.html">client</a>
|
||||
</li>
|
||||
|
||||
Reference in New Issue
Block a user