diff --git a/website/source/api/acl-policies.html.md b/website/source/api/acl-policies.html.md new file mode 100644 index 000000000..140ed37f7 --- /dev/null +++ b/website/source/api/acl-policies.html.md @@ -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: )` - Specifies the name of the policy. + Creates the policy if the name does not exist, otherwise updates the existing policy. + +- `Description` `(string: )` - Specifies a human readable description. + +- `Rules` `(string: )` - 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: )` - Specifies the policy name to delete. + +### Sample Request + +```text +$ curl \ + --request DELETE \ + https://nomad.rocks/v1/acl/policy/foo +``` + diff --git a/website/source/api/acl-tokens.html.md b/website/source/api/acl-tokens.html.md new file mode 100644 index 000000000..c7615dacf --- /dev/null +++ b/website/source/api/acl-tokens.html.md @@ -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: )` - Specifies the human readable name of the token. + +- `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. + +- `Global` `(bool: )` - 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: )` - Specifies the token (by accessor) that is being updated. Must match payload body and request path. + +- `Name` `(string: )` - Specifies the human readable name of the token. + +- `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. + +### 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: )` - Specifies the ACL token accessor ID. + +### Sample Request + +```text +$ curl \ + --request DELETE \ + https://nomad.rocks/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429 +``` + diff --git a/website/source/docs/agent/configuration/acl.html.md b/website/source/docs/agent/configuration/acl.html.md new file mode 100644 index 000000000..0cd0a9c45 --- /dev/null +++ b/website/source/docs/agent/configuration/acl.html.md @@ -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 + + + + + + +
Placement + **acl** +
+ +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. + diff --git a/website/source/docs/agent/configuration/index.html.md b/website/source/docs/agent/configuration/index.html.md index da1164a8b..854c7c395 100644 --- a/website/source/docs/agent/configuration/index.html.md +++ b/website/source/docs/agent/configuration/index.html.md @@ -74,6 +74,8 @@ testing. ## General Parameters +- `acl` ([ACL][acl]: nil) - 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" diff --git a/website/source/docs/agent/configuration/server.html.md b/website/source/docs/agent/configuration/server.html.md index 1e55aedc4..265db668d 100644 --- a/website/source/docs/agent/configuration/server.html.md +++ b/website/source/docs/agent/configuration/server.html.md @@ -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 diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index 94f2e91e2..f3f03a7d7 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -15,6 +15,14 @@
+ > + ACL Policies + + + > + ACL Tokens + + > Agent diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index ad14e19ec..8db66ab10 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -300,6 +300,9 @@ > Configuration