luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

replace internal .html link extensions

This commit is contained in:
Jeff Escalante 2020-04-09 19:46:54 -04:00
parent 4211f12f38
commit 99784c4f24
No known key found for this signature in database
GPG Key ID: 32D23C61AB5450DB
225 changed files with 2164 additions and 2164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
website/pages/api-docs/acl-legacy.mdx
View File

@ -9,7 +9,7 @@ description: >-
-> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_ -> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_
recommended you do not build anything using the legacy system and consider using recommended you do not build anything using the legacy system and consider using
the new ACL [Token](/docs/api/acl-token.html) and [Policy](/docs/api/acl-policy.html) APIs instead. the new ACL [Token](/docs/api/acl-token) and [Policy](/docs/api/acl-policy) APIs instead.
# ACL HTTP API # ACL HTTP API
@ -19,7 +19,7 @@ These `/acl` endpoints create, update, destroy, and query ACL tokens in Consul.
## Bootstrap ACLs ## Bootstrap ACLs
This endpoint does a special one-time bootstrap of the ACL system, making the first This endpoint does a special one-time bootstrap of the ACL system, making the first
management token if the [`acl_master_token`](/docs/agent/options.html#acl_master_token) management token if the [`acl_master_token`](/docs/agent/options#acl_master_token)
is not specified in the Consul server configuration, and if the cluster has not been is not specified in the Consul server configuration, and if the cluster has not been
bootstrapped previously. This is available in Consul 0.9.1 and later, and requires all bootstrapped previously. This is available in Consul 0.9.1 and later, and requires all
Consul servers to be upgraded in order to operate. Consul servers to be upgraded in order to operate.
@ -32,9 +32,9 @@ configuration files.
| `PUT` | `/acl/bootstrap` | `application/json` | | `PUT` | `/acl/bootstrap` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -75,9 +75,9 @@ This endpoint makes a new ACL token.
| `PUT` | `/acl/create` | `application/json` | | `PUT` | `/acl/create` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -134,9 +134,9 @@ generating a new token ID, the `ID` field must be provided.
| `PUT` | `/acl/update` | `application/json` | | `PUT` | `/acl/update` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -187,9 +187,9 @@ This endpoint deletes an ACL token with the given ID.
Even though the return type is application/json, the value is either true or false, indicating whether the delete succeeded. Even though the return type is application/json, the value is either true or false, indicating whether the delete succeeded.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -224,9 +224,9 @@ This endpoint reads an ACL token with the given ID.
| `GET` | `/acl/info/:uuid` | `application/json` | | `GET` | `/acl/info/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -273,9 +273,9 @@ complex rule management.
| `PUT` | `/acl/clone/:uuid` | `application/json` | | `PUT` | `/acl/clone/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -312,9 +312,9 @@ This endpoint lists all the active ACL tokens.
| `GET` | `/acl/list` | `application/json` | | `GET` | `/acl/list` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -357,9 +357,9 @@ for more details.
| `GET` | `/acl/replication` | `application/json` | | `GET` | `/acl/replication` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -400,7 +400,7 @@ $ curl \
- `SourceDatacenter` is the authoritative ACL datacenter that ACLs are being - `SourceDatacenter` is the authoritative ACL datacenter that ACLs are being
replicated from, and will match the replicated from, and will match the
[`primary_datacenter`](/docs/agent/options.html#primary_datacenter) configuration. [`primary_datacenter`](/docs/agent/options#primary_datacenter) configuration.
- `ReplicatedIndex` is the last index that was successfully replicated. You can - `ReplicatedIndex` is the last index that was successfully replicated. You can
compare this to the `X-Consul-Index` header returned by the compare this to the `X-Consul-Index` header returned by the

38
website/pages/api-docs/acl/auth-methods.mdx
View File

@ -27,9 +27,9 @@ This endpoint creates a new ACL auth method.
| `PUT` | `/acl/auth-method` | `application/json` | | `PUT` | `/acl/auth-method` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -51,7 +51,7 @@ The table below shows this endpoint's support for
- `Config` `(map[string]string: <required>)` - The raw configuration to use for - `Config` `(map[string]string: <required>)` - The raw configuration to use for
the chosen auth method. Contents will vary depending upon the type chosen. the chosen auth method. Contents will vary depending upon the type chosen.
For more information on configuring specific auth method types, see the [auth For more information on configuring specific auth method types, see the [auth
method documentation](/docs/acl/acl-auth-methods.html). method documentation](/docs/acl/acl-auth-methods).
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to - `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
create the auth method within. If not provided in the JSON body, the value of create the auth method within. If not provided in the JSON body, the value of
@ -110,9 +110,9 @@ auth method exists with the given name, a 404 is returned instead of a
| `GET` | `/acl/auth-method/:name` | `application/json` | | `GET` | `/acl/auth-method/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -162,9 +162,9 @@ This endpoint updates an existing ACL auth method.
| `PUT` | `/acl/auth-method/:name` | `application/json` | | `PUT` | `/acl/auth-method/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -188,7 +188,7 @@ The table below shows this endpoint's support for
- `Config` `(map[string]string: <required>)` - The raw configuration to use for - `Config` `(map[string]string: <required>)` - The raw configuration to use for
the chosen auth method. Contents will vary depending upon the type chosen. the chosen auth method. Contents will vary depending upon the type chosen.
For more information on configuring specific auth method types, see the [auth For more information on configuring specific auth method types, see the [auth
method documentation](/docs/acl/acl-auth-methods.html). method documentation](/docs/acl/acl-auth-methods).
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of - `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
the auth method to update. If not provided in the JSON body, the value of the auth method to update. If not provided in the JSON body, the value of
@ -240,8 +240,8 @@ $ curl -X PUT \
This endpoint deletes an ACL auth method. This endpoint deletes an ACL auth method.
~> Deleting an auth method will also immediately delete all associated ~> Deleting an auth method will also immediately delete all associated
[binding rules](/api/acl/binding-rules.html) as well as any [binding rules](/api/acl/binding-rules) as well as any
outstanding [tokens](/api/acl/tokens.html) created from this auth method. outstanding [tokens](/api/acl/tokens) created from this auth method.
| Method | Path | Produces | | Method | Path | Produces |
| -------- | ------------------------ | ------------------ | | -------- | ------------------------ | ------------------ |
@ -251,9 +251,9 @@ Even though the return type is application/json, the value is either true or
false indicating whether the delete succeeded. false indicating whether the delete succeeded.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -293,9 +293,9 @@ This endpoint lists all the ACL auth methods.
| `GET` | `/acl/auth-methods` | `application/json` | | `GET` | `/acl/auth-methods` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

30
website/pages/api-docs/acl/binding-rules.mdx
View File

@ -27,9 +27,9 @@ This endpoint creates a new ACL binding rule.
| `PUT` | `/acl/binding-rule` | `application/json` | | `PUT` | `/acl/binding-rule` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -140,9 +140,9 @@ response.
| `GET` | `/acl/binding-rule/:id` | `application/json` | | `GET` | `/acl/binding-rule/:id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -190,9 +190,9 @@ This endpoint updates an existing ACL binding rule.
| `PUT` | `/acl/binding-rule/:id` | `application/json` | | `PUT` | `/acl/binding-rule/:id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -309,9 +309,9 @@ Even though the return type is application/json, the value is either true or
false indicating whether the delete succeeded. false indicating whether the delete succeeded.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -351,9 +351,9 @@ This endpoint lists all the ACL binding rules.
| `GET` | `/acl/binding-rules` | `application/json` | | `GET` | `/acl/binding-rules` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

56
website/pages/api-docs/acl/index.mdx
View File

@ -8,9 +8,9 @@ description: The /acl endpoints manage the Consul's ACL system.
# ACL HTTP API # ACL HTTP API
-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html) -> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api/acl/tokens.html) and [policies](/api/acl/policies.html) with the `/acl` endpoints. The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api/acl/tokens) and [policies](/api/acl/policies) with the `/acl` endpoints.
For more information on how to setup ACLs, please see For more information on how to setup ACLs, please see
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls). the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
@ -18,7 +18,7 @@ the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/pro
## Bootstrap ACLs ## Bootstrap ACLs
This endpoint does a special one-time bootstrap of the ACL system, making the first This endpoint does a special one-time bootstrap of the ACL system, making the first
management token if the [`acl.tokens.master`](/docs/agent/options.html#acl_tokens_master) management token if the [`acl.tokens.master`](/docs/agent/options#acl_tokens_master)
configuration entry is not specified in the Consul server configuration and if the configuration entry is not specified in the Consul server configuration and if the
cluster has not been bootstrapped previously. This is available in Consul 0.9.1 and later, cluster has not been bootstrapped previously. This is available in Consul 0.9.1 and later,
and requires all Consul servers to be upgraded in order to operate. and requires all Consul servers to be upgraded in order to operate.
@ -31,9 +31,9 @@ configuration files.
| `PUT` | `/acl/bootstrap` | `application/json` | | `PUT` | `/acl/bootstrap` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -96,9 +96,9 @@ for more details.
| `GET` | `/acl/replication` | `application/json` | | `GET` | `/acl/replication` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -142,7 +142,7 @@ $ curl \
- `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being - `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being
replicated from and will match the replicated from and will match the
[`primary_datacenter`](/docs/agent/options.html#primary_datacenter) configuration. [`primary_datacenter`](/docs/agent/options#primary_datacenter) configuration.
- `ReplicationType` - The type of replication that is currently in use. - `ReplicationType` - The type of replication that is currently in use.
@ -156,17 +156,17 @@ $ curl \
- `ReplicatedIndex` - The last index that was successfully replicated. Which data - `ReplicatedIndex` - The last index that was successfully replicated. Which data
the replicated index refers to depends on the replication type. For `legacy` the replicated index refers to depends on the replication type. For `legacy`
replication this can be compared with the value of the `X-Consul-Index` header replication this can be compared with the value of the `X-Consul-Index` header
returned by the [`/v1/acl/list`](/api/acl/legacy.html#acl_list) endpoint to returned by the [`/v1/acl/list`](/api/acl/legacy#acl_list) endpoint to
determine if the replication process has gotten all available ACLs. When in either determine if the replication process has gotten all available ACLs. When in either
`tokens` or `policies` mode, this index can be compared with the value of the `tokens` or `policies` mode, this index can be compared with the value of the
`X-Consul-Index` header returned by the [`/v1/acl/policies`](/api/acl/policies.html#list-policies) `X-Consul-Index` header returned by the [`/v1/acl/policies`](/api/acl/policies#list-policies)
endpoint to determine if the policy replication process has gotten all available endpoint to determine if the policy replication process has gotten all available
ACL policies. Note that ACL replication is rate limited so the indexes may lag behind ACL policies. Note that ACL replication is rate limited so the indexes may lag behind
the primary datacenter. the primary datacenter.
- `ReplicatedTokenIndex` - The last token index that was successfully replicated. - `ReplicatedTokenIndex` - The last token index that was successfully replicated.
This index can be compared with the value of the `X-Consul-Index` header returned This index can be compared with the value of the `X-Consul-Index` header returned
by the [`/v1/acl/tokens`](/api/acl/tokens.html#list) endpoint to determine by the [`/v1/acl/tokens`](/api/acl/tokens#list) endpoint to determine
if the replication process has gotten all available ACL tokens. Note that ACL if the replication process has gotten all available ACL tokens. Note that ACL
replication is rate limited so the indexes may lag behind the primary replication is rate limited so the indexes may lag behind the primary
datacenter. datacenter.
@ -195,9 +195,9 @@ migrations.
| `POST` | `/acl/rules/translate` | `text/plain` | | `POST` | `/acl/rules/translate` | `text/plain` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -235,16 +235,16 @@ This endpoint translates the legacy rules embedded within a legacy ACL into the
syntax. It is intended to be used by operators managing Consul's ACLs and performing syntax. It is intended to be used by operators managing Consul's ACLs and performing
legacy token to new policy migrations. Note that this API requires the auto-generated legacy token to new policy migrations. Note that this API requires the auto-generated
Accessor ID of the legacy token. This ID can be retrieved using the Accessor ID of the legacy token. This ID can be retrieved using the
[`/v1/acl/token/self`](/api/acl/tokens.html#self) endpoint. [`/v1/acl/token/self`](/api/acl/tokens#self) endpoint.
| Method | Path | Produces | | Method | Path | Produces |
| ------ | ----------------------------------- | ------------ | | ------ | ----------------------------------- | ------------ |
| `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` | | `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -268,7 +268,7 @@ agent_prefix "" {
## Login to Auth Method ## Login to Auth Method
This endpoint was added in Consul 1.5.0 and is used to exchange an [auth This endpoint was added in Consul 1.5.0 and is used to exchange an [auth
method](/docs/acl/acl-auth-methods.html) bearer token for a newly-created method](/docs/acl/acl-auth-methods) bearer token for a newly-created
Consul ACL token. Consul ACL token.
| Method | Path | Produces | | Method | Path | Produces |
@ -276,9 +276,9 @@ Consul ACL token.
| `POST` | `/acl/login` | `application/json` | | `POST` | `/acl/login` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -287,7 +287,7 @@ The table below shows this endpoint's support for
-> **Note** - To use the login process to create tokens in any connected -> **Note** - To use the login process to create tokens in any connected
secondary datacenter, [ACL secondary datacenter, [ACL
replication](/docs/agent/options.html#acl_enable_token_replication) must be replication](/docs/agent/options#acl_enable_token_replication) must be
enabled. Login requires the ability to create local tokens which is restricted enabled. Login requires the ability to create local tokens which is restricted
to the primary datacenter and any secondary datacenters with ACL token to the primary datacenter and any secondary datacenters with ACL token
replication enabled. replication enabled.
@ -366,9 +366,9 @@ with the `X-Consul-Token` header or the `token` query parameter.
| `POST` | `/acl/logout` | `application/json` | | `POST` | `/acl/logout` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

42
website/pages/api-docs/acl/legacy.mdx
View File

@ -12,7 +12,7 @@ description: >-
-> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_ -> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_
recommended you do not build anything using the legacy system and consider using recommended you do not build anything using the legacy system and consider using
the new ACL [Token](/api/acl/tokens.html) and [Policy](/api/acl/policies.html) APIs instead. the new ACL [Token](/api/acl/tokens) and [Policy](/api/acl/policies) APIs instead.
The `/acl` endpoints create, update, destroy, and query ACL tokens in Consul. The `/acl` endpoints create, update, destroy, and query ACL tokens in Consul.
@ -27,9 +27,9 @@ This endpoint makes a new ACL token.
| `PUT` | `/acl/create` | `application/json` | | `PUT` | `/acl/create` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -47,7 +47,7 @@ The table below shows this endpoint's support for
are: `client` and `management`. are: `client` and `management`.
- `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the - `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the
`Rules` property is detailed in the [ACL Rule documentation](/docs/acl/acl-rules.html). `Rules` property is detailed in the [ACL Rule documentation](/docs/acl/acl-rules).
### Sample Payload ### Sample Payload
@ -86,9 +86,9 @@ generating a new token ID, the `ID` field must be provided.
| `PUT` | `/acl/update` | `application/json` | | `PUT` | `/acl/update` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -140,9 +140,9 @@ Even though the return type is application/json, the value is either true or
false, indicating whether the delete succeeded. false, indicating whether the delete succeeded.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -177,9 +177,9 @@ This endpoint reads an ACL token with the given ID.
| `GET` | `/acl/info/:uuid` | `application/json` | | `GET` | `/acl/info/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -226,9 +226,9 @@ complex rule management.
| `PUT` | `/acl/clone/:uuid` | `application/json` | | `PUT` | `/acl/clone/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -265,9 +265,9 @@ This endpoint lists all the active ACL tokens.
| `GET` | `/acl/list` | `application/json` | | `GET` | `/acl/list` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -298,4 +298,4 @@ $ curl \
## Check ACL Replication ## Check ACL Replication
The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api/acl/acl.html#check-acl-replication) to learn more about this endpoint. The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api/acl/acl#check-acl-replication) to learn more about this endpoint.

42
website/pages/api-docs/acl/policies.mdx
View File

@ -8,7 +8,7 @@ description: The /acl/policy endpoints manage Consul's ACL policies.
# ACL Policy HTTP API # ACL Policy HTTP API
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html) -> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy), The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy),
[update](#update-a-policy), [list](#list-policies) and [update](#update-a-policy), [list](#list-policies) and
@ -26,9 +26,9 @@ This endpoint creates a new ACL policy.
| `PUT` | `/acl/policy` | `application/json` | | `PUT` | `/acl/policy` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -44,7 +44,7 @@ The table below shows this endpoint's support for
- `Description` `(string: "")` - Free form human readable description of the policy. - `Description` `(string: "")` - Free form human readable description of the policy.
- `Rules` `(string: "")` - Specifies rules for the ACL policy. The format of the - `Rules` `(string: "")` - Specifies rules for the ACL policy. The format of the
`Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules.html). `Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules).
- `Datacenters` `(array<string>)` - Specifies the datacenters the policy is valid within. - `Datacenters` `(array<string>)` - Specifies the datacenters the policy is valid within.
When no datacenters are provided the policy is valid in all datacenters including When no datacenters are provided the policy is valid in all datacenters including
@ -99,9 +99,9 @@ This endpoint reads an ACL policy with the given ID.
| `GET` | `/acl/policy/:id` | `application/json` | | `GET` | `/acl/policy/:id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -149,9 +149,9 @@ This endpoint reads an ACL policy with the given ID.
| `GET` | `/acl/policy/name/:name` | `application/json` | | `GET` | `/acl/policy/name/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -199,9 +199,9 @@ This endpoint updates an existing ACL policy.
| `PUT` | `/acl/policy/:id` | `application/json` | | `PUT` | `/acl/policy/:id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -221,7 +221,7 @@ The table below shows this endpoint's support for
- `Description` `(string: "")` - Free form human readable description of this policy. - `Description` `(string: "")` - Free form human readable description of this policy.
- `Rules` `(string: "")` - Specifies rules for this ACL policy. The format of the - `Rules` `(string: "")` - Specifies rules for this ACL policy. The format of the
`Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules.html). `Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules).
- `Datacenters` `(array<string>)` - Specifies the datacenters this policy is valid within. - `Datacenters` `(array<string>)` - Specifies the datacenters this policy is valid within.
When no datacenters are provided the policy is valid in all datacenters including When no datacenters are provided the policy is valid in all datacenters including
@ -278,9 +278,9 @@ Even though the return type is application/json, the value is either true or
false indicating whether the delete succeeded. false indicating whether the delete succeeded.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -320,9 +320,9 @@ This endpoint lists all the ACL policies.
| `GET` | `/acl/policies` | `application/json` | | `GET` | `/acl/policies` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

40
website/pages/api-docs/acl/roles.mdx
View File

@ -25,9 +25,9 @@ This endpoint creates a new ACL role.
| `PUT` | `/acl/role` | `application/json` | | `PUT` | `/acl/role` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -50,7 +50,7 @@ The table below shows this endpoint's support for
breaking tokens. breaking tokens.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service - `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be identities](/docs/acl/acl-system#acl-service-identities) that should be
applied to the role. Added in Consul 1.5.0. applied to the role. Added in Consul 1.5.0.
- `ServiceName` `(string: <required>)` - The name of the service. The name - `ServiceName` `(string: <required>)` - The name of the service. The name
@ -141,9 +141,9 @@ given ID, a 404 is returned instead of a 200 response.
| `GET` | `/acl/role/:id` | `application/json` | | `GET` | `/acl/role/:id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -204,9 +204,9 @@ given name, a 404 is returned instead of a 200 response.
| `GET` | `/acl/role/name/:name` | `application/json` | | `GET` | `/acl/role/name/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -266,9 +266,9 @@ This endpoint updates an existing ACL role.
| `PUT` | `/acl/role/:id` | `application/json` | | `PUT` | `/acl/role/:id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -295,7 +295,7 @@ The table below shows this endpoint's support for
breaking tokens. breaking tokens.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service - `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be identities](/docs/acl/acl-system#acl-service-identities) that should be
applied to the role. Added in Consul 1.5.0. applied to the role. Added in Consul 1.5.0.
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of - `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
@ -366,9 +366,9 @@ Even though the return type is application/json, the value is either true or
false indicating whether the delete succeeded. false indicating whether the delete succeeded.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -408,9 +408,9 @@ This endpoint lists all the ACL roles.
| `GET` | `/acl/roles` | `application/json` | | `GET` | `/acl/roles` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

48
website/pages/api-docs/acl/tokens.mdx
View File

@ -8,7 +8,7 @@ description: The /acl/token endpoints manage Consul's ACL Tokens.
# ACL Token HTTP API # ACL Token HTTP API
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html) -> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy)
The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token), The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token),
[update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul. [update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul.
@ -25,9 +25,9 @@ This endpoint creates a new ACL token.
| `PUT` | `/acl/token` | `application/json` | | `PUT` | `/acl/token` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -62,7 +62,7 @@ The table below shows this endpoint's support for
enables role renaming without breaking tokens. Added in Consul 1.5.0. enables role renaming without breaking tokens. Added in Consul 1.5.0.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service - `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be identities](/docs/acl/acl-system#acl-service-identities) that should be
applied to the token. Added in Consul 1.5.0. applied to the token. Added in Consul 1.5.0.
- `ServiceName` `(string: <required>)` - The name of the service. The name - `ServiceName` `(string: <required>)` - The name of the service. The name
@ -154,9 +154,9 @@ This endpoint reads an ACL token with the given Accessor ID.
| `GET` | `/acl/token/:AccessorID` | `application/json` | | `GET` | `/acl/token/:AccessorID` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -221,9 +221,9 @@ specified with the `X-Consul-Token` header or the `token` query parameter.
| `GET` | `/acl/token/self` | `application/json` | | `GET` | `/acl/token/self` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -274,9 +274,9 @@ This endpoint updates an existing ACL token.
| `PUT` | `/acl/token/:AccessorID` | `application/json` | | `PUT` | `/acl/token/:AccessorID` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -311,7 +311,7 @@ The table below shows this endpoint's support for
enables role renaming without breaking tokens. enables role renaming without breaking tokens.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service - `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be identities](/docs/acl/acl-system#acl-service-identities) that should be
applied to the token. Added in Consul 1.5.0. applied to the token. Added in Consul 1.5.0.
- `ServiceName` `(string: <required>)` - The name of the service. The name - `ServiceName` `(string: <required>)` - The name of the service. The name
@ -410,9 +410,9 @@ This endpoint clones an existing ACL token.
| `PUT` | `/acl/token/:AccessorID/clone` | `application/json` | | `PUT` | `/acl/token/:AccessorID/clone` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -489,9 +489,9 @@ Even though the return type is application/json, the value is either true or
false, indicating whether the delete succeeded. false, indicating whether the delete succeeded.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -531,9 +531,9 @@ This endpoint lists all the ACL tokens.
| `GET` | `/acl/tokens` | `application/json` | | `GET` | `/acl/tokens` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

44
website/pages/api-docs/agent/check.mdx
View File

@ -20,7 +20,7 @@ using the HTTP API.
It is important to note that the checks known by the agent may be different from It is important to note that the checks known by the agent may be different from
those reported by the catalog. This is usually due to changes being made while those reported by the catalog. This is usually due to changes being made while
there is no leader elected. The agent performs active there is no leader elected. The agent performs active
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations [anti-entropy](/docs/internals/anti-entropy), so in most situations
everything will be in sync within a few seconds. everything will be in sync within a few seconds.
| Method | Path | Produces | | Method | Path | Produces |
@ -28,9 +28,9 @@ everything will be in sync within a few seconds.
| `GET` | `/agent/checks` | `application/json` | | `GET` | `/agent/checks` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -95,9 +95,9 @@ check and keeping the Catalog in sync.
| `PUT` | `/agent/check/register` | `application/json` | | `PUT` | `/agent/check/register` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -250,9 +250,9 @@ not exist, no action is taken.
| `PUT` | `/agent/check/deregister/:check_id` | `application/json` | | `PUT` | `/agent/check/deregister/:check_id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -282,9 +282,9 @@ This endpoint is used with a TTL type check to set the status of the check to
| `PUT` | `/agent/check/pass/:check_id` | `application/json` | | `PUT` | `/agent/check/pass/:check_id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -316,9 +316,9 @@ This endpoint is used with a TTL type check to set the status of the check to
| `PUT` | `/agent/check/warn/:check_id` | `application/json` | | `PUT` | `/agent/check/warn/:check_id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -350,9 +350,9 @@ This endpoint is used with a TTL type check to set the status of the check to
| `PUT` | `/agent/check/fail/:check_id` | `application/json` | | `PUT` | `/agent/check/fail/:check_id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -384,9 +384,9 @@ to reset the TTL clock.
| `PUT` | `/agent/check/update/:check_id` | `application/json` | | `PUT` | `/agent/check/update/:check_id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

32
website/pages/api-docs/agent/connect.mdx
View File

@ -13,7 +13,7 @@ description: >-
The `/agent/connect` endpoints interact with [Connect](/docs/connect) The `/agent/connect` endpoints interact with [Connect](/docs/connect)
with agent-local operations. with agent-local operations.
These endpoints may mirror the [non-agent Connect endpoints](/api/connect.html) These endpoints may mirror the [non-agent Connect endpoints](/api/connect)
in some cases. Almost all agent-local Connect endpoints perform local caching in some cases. Almost all agent-local Connect endpoints perform local caching
to optimize performance of Connect without having to make requests to the server. to optimize performance of Connect without having to make requests to the server.
@ -21,8 +21,8 @@ to optimize performance of Connect without having to make requests to the server
This endpoint tests whether a connection attempt is authorized between This endpoint tests whether a connection attempt is authorized between
two services. This is the primary API that must be implemented by two services. This is the primary API that must be implemented by
[proxies](/docs/connect/proxies.html) or [proxies](/docs/connect/proxies) or
[native integrations](/docs/connect/native.html) [native integrations](/docs/connect/native)
that wish to integrate with Connect. Prior to calling this API, it is expected that wish to integrate with Connect. Prior to calling this API, it is expected
that the client TLS certificate has been properly verified against the that the client TLS certificate has been properly verified against the
current CA roots. current CA roots.
@ -37,9 +37,9 @@ connection attempt.
| `POST` | `/agent/connect/authorize` | `application/json` | | `POST` | `/agent/connect/authorize` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -96,11 +96,11 @@ $ curl \
## Certificate Authority (CA) Roots ## Certificate Authority (CA) Roots
This endpoint returns the trusted certificate authority (CA) root certificates. This endpoint returns the trusted certificate authority (CA) root certificates.
This is used by [proxies](/docs/connect/proxies.html) or This is used by [proxies](/docs/connect/proxies) or
[native integrations](/docs/connect/native.html) to verify served client [native integrations](/docs/connect/native) to verify served client
or server certificates are valid. or server certificates are valid.
This is equivalent to the [non-Agent Connect endpoint](/api/connect.html), This is equivalent to the [non-Agent Connect endpoint](/api/connect),
but the response of this request is cached locally at the agent. This allows but the response of this request is cached locally at the agent. This allows
for very fast response times and for fail open behavior if the server is for very fast response times and for fail open behavior if the server is
unavailable. This endpoint should be used by proxies and native integrations. unavailable. This endpoint should be used by proxies and native integrations.
@ -110,9 +110,9 @@ unavailable. This endpoint should be used by proxies and native integrations.
| `GET` | `/agent/connect/ca/roots` | `application/json` | | `GET` | `/agent/connect/ca/roots` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -160,7 +160,7 @@ connections and is also used as the client certificate for establishing
outbound connections to other services. outbound connections to other services.
The agent generates a CSR locally and calls the The agent generates a CSR locally and calls the
[CA sign API](/api/connect/ca.html) to sign it. The resulting certificate [CA sign API](/api/connect/ca) to sign it. The resulting certificate
is cached and returned by this API until it is near expiry or the root is cached and returned by this API until it is near expiry or the root
certificates change. certificates change.
@ -174,9 +174,9 @@ clients to efficiently wait for certificate rotations.
| `GET` | `/agent/connect/ca/leaf/:service` | `application/json` | | `GET` | `/agent/connect/ca/leaf/:service` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

82
website/pages/api-docs/agent/index.mdx
View File

@ -14,7 +14,7 @@ The `/agent` endpoints are used to interact with the local Consul agent.
Usually, services and checks are registered with an agent which then takes on Usually, services and checks are registered with an agent which then takes on
the burden of keeping that data synchronized with the cluster. For example, the the burden of keeping that data synchronized with the cluster. For example, the
agent registers services and checks with the Catalog and performs agent registers services and checks with the Catalog and performs
[anti-entropy](/docs/internals/anti-entropy.html) to recover from outages. [anti-entropy](/docs/internals/anti-entropy) to recover from outages.
In addition to these endpoints, additional endpoints are grouped in the In addition to these endpoints, additional endpoints are grouped in the
navigation for `Checks` and `Services`. navigation for `Checks` and `Services`.
@ -31,9 +31,9 @@ by agent. The strongly consistent view of nodes is instead provided by
| `GET` | `/agent/members` | `application/json` | | `GET` | `/agent/members` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -97,9 +97,9 @@ to change without notice or deprecation.
| `GET` | `/agent/self` | `application/json` | | `GET` | `/agent/self` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -169,7 +169,7 @@ This endpoint instructs the agent to reload its configuration. Any errors
encountered during this process are returned. encountered during this process are returned.
Not all configuration options are reloadable. See the Not all configuration options are reloadable. See the
[Reloadable Configuration](/docs/agent/options.html#reloadable-configuration) [Reloadable Configuration](/docs/agent/options#reloadable-configuration)
section on the agent options page for details on which options are supported. section on the agent options page for details on which options are supported.
| Method | Path | Produces | | Method | Path | Produces |
@ -177,9 +177,9 @@ section on the agent options page for details on which options are supported.
| `PUT` | `/agent/reload` | `application/json` | | `PUT` | `/agent/reload` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -208,9 +208,9 @@ restart.
| `PUT` | `/agent/maintenance` | `application/json` | | `PUT` | `/agent/maintenance` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -240,12 +240,12 @@ $ curl \
## View Metrics ## View Metrics
This endpoint will dump the metrics for the most recent finished interval. This endpoint will dump the metrics for the most recent finished interval.
For more information about metrics, see the [telemetry](/docs/agent/telemetry.html) For more information about metrics, see the [telemetry](/docs/agent/telemetry)
page. page.
In order to enable [Prometheus](https://prometheus.io/) support, you need to use the In order to enable [Prometheus](https://prometheus.io/) support, you need to use the
configuration directive configuration directive
[`prometheus_retention_time`](/docs/agent/options.html#telemetry-prometheus_retention_time). [`prometheus_retention_time`](/docs/agent/options#telemetry-prometheus_retention_time).
Note: If your metric includes labels that use the same key name multiple times Note: If your metric includes labels that use the same key name multiple times
(i.e. tag=tag2 and tag=tag1), only the sorted last value (tag=tag2) will be visible on (i.e. tag=tag2 and tag=tag1), only the sorted last value (tag=tag2) will be visible on
@ -258,9 +258,9 @@ passed to external metrics providers even though it is not visible through this
| `GET` | `/agent/metrics?format=prometheus` | `text/plain; version=0.0.4; charset=utf-8` | | `GET` | `/agent/metrics?format=prometheus` | `text/plain; version=0.0.4; charset=utf-8` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -380,9 +380,9 @@ This endpoint streams logs from the local agent until the connection is closed.
| `GET` | `/agent/monitor` | `application/json` | | `GET` | `/agent/monitor` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -424,9 +424,9 @@ This endpoint instructs the agent to attempt to connect to a given address.
| `PUT` | `/agent/join/:address` | `application/json` | | `PUT` | `/agent/join/:address` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -464,9 +464,9 @@ can affect cluster availability.
| `PUT` | `/agent/leave` | `application/json` | | `PUT` | `/agent/leave` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -501,9 +501,9 @@ the list of members entirely.
| `PUT` | `/agent/force-leave/:node?prune` | `application/json` | | `PUT` | `/agent/force-leave/:node?prune` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -527,7 +527,7 @@ $ curl \
This endpoint updates the ACL tokens currently in use by the agent. It can be This endpoint updates the ACL tokens currently in use by the agent. It can be
used to introduce ACL tokens to the agent for the first time, or to update used to introduce ACL tokens to the agent for the first time, or to update
tokens that were initially loaded from the agent's configuration. Tokens will be persisted tokens that were initially loaded from the agent's configuration. Tokens will be persisted
only if the [`acl.enable_token_persistence`](/docs/agent/options.html#acl_enable_token_persistence) only if the [`acl.enable_token_persistence`](/docs/agent/options#acl_enable_token_persistence)
configuration is `true`. When not being persisted, they will need to be reset if the agent configuration is `true`. When not being persisted, they will need to be reset if the agent
is restarted. is restarted.
@ -539,9 +539,9 @@ is restarted.
| `PUT` | `/agent/token/replication` | `application/json` | | `PUT` | `/agent/token/replication` | `application/json` |
The paths above correspond to the token names as found in the agent configuration: The paths above correspond to the token names as found in the agent configuration:
[`default`](/docs/agent/options.html#acl_tokens_default), [`agent`](/docs/agent/options.html#acl_tokens_agent), [`default`](/docs/agent/options#acl_tokens_default), [`agent`](/docs/agent/options#acl_tokens_agent),
[`agent_master`](/docs/agent/options.html#acl_tokens_agent_master), and [`agent_master`](/docs/agent/options#acl_tokens_agent_master), and
[`replication`](/docs/agent/options.html#acl_tokens_replication). [`replication`](/docs/agent/options#acl_tokens_replication).
-> **Deprecation Note:** The following paths were deprecated in version 1.4.3 -> **Deprecation Note:** The following paths were deprecated in version 1.4.3
@ -553,14 +553,14 @@ The paths above correspond to the token names as found in the agent configuratio
| `PUT` | `/agent/token/acl_replication_token` | `application/json` | | `PUT` | `/agent/token/acl_replication_token` | `application/json` |
The paths above correspond to the token names as found in the agent configuration: The paths above correspond to the token names as found in the agent configuration:
[`acl_token`](/docs/agent/options.html#acl_token_legacy), [`acl_agent_token`](/docs/agent/options.html#acl_agent_token_legacy), [`acl_token`](/docs/agent/options#acl_token_legacy), [`acl_agent_token`](/docs/agent/options#acl_agent_token_legacy),
[`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy), and [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy), and
[`acl_replication_token`](/docs/agent/options.html#acl_replication_token_legacy). [`acl_replication_token`](/docs/agent/options#acl_replication_token_legacy).
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

82
website/pages/api-docs/agent/service.mdx
View File

@ -22,7 +22,7 @@ or added dynamically using the HTTP API.
It is important to note that the services known by the agent may be different It is important to note that the services known by the agent may be different
from those reported by the catalog. This is usually due to changes being made from those reported by the catalog. This is usually due to changes being made
while there is no leader elected. The agent performs active while there is no leader elected. The agent performs active
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations [anti-entropy](/docs/internals/anti-entropy), so in most situations
everything will be in sync within a few seconds. everything will be in sync within a few seconds.
| Method | Path | Produces | | Method | Path | Produces |
@ -30,9 +30,9 @@ everything will be in sync within a few seconds.
| `GET` | `/agent/services` | `application/json` | | `GET` | `/agent/services` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -123,13 +123,13 @@ following selectors and filter operations being supported:
This endpoint was added in Consul 1.3.0 and returns the full service definition This endpoint was added in Consul 1.3.0 and returns the full service definition
for a single service instance registered on the local agent. It is used by for a single service instance registered on the local agent. It is used by
[Connect proxies](/docs/connect/proxies.html) to discover the embedded proxy [Connect proxies](/docs/connect/proxies) to discover the embedded proxy
configuration that was registered with the instance. configuration that was registered with the instance.
It is important to note that the services known by the agent may be different It is important to note that the services known by the agent may be different
from those reported by the catalog. This is usually due to changes being made from those reported by the catalog. This is usually due to changes being made
while there is no leader elected. The agent performs active while there is no leader elected. The agent performs active
[anti-entropy](/docs/internals/anti-entropy.html), so in most situations [anti-entropy](/docs/internals/anti-entropy), so in most situations
everything will be in sync within a few seconds. everything will be in sync within a few seconds.
| Method | Path | Produces | | Method | Path | Produces |
@ -137,16 +137,16 @@ everything will be in sync within a few seconds.
| `GET` | `/agent/service/:service_id` | `application/json` | | `GET` | `/agent/service/:service_id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ----------------- | ----------------- | ------------- | -------------- | | ----------------- | ----------------- | ------------- | -------------- |
| `YES`<sup>1</sup> | `none` | `none` | `service:read` | | `YES`<sup>1</sup> | `none` | `none` | `service:read` |
<sup>1</sup> Supports [hash-based blocking](/api/features/blocking.html#hash-based-blocking-queries) <sup>1</sup> Supports [hash-based blocking](/api/features/blocking#hash-based-blocking-queries)
only. only.
### Parameters ### Parameters
@ -208,9 +208,9 @@ $ curl \
``` ```
The response has the same structure as the [service The response has the same structure as the [service
definition](/docs/agent/services.html) with one extra field `ContentHash` which definition](/docs/agent/services) with one extra field `ContentHash` which
contains the [hash-based blocking contains the [hash-based blocking
query](/api/features/blocking.html#hash-based-blocking-queries) hash for the result. The query](/api/features/blocking#hash-based-blocking-queries) hash for the result. The
same hash is also present in `X-Consul-ContentHash`. same hash is also present in `X-Consul-ContentHash`.
## Get local service health ## Get local service health
@ -228,9 +228,9 @@ the URL or use Mime Content negotiation by specifying a HTTP Header
| `GET` | `/agent/health/service/name/:service_name?format=text` | `text/plain` | | `GET` | `/agent/health/service/name/:service_name?format=text` | `text/plain` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -258,7 +258,7 @@ Those endpoints might be useful for the following use-cases:
##### Note ##### Note
If you know the ID of service you want to target, it is recommended to use If you know the ID of service you want to target, it is recommended to use
[`/v1/agent/health/service/id/:service_id`](/api/agent/service.html#get-local-service-health-by-id) [`/v1/agent/health/service/id/:service_id`](/api/agent/service#get-local-service-health-by-id)
so you have the result for the service only. When requesting so you have the result for the service only. When requesting
`/v1/agent/health/service/name/:service_name`, the caller will receive the `/v1/agent/health/service/name/:service_name`, the caller will receive the
worst state of all services having the given name. worst state of all services having the given name.
@ -449,7 +449,7 @@ See:
| `GET` | `/agent/health/service/id/:service_id?format=text` | `text/plain` | | `GET` | `/agent/health/service/id/:service_id?format=text` | `text/plain` |
Parameters and response format are the same as Parameters and response format are the same as
[`/v1/agent/health/service/name/:service_name`](/api/agent/service.html#get-local-service-health). [`/v1/agent/health/service/name/:service_name`](/api/agent/service#get-local-service-health).
## Register Service ## Register Service
@ -468,9 +468,9 @@ For "connect-proxy" kind services, the `service:write` ACL for the
| `PUT` | `/agent/service/register` | `application/json` | | `PUT` | `/agent/service/register` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -483,13 +483,13 @@ The table below shows this endpoint's support for
### Parameters ### Parameters
Note that this endpoint, unlike most also [supports `snake_case`](/docs/agent/services.html#service-definition-parameter-case) Note that this endpoint, unlike most also [supports `snake_case`](/docs/agent/services#service-definition-parameter-case)
service definition keys for compatibility with the config file format. service definition keys for compatibility with the config file format.
- `Name` `(string: <required>)` - Specifies the logical name of the service. - `Name` `(string: <required>)` - Specifies the logical name of the service.
Many service instances may share the same logical service name. We recommend using Many service instances may share the same logical service name. We recommend using
[valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames)
for [compatibility with external DNS](/docs/agent/services.html#service-and-tag-names-with-dns). for [compatibility with external DNS](/docs/agent/services#service-and-tag-names-with-dns).
- `ID` `(string: "")` - Specifies a unique ID for this service. This must be - `ID` `(string: "")` - Specifies a unique ID for this service. This must be
unique per _agent_. This defaults to the `Name` parameter if not provided. unique per _agent_. This defaults to the `Name` parameter if not provided.
@ -497,7 +497,7 @@ service definition keys for compatibility with the config file format.
- `Tags` `(array<string>: nil)` - Specifies a list of tags to assign to the - `Tags` `(array<string>: nil)` - Specifies a list of tags to assign to the
service. These tags can be used for later filtering and are exposed via the APIs. service. These tags can be used for later filtering and are exposed via the APIs.
We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames)
for [compatibility with external DNS](/docs/agent/services.html#service-and-tag-names-with-dns) for [compatibility with external DNS](/docs/agent/services#service-and-tag-names-with-dns)
- `Address` `(string: "")` - Specifies the address of the service. If not - `Address` `(string: "")` - Specifies the address of the service. If not
provided, the agent's address is used as the address for the service during provided, the agent's address is used as the address for the service during
@ -516,25 +516,25 @@ service definition keys for compatibility with the config file format.
typical Consul service. This value may also be "connect-proxy" for typical Consul service. This value may also be "connect-proxy" for
services that are [Connect-capable](/docs/connect) services that are [Connect-capable](/docs/connect)
proxies representing another service or "mesh-gateway" for instances of proxies representing another service or "mesh-gateway" for instances of
a [mesh gateway](/docs/connect/mesh_gateway.html) a [mesh gateway](/docs/connect/mesh_gateway)
- `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a - `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a
Connect proxy instance. This is only valid if `Kind == "connect-proxy"` or Connect proxy instance. This is only valid if `Kind == "connect-proxy"` or
`Kind == "mesh-gateway"`. See the [Proxy documentation](/docs/connect/registration/service-registration.html) `Kind == "mesh-gateway"`. See the [Proxy documentation](/docs/connect/registration/service-registration)
for full details. for full details.
- `Connect` `(Connect: nil)` - Specifies the - `Connect` `(Connect: nil)` - Specifies the
[configuration for Connect](/docs/connect/configuration.html). See the [configuration for Connect](/docs/connect/configuration). See the
[Connect Structure](#connect-structure) section below for supported fields. [Connect Structure](#connect-structure) section below for supported fields.
- `Check` `(Check: nil)` - Specifies a check. Please see the - `Check` `(Check: nil)` - Specifies a check. Please see the
[check documentation](/api/agent/check.html) for more information about the [check documentation](/api/agent/check) for more information about the
accepted fields. If you don't provide a name or id for the check then they accepted fields. If you don't provide a name or id for the check then they
will be generated. To provide a custom id and/or name set the `CheckID` will be generated. To provide a custom id and/or name set the `CheckID`
and/or `Name` field. and/or `Name` field.
- `Checks` `(array<Check>: nil)` - Specifies a list of checks. Please see the - `Checks` `(array<Check>: nil)` - Specifies a list of checks. Please see the
[check documentation](/api/agent/check.html) for more information about the [check documentation](/api/agent/check) for more information about the
accepted fields. If you don't provide a name or id for the check then they accepted fields. If you don't provide a name or id for the check then they
will be generated. To provide a custom id and/or name set the `CheckID` will be generated. To provide a custom id and/or name set the `CheckID`
and/or `Name` field. The automatically generated `Name` and `CheckID` depend and/or `Name` field. The automatically generated `Name` and `CheckID` depend
@ -544,7 +544,7 @@ service definition keys for compatibility with the config file format.
- `EnableTagOverride` `(bool: false)` - Specifies to disable the anti-entropy - `EnableTagOverride` `(bool: false)` - Specifies to disable the anti-entropy
feature for this service's tags. If `EnableTagOverride` is set to `true` then feature for this service's tags. If `EnableTagOverride` is set to `true` then
external agents can update this service in the [catalog](/api/catalog.html) external agents can update this service in the [catalog](/api/catalog)
and modify the tags. Subsequent local sync operations by this agent will and modify the tags. Subsequent local sync operations by this agent will
ignore the updated tags. For instance, if an external agent modified both the ignore the updated tags. For instance, if an external agent modified both the
tags and the port for this service and `EnableTagOverride` was set to `true` tags and the port for this service and `EnableTagOverride` was set to `true`
@ -556,7 +556,7 @@ service definition keys for compatibility with the config file format.
modifications would be lost. modifications would be lost.
- `Weights` `(Weights: nil)` - Specifies weights for the service. Please see the - `Weights` `(Weights: nil)` - Specifies weights for the service. Please see the
[service documentation](/docs/agent/services.html) for more information about [service documentation](/docs/agent/services) for more information about
weights. If this field is not provided weights will default to weights. If this field is not provided weights will default to
`{"Passing": 1, "Warning": 1}`. `{"Passing": 1, "Warning": 1}`.
@ -566,7 +566,7 @@ service definition keys for compatibility with the config file format.
are independent of one another. Updating the tags for the service registered are independent of one another. Updating the tags for the service registered
on one node is independent of the same service (by name) registered on on one node is independent of the same service (by name) registered on
another node. If `EnableTagOverride` is not specified the default value is another node. If `EnableTagOverride` is not specified the default value is
`false`. See [anti-entropy syncs](/docs/internals/anti-entropy.html) for `false`. See [anti-entropy syncs](/docs/internals/anti-entropy) for
more info. more info.
#### Connect Structure #### Connect Structure
@ -574,17 +574,17 @@ service definition keys for compatibility with the config file format.
For the `Connect` field, the parameters are: For the `Connect` field, the parameters are:
- `Native` `(bool: false)` - Specifies whether this service supports - `Native` `(bool: false)` - Specifies whether this service supports
the [Connect](/docs/connect) protocol [natively](/docs/connect/native.html). the [Connect](/docs/connect) protocol [natively](/docs/connect/native).
If this is true, then Connect proxies, DNS queries, etc. will be able to If this is true, then Connect proxies, DNS queries, etc. will be able to
service discover this service. service discover this service.
- `Proxy` `(Proxy: nil)` - - `Proxy` `(Proxy: nil)` -
[**Deprecated**](/docs/connect/proxies/managed-deprecated.html) Specifies that [**Deprecated**](/docs/connect/proxies/managed-deprecated) Specifies that
a managed Connect proxy should be started for this service instance, and a managed Connect proxy should be started for this service instance, and
optionally provides configuration for the proxy. The format is as documented optionally provides configuration for the proxy. The format is as documented
in [Managed Proxy Deprecation](/docs/connect/proxies/managed-deprecated.html). in [Managed Proxy Deprecation](/docs/connect/proxies/managed-deprecated).
- `SidecarService` `(ServiceDefinition: nil)` - Specifies an optional nested - `SidecarService` `(ServiceDefinition: nil)` - Specifies an optional nested
service definition to register. For more information see service definition to register. For more information see
[Sidecar Service Registration](/docs/connect/registration/sidecar-service.html). [Sidecar Service Registration](/docs/connect/registration/sidecar-service).
### Sample Payload ### Sample Payload
@ -634,9 +634,9 @@ is an associated check, that is also deregistered.
| `PUT` | `/agent/service/deregister/:service_id` | `application/json` | | `PUT` | `/agent/service/deregister/:service_id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -668,9 +668,9 @@ will be automatically restored on agent restart.
| `PUT` | `/agent/service/maintenance/:service_id` | `application/json` | | `PUT` | `/agent/service/maintenance/:service_id` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

68
website/pages/api-docs/catalog.mdx
View File

@ -18,17 +18,17 @@ API methods look similar.
This endpoint is a low-level mechanism for registering or updating This endpoint is a low-level mechanism for registering or updating
entries in the catalog. It is usually preferable to instead use the entries in the catalog. It is usually preferable to instead use the
[agent endpoints](/api/agent.html) for registration as they are simpler and [agent endpoints](/api/agent) for registration as they are simpler and
perform [anti-entropy](/docs/internals/anti-entropy.html). perform [anti-entropy](/docs/internals/anti-entropy).
| Method | Path | Produces | | Method | Path | Produces |
| ------ | ------------------- | ------------------ | | ------ | ------------------- | ------------------ |
| `PUT` | `/catalog/register` | `application/json` | | `PUT` | `/catalog/register` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -56,17 +56,17 @@ The table below shows this endpoint's support for
provided, it will be defaulted to the value of the `Service.Service` property. provided, it will be defaulted to the value of the `Service.Service` property.
Only one service with a given `ID` may be present per node. We recommend using Only one service with a given `ID` may be present per node. We recommend using
[valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames)
for service definition names for [compatibility with external DNS](/docs/agent/services.html#service-and-tag-names-with-dns). for service definition names for [compatibility with external DNS](/docs/agent/services#service-and-tag-names-with-dns).
The service `Tags`, `Address`, `Meta`, and `Port` fields are all optional. For more The service `Tags`, `Address`, `Meta`, and `Port` fields are all optional. For more
information about these fields and the implications of setting them, information about these fields and the implications of setting them,
see the [Service - Agent API](/api/agent/service.html) page see the [Service - Agent API](/api/agent/service) page
as registering services differs between using this or the Services Agent endpoint. as registering services differs between using this or the Services Agent endpoint.
- `Check` `(Check: nil)` - Specifies to register a check. The register API - `Check` `(Check: nil)` - Specifies to register a check. The register API
manipulates the health check entry in the Catalog, but it does not setup the manipulates the health check entry in the Catalog, but it does not setup the
script, TTL, or HTTP check to monitor the node's health. To truly enable a new script, TTL, or HTTP check to monitor the node's health. To truly enable a new
health check, the check must either be provided in agent configuration or set health check, the check must either be provided in agent configuration or set
via the [agent endpoint](agent.html). via the [agent endpoint](agent).
The `CheckID` can be omitted and will default to the value of `Name`. As The `CheckID` can be omitted and will default to the value of `Name`. As
with `Service.ID`, the `CheckID` must be unique on this node. `Notes` is an with `Service.ID`, the `CheckID` must be unique on this node. `Notes` is an
@ -76,7 +76,7 @@ The table below shows this endpoint's support for
check. The `Status` must be one of `passing`, `warning`, or `critical`. check. The `Status` must be one of `passing`, `warning`, or `critical`.
The `Definition` field can be provided with details for a TCP or HTTP health The `Definition` field can be provided with details for a TCP or HTTP health
check. For more information, see the [Health Checks](/docs/agent/checks.html) page. check. For more information, see the [Health Checks](/docs/agent/checks) page.
Multiple checks can be provided by replacing `Check` with `Checks` and Multiple checks can be provided by replacing `Check` with `Checks` and
sending an array of `Check` objects. sending an array of `Check` objects.
@ -169,17 +169,17 @@ $ curl \
This endpoint is a low-level mechanism for directly removing This endpoint is a low-level mechanism for directly removing
entries from the Catalog. It is usually preferable to instead use the entries from the Catalog. It is usually preferable to instead use the
[agent endpoints](/api/agent.html) for deregistration as they are simpler and [agent endpoints](/api/agent) for deregistration as they are simpler and
perform [anti-entropy](/docs/internals/anti-entropy.html). perform [anti-entropy](/docs/internals/anti-entropy).
| Method | Path | Produces | | Method | Path | Produces |
| ------ | --------------------- | ------------------ | | ------ | --------------------- | ------------------ |
| `PUT` | `/catalog/deregister` | `application/json` | | `PUT` | `/catalog/deregister` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -259,9 +259,9 @@ Consul servers are routable.
| `GET` | `/catalog/datacenters` | `application/json` | | `GET` | `/catalog/datacenters` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -290,9 +290,9 @@ This endpoint and returns the nodes registered in a given datacenter.
| `GET` | `/catalog/nodes` | `application/json` | | `GET` | `/catalog/nodes` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -383,9 +383,9 @@ This endpoint returns the services registered in a given datacenter.
| `GET` | `/catalog/services` | `application/json` | | `GET` | `/catalog/services` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -437,9 +437,9 @@ This endpoint returns the nodes providing a service in a given datacenter.
| `GET` | `/catalog/service/:service` | `application/json` | | `GET` | `/catalog/service/:service` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -579,7 +579,7 @@ $ curl \
registration API for more information. registration API for more information.
- `ServiceProxy` is the proxy config as specified in - `ServiceProxy` is the proxy config as specified in
[Connect Proxies](/docs/connect/proxies.html). [Connect Proxies](/docs/connect/proxies).
- `ServiceConnect` are the [Connect](/docs/connect) settings. The - `ServiceConnect` are the [Connect](/docs/connect) settings. The
value of this struct is equivalent to the `Connect` field for service value of this struct is equivalent to the `Connect` field for service
@ -644,7 +644,7 @@ so this endpoint may be used to filter only the Connect-capable endpoints.
| `GET` | `/catalog/connect/:service` | `application/json` | | `GET` | `/catalog/connect/:service` | `application/json` |
Parameters and response format are the same as Parameters and response format are the same as
[`/catalog/service/:service`](/api/catalog.html#list-nodes-for-service). [`/catalog/service/:service`](/api/catalog#list-nodes-for-service).
## Retrieve Map of Services for a Node ## Retrieve Map of Services for a Node
@ -655,9 +655,9 @@ This endpoint returns the node's registered services.
| `GET` | `/catalog/node/:node` | `application/json` | | `GET` | `/catalog/node/:node` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -782,9 +782,9 @@ This endpoint returns the node's registered services.
| `GET` | `/catalog/node-services/:node` | `application/json` | | `GET` | `/catalog/node-services/:node` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

28
website/pages/api-docs/config.mdx
View File

@ -12,9 +12,9 @@ description: |-
The `/config` endpoints create, update, delete and query central configuration The `/config` endpoints create, update, delete and query central configuration
entries registered with Consul. See the entries registered with Consul. See the
[agent configuration](/docs/agent/options.html#enable_central_service_config) [agent configuration](/docs/agent/options#enable_central_service_config)
for more information on how to enable this functionality for centrally for more information on how to enable this functionality for centrally
configuring services and [configuration entries docs](/docs/agent/config_entries.html) for a description configuring services and [configuration entries docs](/docs/agent/config_entries) for a description
of the configuration entries content. of the configuration entries content.
## Apply Configuration ## Apply Configuration
@ -26,9 +26,9 @@ This endpoint creates or updates the given config entry.
| `PUT` | `/config` | `application/json` | | `PUT` | `/config` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -89,9 +89,9 @@ This endpoint returns a specific config entry.
| `GET` | `/config/:kind/:name` | `application/json` | | `GET` | `/config/:kind/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -151,9 +151,9 @@ This endpoint returns all config entries of the given kind.
| `GET` | `/config/:kind` | `application/json` | | `GET` | `/config/:kind` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -219,9 +219,9 @@ This endpoint deletes the given config entry.
| `DELETE` | `/config/:kind/:name` | `application/json` | | `DELETE` | `/config/:kind/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

24
website/pages/api-docs/connect/ca.mdx
View File

@ -23,9 +23,9 @@ the cluster.
| `GET` | `/connect/ca/roots` | `application/json` | | `GET` | `/connect/ca/roots` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -75,9 +75,9 @@ This endpoint returns the current CA configuration.
| `GET` | `/connect/ca/configuration` | `application/json` | | `GET` | `/connect/ca/configuration` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -109,16 +109,16 @@ $ curl \
## Update CA Configuration ## Update CA Configuration
This endpoint updates the configuration for the CA. If this results in a This endpoint updates the configuration for the CA. If this results in a
new root certificate being used, the [Root Rotation](/docs/connect/ca.html#root-certificate-rotation) process will be triggered. new root certificate being used, the [Root Rotation](/docs/connect/ca#root-certificate-rotation) process will be triggered.
| Method | Path | Produces | | Method | Path | Produces |
| ------ | --------------------------- | ------------------ | | ------ | --------------------------- | ------------------ |
| `PUT` | `/connect/ca/configuration` | `application/json` | | `PUT` | `/connect/ca/configuration` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -131,13 +131,13 @@ The table below shows this endpoint's support for
- `Config` `(map[string]string: <required>)` - The raw configuration to use - `Config` `(map[string]string: <required>)` - The raw configuration to use
for the chosen provider. For more information on configuring the Connect CA for the chosen provider. For more information on configuring the Connect CA
providers, see [Provider Config](/docs/connect/ca.html). providers, see [Provider Config](/docs/connect/ca).
- `ForceWithoutCrossSigning` `(bool: <optional>)` - Indicates that the CA change - `ForceWithoutCrossSigning` `(bool: <optional>)` - Indicates that the CA change
should be force to complete even if the current CA doesn't support cross should be force to complete even if the current CA doesn't support cross
signing. Changing root without cross-signing may cause temporary connection signing. Changing root without cross-signing may cause temporary connection
failures until the rollout completes. See [Forced Rotation Without failures until the rollout completes. See [Forced Rotation Without
Cross-Signing](/docs/connect/ca.html#forced-rotation-without-cross-signing) Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
for more detail. for more detail.
### Sample Payload ### Sample Payload

2
website/pages/api-docs/connect/index.mdx
View File

@ -15,7 +15,7 @@ The `/connect` endpoints provide access to
intentions and the certificate authority. intentions and the certificate authority.
There are also Connect-related endpoints in the There are also Connect-related endpoints in the
[Agent](/api/agent.html) and [Catalog](/api/catalog.html) APIs. For example, [Agent](/api/agent) and [Catalog](/api/catalog) APIs. For example,
the API for requesting a TLS certificate for a service is part of the agent the API for requesting a TLS certificate for a service is part of the agent
APIs. And the catalog API has an endpoint for finding all Connect-capable APIs. And the catalog API has an endpoint for finding all Connect-capable
services in the catalog. services in the catalog.

58
website/pages/api-docs/connect/intentions.mdx
View File

@ -11,7 +11,7 @@ description: |-
# Intentions - Connect HTTP API # Intentions - Connect HTTP API
The `/connect/intentions` endpoint provide tools for managing The `/connect/intentions` endpoint provide tools for managing
[intentions](/docs/connect/intentions.html). [intentions](/docs/connect/intentions).
## Create Intention ## Create Intention
@ -27,9 +27,9 @@ existing intention or delete it prior to creating a new one.
| `POST` | `/connect/intentions` | `application/json` | | `POST` | `/connect/intentions` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -39,7 +39,7 @@ The table below shows this endpoint's support for
<p> <p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule. <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '} See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions"> <a href="/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions Intention Management Permissions
</a>{' '} </a>{' '}
for more details. for more details.
@ -104,9 +104,9 @@ This endpoint reads a specific intention.
| `GET` | `/connect/intentions/:uuid` | `application/json` | | `GET` | `/connect/intentions/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -116,7 +116,7 @@ The table below shows this endpoint's support for
<p> <p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule. <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '} See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions"> <a href="/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions Intention Management Permissions
</a>{' '} </a>{' '}
for more details. for more details.
@ -166,9 +166,9 @@ This endpoint lists all intentions.
| `GET` | `/connect/intentions` | `application/json` | | `GET` | `/connect/intentions` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -178,7 +178,7 @@ The table below shows this endpoint's support for
<p> <p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule. <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '} See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions"> <a href="/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions Intention Management Permissions
</a>{' '} </a>{' '}
for more details. for more details.
@ -251,9 +251,9 @@ This endpoint updates an intention with the given values.
| `PUT` | `/connect/intentions/:uuid` | `application/json` | | `PUT` | `/connect/intentions/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -263,7 +263,7 @@ The table below shows this endpoint's support for
<p> <p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule. <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '} See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions"> <a href="/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions Intention Management Permissions
</a>{' '} </a>{' '}
for more details. for more details.
@ -305,9 +305,9 @@ This endpoint deletes a specific intention.
| `DELETE` | `/connect/intentions/:uuid` | `application/json` | | `DELETE` | `/connect/intentions/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -317,7 +317,7 @@ The table below shows this endpoint's support for
<p> <p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule. <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '} See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions"> <a href="/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions Intention Management Permissions
</a>{' '} </a>{' '}
for more details. for more details.
@ -351,9 +351,9 @@ does not contain any information about the intention itself.
| `GET` | `/connect/intentions/check` | `application/json` | | `GET` | `/connect/intentions/check` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -363,7 +363,7 @@ The table below shows this endpoint's support for
<p> <p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule. <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '} See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions"> <a href="/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions Intention Management Permissions
</a>{' '} </a>{' '}
for more details. for more details.
@ -404,9 +404,9 @@ The intentions in the response are in evaluation order.
| `GET` | `/connect/intentions/match` | `application/json` | | `GET` | `/connect/intentions/match` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -416,7 +416,7 @@ The table below shows this endpoint's support for
<p> <p>
<sup>1</sup> Intention ACL rules are specified as part of a `service` rule. <sup>1</sup> Intention ACL rules are specified as part of a `service` rule.
See{' '} See{' '}
<a href="/docs/connect/intentions.html#intention-management-permissions"> <a href="/docs/connect/intentions#intention-management-permissions">
Intention Management Permissions Intention Management Permissions
</a>{' '} </a>{' '}
for more details. for more details.

26
website/pages/api-docs/coordinate.mdx
View File

@ -15,7 +15,7 @@ The `/coordinate` endpoints query for the network coordinates for nodes in the
local datacenter as well as Consul servers in the local datacenter and remote local datacenter as well as Consul servers in the local datacenter and remote
datacenters. datacenters.
Please see the [Network Coordinates](/docs/internals/coordinates.html) internals Please see the [Network Coordinates](/docs/internals/coordinates) internals
guide for more information on how these coordinates are computed, and for guide for more information on how these coordinates are computed, and for
details on how to perform calculations with them. details on how to perform calculations with them.
@ -31,9 +31,9 @@ cluster.
| `GET` | `/coordinate/datacenters` | `application/json` | | `GET` | `/coordinate/datacenters` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -83,9 +83,9 @@ datacenter.
| `GET` | `/coordinate/nodes` | `application/json` | | `GET` | `/coordinate/nodes` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -140,9 +140,9 @@ This endpoint returns the LAN network coordinates for the given node.
| `GET` | `/coordinate/node/:node` | `application/json` | | `GET` | `/coordinate/node/:node` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -198,9 +198,9 @@ datacenter.
| `PUT` | `/coordinate/update` | `application/json` | | `PUT` | `/coordinate/update` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

44
website/pages/api-docs/discovery-chain.mdx
View File

@ -11,17 +11,17 @@ description: The /discovery-chain endpoints are for interacting with the discove
# Discovery Chain HTTP Endpoint # Discovery Chain HTTP Endpoint
~> This is a low-level API primarily targeted at developers building external ~> This is a low-level API primarily targeted at developers building external
[Connect proxy integrations](/docs/connect/proxies/integrate.html). Future [Connect proxy integrations](/docs/connect/proxies/integrate). Future
high-level proxy integration APIs may obviate the need for this API over time. high-level proxy integration APIs may obviate the need for this API over time.
The `/discovery-chain` endpoint returns the compiled [discovery The `/discovery-chain` endpoint returns the compiled [discovery
chain](/docs/internals/discovery-chain.html) for a service. chain](/docs/internals/discovery-chain) for a service.
This will fetch all related [configuration This will fetch all related [configuration
entries](/docs/agent/config_entries.html) and render them into a form suitable entries](/docs/agent/config_entries) and render them into a form suitable
for use by a [connect proxy](/docs/connect/proxies.html) implementation. This for use by a [connect proxy](/docs/connect/proxies) implementation. This
is a key component of [L7 Traffic is a key component of [L7 Traffic
Management](/docs/connect/l7-traffic-management.html). Management](/docs/connect/l7-traffic-management).
## Read Compiled Discovery Chain ## Read Compiled Discovery Chain
@ -40,9 +40,9 @@ the `POST` method must be used, otherwise `GET` is sufficient.
</p> </p>
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -59,24 +59,24 @@ The table below shows this endpoint's support for
This is specified as part of the URL as a query parameter. This is specified as part of the URL as a query parameter.
This value comes from an [upstream This value comes from an [upstream
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference) configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
[`datacenter`](/docs/connect/registration/service-registration.html#datacenter) [`datacenter`](/docs/connect/registration/service-registration#datacenter)
parameter. parameter.
### POST Body Parameters ### POST Body Parameters
- `OverrideConnectTimeout` `(duration: 0s)` - Overrides the final [connect - `OverrideConnectTimeout` `(duration: 0s)` - Overrides the final [connect
timeout](/docs/agent/config-entries/service-resolver.html#connecttimeout) for timeout](/docs/agent/config-entries/service-resolver#connecttimeout) for
any service resolved in the compiled chain. any service resolved in the compiled chain.
This value comes from the `connect_timeout_ms` key in an [upstream This value comes from the `connect_timeout_ms` key in an [upstream
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference) configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
opaque opaque
[`config`](/docs/connect/registration/service-registration.html#config-1) [`config`](/docs/connect/registration/service-registration#config-1)
parameter. parameter.
- `OverrideProtocol` `(string: "")` - Overrides the final - `OverrideProtocol` `(string: "")` - Overrides the final
[protocol](/docs/agent/config-entries/service-defaults.html#protocol) used in [protocol](/docs/agent/config-entries/service-defaults#protocol) used in
the compiled discovery chain. the compiled discovery chain.
If the chain ordinarily would be TCP and an L7 protocol is passed here the If the chain ordinarily would be TCP and an L7 protocol is passed here the
@ -85,21 +85,21 @@ The table below shows this endpoint's support for
Splitters. Splitters.
This value comes from the `protocol` key in an [upstream This value comes from the `protocol` key in an [upstream
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference) configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
opaque opaque
[`config`](/docs/connect/registration/service-registration.html#config-1) [`config`](/docs/connect/registration/service-registration#config-1)
parameter. parameter.
- `OverrideMeshGateway` `(MeshGatewayConfig: <optional>)` - Overrides the final - `OverrideMeshGateway` `(MeshGatewayConfig: <optional>)` - Overrides the final
[mesh gateway configuration](/docs/connect/mesh_gateway.html#connect-proxy-configuration) [mesh gateway configuration](/docs/connect/mesh_gateway#connect-proxy-configuration)
for this any service resolved in the compiled chain. for this any service resolved in the compiled chain.
This value comes from either the [proxy This value comes from either the [proxy
configuration](/docs/connect/registration/service-registration.html#complete-configuration-example) configuration](/docs/connect/registration/service-registration#complete-configuration-example)
[`mesh_gateway`](/docs/connect/registration/service-registration.html#mesh_gateway) [`mesh_gateway`](/docs/connect/registration/service-registration#mesh_gateway)
parameter or an [upstream parameter or an [upstream
configuration](/docs/connect/registration/service-registration.html#upstream-configuration-reference) configuration](/docs/connect/registration/service-registration#upstream-configuration-reference)
[`mesh_gateway`](/docs/connect/registration/service-registration.html#mesh_gateway-1) [`mesh_gateway`](/docs/connect/registration/service-registration#mesh_gateway-1)
parameter. If both are present the value defined on the upstream is used. parameter. If both are present the value defined on the upstream is used.
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`. - `Mode` `(string: "")` - One of `none`, `local`, or `remote`.
@ -107,7 +107,7 @@ The table below shows this endpoint's support for
### Sample Compilations ### Sample Compilations
Full documentation for the output fields is found on the [discovery chain Full documentation for the output fields is found on the [discovery chain
internals](/docs/internals/discovery-chain.html#compileddiscoverychain) internals](/docs/internals/discovery-chain#compileddiscoverychain)
page. page.
#### Multi-Datacenter Failover #### Multi-Datacenter Failover

18
website/pages/api-docs/event.mdx
View File

@ -22,9 +22,9 @@ This endpoint triggers a new user event.
| `PUT` | `/event/fire/:name` | `application/json` | | `PUT` | `/event/fire/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -88,9 +88,9 @@ $ curl \
## List Events ## List Events
This endpoint returns the most recent events (up to 256) known by the agent. As a This endpoint returns the most recent events (up to 256) known by the agent. As a
consequence of how the [event command](/docs/commands/event.html) works, each consequence of how the [event command](/docs/commands/event) works, each
agent may have a different view of the events. Events are broadcast using the agent may have a different view of the events. Events are broadcast using the
[gossip protocol](/docs/internals/gossip.html), so they have no global ordering [gossip protocol](/docs/internals/gossip), so they have no global ordering
nor do they make a promise of delivery. nor do they make a promise of delivery.
| Method | Path | Produces | | Method | Path | Produces |
@ -98,9 +98,9 @@ nor do they make a promise of delivery.
| `GET` | `/event/list` | `application/json` | | `GET` | `/event/list` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -150,7 +150,7 @@ $ curl \
The semantics of this endpoint's blocking queries are slightly different. Most The semantics of this endpoint's blocking queries are slightly different. Most
blocking queries provide a monotonic index and block until a newer index is blocking queries provide a monotonic index and block until a newer index is
available. This can be supported as a consequence of the total ordering of the available. This can be supported as a consequence of the total ordering of the
[consensus protocol](/docs/internals/consensus.html). With gossip, there is no [consensus protocol](/docs/internals/consensus). With gossip, there is no
ordering, and instead `X-Consul-Index` maps to the newest event that matches the ordering, and instead `X-Consul-Index` maps to the newest event that matches the
query. query.

2
website/pages/api-docs/features/consistency.mdx
View File

@ -44,7 +44,7 @@ should be provided on requests. It is an error to provide both.
Note that some endpoints support a `cached` parameter which has some of the same Note that some endpoints support a `cached` parameter which has some of the same
semantics as `stale` but different trade offs. This behavior is described in semantics as `stale` but different trade offs. This behavior is described in
[agent caching feature documentation](/api/features/caching.html). [agent caching feature documentation](/api/features/caching).
To support bounding the acceptable staleness of data, responses provide the To support bounding the acceptable staleness of data, responses provide the
`X-Consul-LastContact` header containing the time in milliseconds that a server `X-Consul-LastContact` header containing the time in milliseconds that a server

2
website/pages/api-docs/features/filtering.mdx
View File

@ -120,7 +120,7 @@ will not be expanded.
Generally, only the main object is filtered. When filtering for Generally, only the main object is filtered. When filtering for
an item within an array that is not at the top level, the entire array that contains the item an item within an array that is not at the top level, the entire array that contains the item
will be returned. This is usually the outermost object of a response, will be returned. This is usually the outermost object of a response,
but in some cases such the [`/catalog/node/:node`](/api/catalog.html#list-services-for-node) but in some cases such the [`/catalog/node/:node`](/api/catalog#list-services-for-node)
endpoint the filtering is performed on a object embedded within the results. endpoint the filtering is performed on a object embedded within the results.
### Performance ### Performance

26
website/pages/api-docs/health.mdx
View File

@ -25,9 +25,9 @@ This endpoint returns the checks specific to the node provided on the path.
| `GET` | `/health/node/:node` | `application/json` | | `GET` | `/health/node/:node` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -120,9 +120,9 @@ path.
| `GET` | `/health/checks/:service` | `application/json` | | `GET` | `/health/checks/:service` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -210,9 +210,9 @@ incorporating the use of health checks.
| `GET` | `/health/service/:service` | `application/json` | | `GET` | `/health/service/:service` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -402,7 +402,7 @@ so this endpoint may be used to filter only the Connect-capable endpoints.
| `GET` | `/health/connect/:service` | `application/json` | | `GET` | `/health/connect/:service` | `application/json` |
Parameters and response format are the same as Parameters and response format are the same as
[`/health/service/:service`](/api/health.html#list-nodes-for-service). [`/health/service/:service`](/api/health#list-nodes-for-service).
## List Checks in State ## List Checks in State
@ -413,9 +413,9 @@ This endpoint returns the checks in the state provided on the path.
| `GET` | `/health/state/:state` | `application/json` | | `GET` | `/health/state/:state` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

4
website/pages/api-docs/index.mdx
View File

@ -42,7 +42,7 @@ Previously this was provided via a `?token=` query parameter. This functionality
exists on many endpoints for backwards compatibility, but its use is **highly exists on many endpoints for backwards compatibility, but its use is **highly
discouraged**, since it can show up in access logs as part of the URL. discouraged**, since it can show up in access logs as part of the URL.
To learn more about the ACL system read the [documentation](/docs/acl/acl-system.html). To learn more about the ACL system read the [documentation](/docs/acl/acl-system).
## Version Prefix ## Version Prefix
@ -81,7 +81,7 @@ $ curl \
Consul 0.7 added the ability to translate addresses in HTTP response based on Consul 0.7 added the ability to translate addresses in HTTP response based on
the configuration setting for the configuration setting for
[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs). In order [`translate_wan_addrs`](/docs/agent/options#translate_wan_addrs). In order
to allow clients to know if address translation is in effect, the to allow clients to know if address translation is in effect, the
`X-Consul-Translate-Addresses` header will be added if translation is enabled, `X-Consul-Translate-Addresses` header will be added if translation is enabled,
and will have a value of `true`. If translation is not enabled then this header and will have a value of `true`. If translation is not enabled then this header

22
website/pages/api-docs/kv.mdx
View File

@ -20,23 +20,23 @@ replication between datacenters, please view the
~> Values in the KV store cannot be larger than 512kb. ~> Values in the KV store cannot be larger than 512kb.
For multi-key updates, please consider using [transaction](/api/txn.html). For multi-key updates, please consider using [transaction](/api/txn).
## Read Key ## Read Key
This endpoint returns the specified key. If no key exists at the given path, a This endpoint returns the specified key. If no key exists at the given path, a
404 is returned instead of a 200 response. 404 is returned instead of a 200 response.
For multi-key reads, please consider using [transaction](/api/txn.html). For multi-key reads, please consider using [transaction](/api/txn).
| Method | Path | Produces | | Method | Path | Produces |
| ------ | ---------- | ------------------ | | ------ | ---------- | ------------------ |
| `GET` | `/kv/:key` | `application/json` | | `GET` | `/kv/:key` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -160,9 +160,9 @@ Even though the return type is `application/json`, the value is either `true` or
`false`, indicating whether the create/update succeeded. `false`, indicating whether the create/update succeeded.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -245,9 +245,9 @@ This endpoint deletes a single key or all keys sharing a prefix.
| `DELETE` | `/kv/:key` | `application/json` | | `DELETE` | `/kv/:key` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

30
website/pages/api-docs/namespaces.mdx
View File

@ -23,9 +23,9 @@ This endpoint creates a new ACL token.
| `PUT` | `/namespace` | `application/json` | | `PUT` | `/namespace` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -148,9 +148,9 @@ This endpoint reads a Namespace with the given name.
| `GET` | `/namespace/:name` | `application/json` | | `GET` | `/namespace/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -217,9 +217,9 @@ This endpoint updates a new ACL token.
| `PUT` | `/namespace/:name` | `application/json` | | `PUT` | `/namespace/:name` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -350,9 +350,9 @@ This endpoint will return no data. Success or failure is indicated by the status
code returned. code returned.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -419,9 +419,9 @@ privileges of the ACL token used for the request.
| `GET` | `/namespaces` | `application/json` | | `GET` | `/namespaces` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

46
website/pages/api-docs/operator/area.mdx
View File

@ -39,9 +39,9 @@ successfully.
| `POST` | `/operator/area` | `application/json` | | `POST` | `/operator/area` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -105,9 +105,9 @@ This endpoint lists all network areas.
| `GET` | `/operator/area` | `application/json` | | `GET` | `/operator/area` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -148,9 +148,9 @@ This endpoint updates a network area to the given configuration.
| `PUT` | `/operator/area/:uuid` | `application/json` | | `PUT` | `/operator/area/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -192,9 +192,9 @@ This endpoint lists a specific network area.
| `GET` | `/operator/area/:uuid` | `application/json` | | `GET` | `/operator/area/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -238,9 +238,9 @@ This endpoint deletes a specific network area.
| `DELETE` | `/operator/area/:uuid` | `application/json` | | `DELETE` | `/operator/area/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -274,9 +274,9 @@ area.
| `PUT` | `/operator/area/:uuid/join` | `application/json` | | `PUT` | `/operator/area/:uuid/join` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -347,9 +347,9 @@ network area.
| `GET` | `/operator/area/:uuid/members` | `application/json` | | `GET` | `/operator/area/:uuid/members` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -406,7 +406,7 @@ $ curl \
- `Build` has the Consul version running on the node. - `Build` has the Consul version running on the node.
- `Protocol` is the [protocol version](/docs/upgrading.html#protocol-versions) - `Protocol` is the [protocol version](/docs/upgrading#protocol-versions)
being spoken by the node. being spoken by the node.
- `Status` is the current health status of the node, as determined by the - `Status` is the current health status of the node, as determined by the
@ -416,4 +416,4 @@ $ curl \
- `RTT` is an estimated network round trip time from the server answering the - `RTT` is an estimated network round trip time from the server answering the
query to the given server, in nanoseconds. This is computed using [network query to the given server, in nanoseconds. This is computed using [network
coordinates](/docs/internals/coordinates.html). coordinates](/docs/internals/coordinates).

20
website/pages/api-docs/operator/autopilot.mdx
View File

@ -26,9 +26,9 @@ This endpoint retrieves its latest Autopilot configuration.
| `GET` | `/operator/autopilot/configuration` | `application/json` | | `GET` | `/operator/autopilot/configuration` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -69,7 +69,7 @@ $ curl \
``` ```
For more information about the Autopilot configuration options, see the For more information about the Autopilot configuration options, see the
[agent configuration section](/docs/agent/options.html#autopilot). [agent configuration section](/docs/agent/options#autopilot).
## Update Configuration ## Update Configuration
@ -80,9 +80,9 @@ This endpoint updates the Autopilot configuration of the cluster.
| `PUT` | `/operator/autopilot/configuration` | `application/json` | | `PUT` | `/operator/autopilot/configuration` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -157,9 +157,9 @@ This endpoint queries the health of the autopilot status.
| `GET` | `/operator/autopilot/health` | `application/json` | | `GET` | `/operator/autopilot/health` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

4
website/pages/api-docs/operator/index.mdx
View File

@ -13,10 +13,10 @@ description: |-
The `/operator` endpoints provide cluster-level tools for Consul operators, The `/operator` endpoints provide cluster-level tools for Consul operators,
such as interacting with the Raft subsystem. For a CLI to perform these such as interacting with the Raft subsystem. For a CLI to perform these
operations manually, please see the documentation for the operations manually, please see the documentation for the
[`consul operator`](/docs/commands/operator.html) command. [`consul operator`](/docs/commands/operator) command.
If ACLs are enabled then a token with operator privileges may be required in If ACLs are enabled then a token with operator privileges may be required in
order to use this interface. See the [ACL Rules documentation](/docs/acl/acl-rules.html#operator-rules) order to use this interface. See the [ACL Rules documentation](/docs/acl/acl-rules#operator-rules)
for more information. for more information.
See the [Outage Recovery](https://learn.hashicorp.com/consul/day-2-operations/outage) guide for some examples of See the [Outage Recovery](https://learn.hashicorp.com/consul/day-2-operations/outage) guide for some examples of

26
website/pages/api-docs/operator/keyring.mdx
View File

@ -11,7 +11,7 @@ description: |-
# Keyring Operator HTTP API # Keyring Operator HTTP API
The `/operator/keyring` endpoints allow for management of the gossip encryption The `/operator/keyring` endpoints allow for management of the gossip encryption
keyring. Please see the [Gossip Protocol Guide](/docs/internals/gossip.html) for keyring. Please see the [Gossip Protocol Guide](/docs/internals/gossip) for
more details on the gossip protocol and its use. more details on the gossip protocol and its use.
## List Gossip Encryption Keys ## List Gossip Encryption Keys
@ -28,9 +28,9 @@ read privileges.
| `GET` | `/operator/keyring` | `application/json` | | `GET` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -104,9 +104,9 @@ This endpoint installs a new gossip encryption key into the cluster.
| `POST` | `/operator/keyring` | `application/json` | | `POST` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -150,9 +150,9 @@ installed before this operation can succeed.
| `PUT` | `/operator/keyring` | `application/json` | | `PUT` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -196,9 +196,9 @@ may only be performed on keys which are not currently the primary key.
| `DELETE` | `/operator/keyring` | `application/json` | | `DELETE` | `/operator/keyring` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

18
website/pages/api-docs/operator/license.mdx
View File

@ -25,9 +25,9 @@ This endpoint gets information about the current license.
| `GET` | `/operator/license` | `application/json` | | `GET` | `/operator/license` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -87,9 +87,9 @@ license contents as well as any warning messages regarding its validity.
| `PUT` | `/operator/license` | `application/json` | | `PUT` | `/operator/license` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -154,9 +154,9 @@ This endpoint resets the Consul license to the license included in the Enterpris
| `DELETE` | `/operator/license` | `application/json` | | `DELETE` | `/operator/license` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

16
website/pages/api-docs/operator/raft.mdx
View File

@ -13,7 +13,7 @@ description: |-
The `/operator/raft` endpoints provide tools for management of Raft the The `/operator/raft` endpoints provide tools for management of Raft the
consensus subsystem and cluster quorum. consensus subsystem and cluster quorum.
Please see the [Consensus Protocol Guide](/docs/internals/consensus.html) for Please see the [Consensus Protocol Guide](/docs/internals/consensus) for
more information about Raft consensus protocol and its use. more information about Raft consensus protocol and its use.
## Read Configuration ## Read Configuration
@ -25,9 +25,9 @@ This endpoint reads the current raft configuration.
| `GET` | `/operator/raft/configuration` | `application/json` | | `GET` | `/operator/raft/configuration` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -45,7 +45,7 @@ The table below shows this endpoint's support for
Raft configuration from any of the Consul servers. Not setting this will choose Raft configuration from any of the Consul servers. Not setting this will choose
the default consistency mode which will forward the request to the leader for the default consistency mode which will forward the request to the leader for
processing but not re-confirm the server is still the leader before returning processing but not re-confirm the server is still the leader before returning
results. See [default consistency](/api/features/consistency.html#default) for more details. results. See [default consistency](/api/features/consistency#default) for more details.
### Sample Request ### Sample Request
@ -123,9 +123,9 @@ write privileges.
| `DELETE` | `/operator/raft/peer` | `application/json` | | `DELETE` | `/operator/raft/peer` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

6
website/pages/api-docs/operator/segment.mdx
View File

@ -32,9 +32,9 @@ This endpoint lists all network areas.
| `GET` | `/operator/segment` | `application/json` | | `GET` | `/operator/segment` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

50
website/pages/api-docs/query.mdx
View File

@ -13,13 +13,13 @@ The `/query` endpoints create, update, destroy, and execute prepared queries.
Prepared queries allow you to register a complex service query and then execute Prepared queries allow you to register a complex service query and then execute
it later via its ID or name to get a set of healthy nodes that provide a given it later via its ID or name to get a set of healthy nodes that provide a given
service. This is particularly useful in combination with Consul's service. This is particularly useful in combination with Consul's
[DNS Interface](/docs/agent/dns.html) as it allows for much richer queries than [DNS Interface](/docs/agent/dns) as it allows for much richer queries than
would be possible given the limited entry points exposed by DNS. would be possible given the limited entry points exposed by DNS.
See the [Geo Failover Guide](https://learn.hashicorp.com/consul/developer-discovery/geo-failover) for details and See the [Geo Failover Guide](https://learn.hashicorp.com/consul/developer-discovery/geo-failover) for details and
examples for using prepared queries to implement geo failover for services. examples for using prepared queries to implement geo failover for services.
See the [prepared query rules](/docs/agent/acl-rules.html#prepared-query-rules) See the [prepared query rules](/docs/agent/acl-rules#prepared-query-rules)
section of the agent ACL documentation for more details about how prepared section of the agent ACL documentation for more details about how prepared
queries work with Consul's ACL system. queries work with Consul's ACL system.
@ -143,9 +143,9 @@ successfully.
| `POST` | `/query` | `application/json` | | `POST` | `/query` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -186,7 +186,7 @@ The table below shows this endpoint's support for
- `NearestN` `(int: 0)` - Specifies that the query will be forwarded to up - `NearestN` `(int: 0)` - Specifies that the query will be forwarded to up
to `NearestN` other datacenters based on their estimated network round to `NearestN` other datacenters based on their estimated network round
trip time using [Network Coordinates](/docs/internals/coordinates.html) trip time using [Network Coordinates](/docs/internals/coordinates)
from the WAN gossip pool. The median round trip time from the server from the WAN gossip pool. The median round trip time from the server
handling the query to the servers in the remote datacenter is used to handling the query to the servers in the remote datacenter is used to
determine the priority. determine the priority.
@ -213,7 +213,7 @@ The table below shows this endpoint's support for
true, only nodes with checks in the passing state will be returned. true, only nodes with checks in the passing state will be returned.
- `Near` `(string: "")` - Specifies a node to sort near based on distance - `Near` `(string: "")` - Specifies a node to sort near based on distance
sorting using [Network Coordinates](/docs/internals/coordinates.html). The sorting using [Network Coordinates](/docs/internals/coordinates). The
nearest instance to the specified node will be returned first, and subsequent nearest instance to the specified node will be returned first, and subsequent
nodes in the response will be sorted in ascending order of estimated nodes in the response will be sorted in ascending order of estimated
round-trip times. If the node given does not exist, the nodes in the response round-trip times. If the node given does not exist, the nodes in the response
@ -303,9 +303,9 @@ This endpoint returns a list of all prepared queries.
| `GET` | `/query` | `application/json` | | `GET` | `/query` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -366,9 +366,9 @@ given ID, an error is returned.
| `PUT` | `/query/:uuid` | `application/json` | | `PUT` | `/query/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -406,9 +406,9 @@ given ID, an error is returned.
| `GET` | `/query/:uuid` | `application/json` | | `GET` | `/query/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -446,9 +446,9 @@ given ID, an error is returned.
| `DELETE` | `/query/:uuid` | `application/json` | | `DELETE` | `/query/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -482,9 +482,9 @@ given ID, an error is returned.
| `GET` | `/query/:uuid/execute` | `application/json` | | `GET` | `/query/:uuid/execute` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -611,9 +611,9 @@ interpolation.
| `GET` | `/query/:uuid/explain` | `application/json` | | `GET` | `/query/:uuid/explain` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

36
website/pages/api-docs/session.mdx
View File

@ -20,9 +20,9 @@ node and may be associated with any number of checks.
| `PUT` | `/session/create` | `application/json` | | `PUT` | `/session/create` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -113,9 +113,9 @@ either a literal `true` or `false`, indicating of whether the destroy was
successful. successful.
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -159,9 +159,9 @@ This endpoint returns the requested session information.
| `GET` | `/session/info/:uuid` | `application/json` | | `GET` | `/session/info/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -218,9 +218,9 @@ This endpoint returns the active sessions for a given node.
| `GET` | `/session/node/:node` | `application/json` | | `GET` | `/session/node/:node` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -277,9 +277,9 @@ This endpoint returns the list of active sessions.
| `GET` | `/session/list` | `application/json` | | `GET` | `/session/list` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -333,9 +333,9 @@ TTL, and it extends the expiration by the TTL.
| `PUT` | `/session/renew/:uuid` | `application/json` | | `PUT` | `/session/renew/:uuid` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

14
website/pages/api-docs/snapshot.mdx
View File

@ -12,7 +12,7 @@ description: |-
The `/snapshot` endpoints save and restore the state of the Consul The `/snapshot` endpoints save and restore the state of the Consul
servers for disaster recovery. Snapshots include all state managed by Consul's servers for disaster recovery. Snapshots include all state managed by Consul's
Raft [consensus protocol](/docs/internals/consensus.html). Raft [consensus protocol](/docs/internals/consensus).
## Generate Snapshot ## Generate Snapshot
@ -32,9 +32,9 @@ restore.
| `GET` | `/snapshot` | `200 application/x-gzip` | | `GET` | `/snapshot` | `200 application/x-gzip` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -87,9 +87,9 @@ call to the `GET` method.
| `PUT` | `/snapshot` | `200 text/plain (empty body)` | | `PUT` | `/snapshot` | `200 text/plain (empty body)` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

12
website/pages/api-docs/status.mdx
View File

@ -25,9 +25,9 @@ running.
| `GET` | `/status/leader` | `application/json` | | `GET` | `/status/leader` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -63,9 +63,9 @@ determining when a given server has successfully joined the cluster.
| `GET` | `/status/peers` | `application/json` | | `GET` | `/status/peers` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |

12
website/pages/api-docs/txn.mdx
View File

@ -38,9 +38,9 @@ the leader via the Raft consensus protocol.
| `PUT` | `/txn` | `application/json` | | `PUT` | `/txn` | `application/json` |
The table below shows this endpoint's support for The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html), [blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency.html), [consistency modes](/api/features/consistency),
[agent caching](/api/features/caching.html), and [agent caching](/api/features/caching), and
[required ACLs](/api#authentication). [required ACLs](/api#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
@ -88,7 +88,7 @@ The table below shows this endpoint's support for
- `Verb` `(string: <required>)` - Specifies the type of operation to perform. - `Verb` `(string: <required>)` - Specifies the type of operation to perform.
- `Node` `(Node: <required>)` - Specifies the node information to use - `Node` `(Node: <required>)` - Specifies the node information to use
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object. Note the only the node can be specified here, not any services or checks - separate service or check operations must be used for those. for the operation. See the [catalog endpoint](/api/catalog#parameters) for the fields in this object. Note the only the node can be specified here, not any services or checks - separate service or check operations must be used for those.
- `Service` operations have the following fields: - `Service` operations have the following fields:
@ -98,14 +98,14 @@ The table below shows this endpoint's support for
this service operation. this service operation.
- `Service` `(Service: <required>)` - Specifies the service instance information to use - `Service` `(Service: <required>)` - Specifies the service instance information to use
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object. for the operation. See the [catalog endpoint](/api/catalog#parameters) for the fields in this object.
- `Check` operations have the following fields: - `Check` operations have the following fields:
- `Verb` `(string: <required>)` - Specifies the type of operation to perform. - `Verb` `(string: <required>)` - Specifies the type of operation to perform.
- `Check` `(Service: <required>)` - Specifies the check to use - `Check` `(Service: <required>)` - Specifies the check to use
for the operation. See the [catalog endpoint](/api/catalog.html#parameters) for the fields in this object. for the operation. See the [catalog endpoint](/api/catalog#parameters) for the fields in this object.
Please see the table below for available verbs. Please see the table below for available verbs.

244
website/pages/docs/acl/acl-legacy.mdx
View File

@ -12,23 +12,23 @@ description: >-
# ACL System in Legacy Mode # ACL System in Legacy Mode
-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system.html) -> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system)
~> **Alert: Deprecation Notice** ~> **Alert: Deprecation Notice**
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0 The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
the ACL system was rewritten and the legacy system was deprecated. The new ACL system information can be found [here](/docs/acl/acl-system.html). the ACL system was rewritten and the legacy system was deprecated. The new ACL system information can be found [here](/docs/acl/acl-system).
The legacy documentation has two sections. The legacy documentation has two sections.
- The [New ACL System Differences](#new-acl-system-differences) section - The [New ACL System Differences](#new-acl-system-differences) section
details the differences between ACLs in Consul 1.4.0 and older versions. You should read this section before upgrading to Consul 1.4.0 and [migrating](/docs/acl/acl-migrate-tokens.html) tokens. details the differences between ACLs in Consul 1.4.0 and older versions. You should read this section before upgrading to Consul 1.4.0 and [migrating](/docs/acl/acl-migrate-tokens) tokens.
- The [Legacy ACL System documentation](#legacy-acl-system) section details the - The [Legacy ACL System documentation](#legacy-acl-system) section details the
ACL system in Consul 1.3.0 and older. ACL system in Consul 1.3.0 and older.
# New ACL System Differences # New ACL System Differences
The [ACL System documentation](/docs/acl/acl-system.html) and [legacy ACL The [ACL System documentation](/docs/acl/acl-system) and [legacy ACL
documentation](/docs/acl/acl-legacy.html) describes the new and old systems in documentation](/docs/acl/acl-legacy) describes the new and old systems in
detail. Below is a summary of the changes that need to be considered when detail. Below is a summary of the changes that need to be considered when
migrating legacy tokens to the new system. migrating legacy tokens to the new system.
@ -73,24 +73,24 @@ key_prefix "foo" { policy = "write" }
The "old" API endpoints below continue to work for backwards compatibility but The "old" API endpoints below continue to work for backwards compatibility but
will continue to create or show only "legacy" tokens that can't take full will continue to create or show only "legacy" tokens that can't take full
advantage of the new ACL system improvements. They are documented fully under advantage of the new ACL system improvements. They are documented fully under
[Legacy Tokens](/api/acl/legacy.html). [Legacy Tokens](/api/acl/legacy).
- [`PUT /acl/create` - Create Legacy Token](/api/acl/legacy.html#create-acl-token) - [`PUT /acl/create` - Create Legacy Token](/api/acl/legacy#create-acl-token)
- [`PUT /acl/update` - Update Legacy Token](/api/acl/legacy.html#update-acl-token) - [`PUT /acl/update` - Update Legacy Token](/api/acl/legacy#update-acl-token)
- [`PUT /acl/destroy/:uuid` - Delete Legacy Token](/api/acl/legacy.html#delete-acl-token) - [`PUT /acl/destroy/:uuid` - Delete Legacy Token](/api/acl/legacy#delete-acl-token)
- [`GET /acl/info/:uuid` - Read Legacy Token](/api/acl/legacy.html#read-acl-token) - [`GET /acl/info/:uuid` - Read Legacy Token](/api/acl/legacy#read-acl-token)
- [`PUT /acl/clone/:uuid` - Clone Legacy Token](/api/acl/legacy.html#clone-acl-token) - [`PUT /acl/clone/:uuid` - Clone Legacy Token](/api/acl/legacy#clone-acl-token)
- [`GET /acl/list` - List Legacy Tokens](/api/acl/legacy.html#list-acls) - [`GET /acl/list` - List Legacy Tokens](/api/acl/legacy#list-acls)
The new ACL system includes new API endpoints to manage The new ACL system includes new API endpoints to manage
the [ACL System](/api/acl/acl.html), [Tokens](/api/acl/tokens.html) the [ACL System](/api/acl/acl), [Tokens](/api/acl/tokens)
and [Policies](/api/acl/policies.html). and [Policies](/api/acl/policies).
# Legacy ACL System # Legacy ACL System
~> **Warning**: In this document we use the deprecated ~> **Warning**: In this document we use the deprecated
configuration parameter `acl_datacenter`. In Consul 1.4 and newer the configuration parameter `acl_datacenter`. In Consul 1.4 and newer the
parameter has been updated to [`primary_datacenter`](https://www.consul.io/docs/agent/options.html#primary_datacenter). parameter has been updated to [`primary_datacenter`](/docs/agent/options#primary_datacenter).
Consul provides an optional Access Control List (ACL) system which can be used to control Consul provides an optional Access Control List (ACL) system which can be used to control
access to data and APIs. The ACL is access to data and APIs. The ACL is
@ -106,7 +106,7 @@ all while providing administrative insight.
#### ACL Tokens #### ACL Tokens
The ACL system is based on tokens, which are managed by Consul operators via Consul's The ACL system is based on tokens, which are managed by Consul operators via Consul's
[ACL API](/api/acl/acl.html), or systems like [ACL API](/api/acl/acl), or systems like
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul). [HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul).
Every token has an ID, name, type, and rule set. The ID is a randomly generated Every token has an ID, name, type, and rule set. The ID is a randomly generated
@ -123,14 +123,14 @@ token [RFC6750](https://tools.ietf.org/html/rfc6750). Consul's
If no token is provided, the rules associated with a special, configurable anonymous If no token is provided, the rules associated with a special, configurable anonymous
token are automatically applied. The anonymous token is managed using the token are automatically applied. The anonymous token is managed using the
[ACL API](/api/acl/acl.html) like any other ACL token, but using `anonymous` for the ID. [ACL API](/api/acl/acl) like any other ACL token, but using `anonymous` for the ID.
#### ACL Rules and Scope #### ACL Rules and Scope
Tokens are bound to a set of rules that control which Consul resources the token Tokens are bound to a set of rules that control which Consul resources the token
has access to. Policies can be defined in either a whitelist or blacklist mode has access to. Policies can be defined in either a whitelist or blacklist mode
depending on the configuration of depending on the configuration of
[`acl_default_policy`](/docs/agent/options.html#acl_default_policy). If the default [`acl_default_policy`](/docs/agent/options#acl_default_policy). If the default
policy is to "deny" all actions, then token rules can be set to whitelist specific policy is to "deny" all actions, then token rules can be set to whitelist specific
actions. In the inverse, the "allow" all default behavior is a blacklist where rules actions. In the inverse, the "allow" all default behavior is a blacklist where rules
are used to prohibit actions. By default, Consul will allow all actions. are used to prohibit actions. By default, Consul will allow all actions.
@ -139,29 +139,29 @@ The following table summarizes the ACL policies that are available for construct
rules: rules:
| Policy | Scope | | Policy | Scope |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent.html), other than service and check registration | | [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent), other than service and check registration |
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) | | [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event) |
| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv.html) | | [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv) |
| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring.html) | | [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring) |
| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), [Network Coordinate API](/api/coordinate.html), and [Agent API](/api/agent.html) | | [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Prepared Query API](/api/query), [Network Coordinate API](/api/coordinate), and [Agent API](/api/agent) |
| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html) | | [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring) |
| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query.html) | | [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query) |
| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), and [Agent API](/api/agent.html) | | [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Prepared Query API](/api/query), and [Agent API](/api/agent) |
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) | | [`session`](#session-rules) | Session operations in the [Session API](/api/session) |
Since Consul snapshots actually contain ACL tokens, the Since Consul snapshots actually contain ACL tokens, the
[Snapshot API](/api/snapshot.html) requires a management token for snapshot operations [Snapshot API](/api/snapshot) requires a management token for snapshot operations
and does not use a special policy. and does not use a special policy.
The following resources are not covered by ACL policies: The following resources are not covered by ACL policies:
1. The [Status API](/api/status.html) is used by servers when bootstrapping and exposes 1. The [Status API](/api/status) is used by servers when bootstrapping and exposes
basic IP and port information about the servers, and does not allow modification basic IP and port information about the servers, and does not allow modification
of any state. of any state.
2. The datacenter listing operation of the 2. The datacenter listing operation of the
[Catalog API](/api/catalog.html#list-datacenters) similarly exposes the names of known [Catalog API](/api/catalog#list-datacenters) similarly exposes the names of known
Consul datacenters, and does not allow modification of any state. Consul datacenters, and does not allow modification of any state.
Constructing rules from these policies is covered in detail in the Constructing rules from these policies is covered in detail in the
@ -170,9 +170,9 @@ Constructing rules from these policies is covered in detail in the
#### ACL Datacenter #### ACL Datacenter
All nodes (clients and servers) must be configured with a All nodes (clients and servers) must be configured with a
[`acl_datacenter`](/docs/agent/options.html#acl_datacenter) which enables ACL [`acl_datacenter`](/docs/agent/options#acl_datacenter) which enables ACL
enforcement but also specifies the authoritative datacenter. Consul relies on enforcement but also specifies the authoritative datacenter. Consul relies on
[RPC forwarding](/docs/internals/architecture.html) to support multi-datacenter [RPC forwarding](/docs/internals/architecture) to support multi-datacenter
configurations. However, because requests can be made across datacenter boundaries, configurations. However, because requests can be made across datacenter boundaries,
ACL tokens must be valid globally. To avoid consistency issues, a single datacenter ACL tokens must be valid globally. To avoid consistency issues, a single datacenter
is considered authoritative and stores the canonical set of tokens. is considered authoritative and stores the canonical set of tokens.
@ -180,14 +180,14 @@ is considered authoritative and stores the canonical set of tokens.
When a request is made to an agent in a non-authoritative datacenter, it must be When a request is made to an agent in a non-authoritative datacenter, it must be
resolved into the appropriate policy. This is done by reading the token from the resolved into the appropriate policy. This is done by reading the token from the
authoritative server and caching the result for a configurable authoritative server and caching the result for a configurable
[`acl_ttl`](/docs/agent/options.html#acl_ttl). The implication of caching is that [`acl_ttl`](/docs/agent/options#acl_ttl). The implication of caching is that
the cache TTL is an upper bound on the staleness of policy that is enforced. It is the cache TTL is an upper bound on the staleness of policy that is enforced. It is
possible to set a zero TTL, but this has adverse performance impacts, as every possible to set a zero TTL, but this has adverse performance impacts, as every
request requires refreshing the policy via an RPC call. request requires refreshing the policy via an RPC call.
During an outage of the ACL datacenter, or loss of connectivity, the cache will be During an outage of the ACL datacenter, or loss of connectivity, the cache will be
used as long as the TTL is valid, or the cache may be extended if the used as long as the TTL is valid, or the cache may be extended if the
[`acl_down_policy`](/docs/agent/options.html#acl_down_policy) is set accordingly. [`acl_down_policy`](/docs/agent/options#acl_down_policy) is set accordingly.
This configuration also allows the ACL system to fail open or closed. This configuration also allows the ACL system to fail open or closed.
[ACL replication](#replication) is also available to allow for the full set of ACL [ACL replication](#replication) is also available to allow for the full set of ACL
tokens to be replicated for use during an outage. tokens to be replicated for use during an outage.
@ -198,11 +198,11 @@ ACLs are configured using several different configuration options. These are mar
as to whether they are set on servers, clients, or both. as to whether they are set on servers, clients, or both.
| Configuration Option | Servers | Clients | Purpose | | Configuration Option | Servers | Clients | Purpose |
| -------------------------------------------------------------------------- | ---------- | ---------- | ----------------------------------------------------------------------------------------- | | --------------------------------------------------------------------- | ---------- | ---------- | ----------------------------------------------------------------------------------------- |
| [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | | [`acl_datacenter`](/docs/agent/options#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs |
| [`acl_default_policy`](/docs/agent/options.html#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode | | [`acl_default_policy`](/docs/agent/options#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode |
| [`acl_down_policy`](/docs/agent/options.html#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | | [`acl_down_policy`](/docs/agent/options#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline |
| [`acl_ttl`](/docs/agent/options.html#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | | [`acl_ttl`](/docs/agent/options#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs |
There are some additional configuration items related to [ACL replication](#replication) and There are some additional configuration items related to [ACL replication](#replication) and
[Version 8 ACL support](#version_8_acls). These are discussed in those respective sections [Version 8 ACL support](#version_8_acls). These are discussed in those respective sections
@ -212,18 +212,18 @@ A number of special tokens can also be configured which allow for bootstrapping
system, or accessing Consul in special situations: system, or accessing Consul in special situations:
| Special Token | Servers | Clients | Purpose | | Special Token | Servers | Clients | Purpose |
| ---------------------------------------------------------------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ----------------------------------------------------------------------------- | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent.html) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | | [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details |
| [`acl_agent_token`](/docs/agent/options.html#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | | [`acl_agent_token`](/docs/agent/options#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details |
| [`acl_master_token`](/docs/agent/options.html#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details | | [`acl_master_token`](/docs/agent/options#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details |
| [`acl_token`](/docs/agent/options.html#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | | [`acl_token`](/docs/agent/options#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents |
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
[/v1/agent/token API](/api/agent.html#update-acl-tokens). [/v1/agent/token API](/api/agent#update-acl-tokens).
#### ACL Agent Master Token #### ACL Agent Master Token
Since the [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0): Since the [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0):
```hcl ```hcl
agent "<node name of agent>" { agent "<node name of agent>" {
@ -235,15 +235,15 @@ node "" {
``` ```
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
[/v1/agent/token API](/api/agent.html#update-acl-tokens). [/v1/agent/token API](/api/agent#update-acl-tokens).
#### ACL Agent Token #### ACL Agent Token
The [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/docs/agent/options.html#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent: The [`acl_agent_token`](/docs/agent/options#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/docs/agent/options#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent:
1. Updating the agent's node entry using the [Catalog API](/api/catalog.html), including updating its node metadata, tagged addresses, and network coordinates 1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/internals/anti-entropy.html) syncing, in particular reading the node metadata and services registered with the catalog 2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec.html) commands 3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands
Here's an example policy sufficient to accomplish the above for a node called `mynode`: Here's an example policy sufficient to accomplish the above for a node called `mynode`:
@ -259,10 +259,10 @@ key "_rexec" {
} }
``` ```
The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options.html#disable_remote_exec), the default, then the `key` policy can be omitted. The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key` policy can be omitted.
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
[/v1/agent/token API](/api/agent.html#update-acl-tokens). [/v1/agent/token API](/api/agent#update-acl-tokens).
## Bootstrapping ACLs ## Bootstrapping ACLs
@ -275,7 +275,7 @@ The first step for bootstrapping ACLs is to enable ACLs on the Consul servers in
datacenter. In this example, we are configuring the following: datacenter. In this example, we are configuring the following:
1. An ACL datacenter of "dc1", which is where these servers are 1. An ACL datacenter of "dc1", which is where these servers are
2. An ACL master token of "b1gs33cr3t"; see below for an alternative using the [/v1/acl/bootstrap API](/api/acl/acl.html#bootstrap-acls) 2. An ACL master token of "b1gs33cr3t"; see below for an alternative using the [/v1/acl/bootstrap API](/api/acl/acl#bootstrap-acls)
3. A default policy of "deny" which means we are in whitelist mode 3. A default policy of "deny" which means we are in whitelist mode
4. A down policy of "extend-cache" which means that we will ignore token TTLs during an 4. A down policy of "extend-cache" which means that we will ignore token TTLs during an
outage outage
@ -295,15 +295,15 @@ The servers will need to be restarted to load the new configuration. Please take
to start the servers one at a time, and ensure each server has joined and is operating to start the servers one at a time, and ensure each server has joined and is operating
correctly before starting another. correctly before starting another.
The [`acl_master_token`](/docs/agent/options.html#acl_master_token) will be created The [`acl_master_token`](/docs/agent/options#acl_master_token) will be created
as a "management" type token automatically. The as a "management" type token automatically. The
[`acl_master_token`](/docs/agent/options.html#acl_master_token) is only installed when [`acl_master_token`](/docs/agent/options#acl_master_token) is only installed when
a server acquires cluster leadership. If you would like to install or change the a server acquires cluster leadership. If you would like to install or change the
[`acl_master_token`](/docs/agent/options.html#acl_master_token), set the new value for [`acl_master_token`](/docs/agent/options#acl_master_token), set the new value for
[`acl_master_token`](/docs/agent/options.html#acl_master_token) in the configuration [`acl_master_token`](/docs/agent/options#acl_master_token) in the configuration
for all servers. Once this is done, restart the current leader to force a leader election. for all servers. Once this is done, restart the current leader to force a leader election.
In Consul 0.9.1 and later, you can use the [/v1/acl/bootstrap API](/api/acl/acl.html#bootstrap-acls) In Consul 0.9.1 and later, you can use the [/v1/acl/bootstrap API](/api/acl/acl#bootstrap-acls)
to make the initial master token, so a token never needs to be placed into a configuration to make the initial master token, so a token never needs to be placed into a configuration
file. To use this approach, omit `acl_master_token` from the above config and then call the API: file. To use this approach, omit `acl_master_token` from the above config and then call the API:
@ -320,7 +320,7 @@ It's only possible to bootstrap one time, and bootstrapping will be disabled if
token was configured and created. token was configured and created.
Once the ACL system is bootstrapped, ACL tokens can be managed through the Once the ACL system is bootstrapped, ACL tokens can be managed through the
[ACL API](/api/acl/acl.html). [ACL API](/api/acl/acl).
#### Create an Agent Token #### Create an Agent Token
@ -333,9 +333,9 @@ servers related to permission denied errors:
``` ```
These errors are because the agent doesn't yet have a properly configured These errors are because the agent doesn't yet have a properly configured
[`acl_agent_token`](/docs/agent/options.html#acl_agent_token) that it can use for its [`acl_agent_token`](/docs/agent/options#acl_agent_token) that it can use for its
own internal operations like updating its node information in the catalog and performing own internal operations like updating its node information in the catalog and performing
[anti-entropy](/docs/internals/anti-entropy.html) syncing. We can create a token using the [anti-entropy](/docs/internals/anti-entropy) syncing. We can create a token using the
ACL API, and the ACL master token we set in the previous step: ACL API, and the ACL master token we set in the previous step:
```text ```text
@ -419,7 +419,7 @@ environment it is recommended that each client get an ACL agent token with `node
privileges for just its own node name prefix, and `service` read privileges for just the privileges for just its own node name prefix, and `service` read privileges for just the
service prefixes expected to be registered on that client. service prefixes expected to be registered on that client.
[Anti-entropy](/docs/internals/anti-entropy.html) syncing requires the ACL agent token [Anti-entropy](/docs/internals/anti-entropy) syncing requires the ACL agent token
to have `service` read privileges for all services that may be registered with the agent, to have `service` read privileges for all services that may be registered with the agent,
so generally an empty `service` prefix can be used, as shown in the example. so generally an empty `service` prefix can be used, as shown in the example.
@ -551,20 +551,20 @@ The next section shows an alternative to the anonymous token.
#### Set Agent-Specific Default Tokens (Optional) #### Set Agent-Specific Default Tokens (Optional)
An alternative to the anonymous token is the [`acl_token`](/docs/agent/options.html#acl_token) An alternative to the anonymous token is the [`acl_token`](/docs/agent/options#acl_token)
configuration item. When a request is made to a particular Consul agent and no token is configuration item. When a request is made to a particular Consul agent and no token is
supplied, the [`acl_token`](/docs/agent/options.html#acl_token) will be used for the token, supplied, the [`acl_token`](/docs/agent/options#acl_token) will be used for the token,
instead of being left empty which would normally invoke the anonymous token. instead of being left empty which would normally invoke the anonymous token.
In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the
[/v1/agent/token API](/api/agent.html#update-acl-tokens). [/v1/agent/token API](/api/agent#update-acl-tokens).
This behaves very similarly to the anonymous token, but can be configured differently on each This behaves very similarly to the anonymous token, but can be configured differently on each
agent, if desired. For example, this allows more fine grained control of what DNS requests a agent, if desired. For example, this allows more fine grained control of what DNS requests a
given agent can service, or can give the agent read access to some key-value store prefixes by given agent can service, or can give the agent read access to some key-value store prefixes by
default. default.
If using [`acl_token`](/docs/agent/options.html#acl_token), then it's likely the anonymous If using [`acl_token`](/docs/agent/options#acl_token), then it's likely the anonymous
token will have a more restrictive policy than shown in the examples here. token will have a more restrictive policy than shown in the examples here.
#### Create Tokens for UI Use (Optional) #### Create Tokens for UI Use (Optional)
@ -592,7 +592,7 @@ The token can then be set on the "settings" page of the UI.
#### Next Steps #### Next Steps
The examples above configure a basic ACL environment with the ability to see all nodes The examples above configure a basic ACL environment with the ability to see all nodes
by default, and limited access to just the "consul" service. The [ACL API](/api/acl/acl.html) by default, and limited access to just the "consul" service. The [ACL API](/api/acl/acl)
can be used to create tokens for applications specific to their intended use, and to create can be used to create tokens for applications specific to their intended use, and to create
more specific ACL agent tokens for each agent's expected role. more specific ACL agent tokens for each agent's expected role.
@ -659,7 +659,7 @@ This is equivalent to the following JSON input:
} }
``` ```
The [ACL API](/api/acl/acl.html) allows either HCL or JSON to be used to define the content The [ACL API](/api/acl/acl) allows either HCL or JSON to be used to define the content
of the rules section. of the rules section.
Here's a sample request using the HCL form: Here's a sample request using the HCL form:
@ -703,7 +703,7 @@ or the `CONSUL_HTTP_TOKEN` environment variable.
#### Agent Rules #### Agent Rules
The `agent` policy controls access to the utility operations in the [Agent API](/api/agent.html), The `agent` policy controls access to the utility operations in the [Agent API](/api/agent),
such as join and leave. All of the catalog-related operations are covered by the [`node`](#node-rules) such as join and leave. All of the catalog-related operations are covered by the [`node`](#node-rules)
and [`service`](#service-rules) policies instead. and [`service`](#service-rules) policies instead.
@ -726,14 +726,14 @@ the example above, the rules allow read-only access to any node name with the em
read-write access to any node name that starts with "foo", and deny all access to any node name that read-write access to any node name that starts with "foo", and deny all access to any node name that
starts with "bar". starts with "bar".
Since [Agent API](/api/agent.html) utility operations may be required before an agent is joined to Since [Agent API](/api/agent) utility operations may be required before an agent is joined to
a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be
configured with [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) to allow configured with [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) to allow
write access to these operations even if no ACL resolution capability is available. write access to these operations even if no ACL resolution capability is available.
#### Event Rules #### Event Rules
The `event` policy controls access to event operations in the [Event API](/api/event.html), such as The `event` policy controls access to event operations in the [Event API](/api/event), such as
firing events and listing events. firing events and listing events.
Event rules look like this: Event rules look like this:
@ -751,14 +751,14 @@ Event rules are keyed by the event name prefix they apply to, using the longest
In the example above, the rules allow read-only access to any event, and firing of any event that In the example above, the rules allow read-only access to any event, and firing of any event that
starts with "deploy". starts with "deploy".
The [`consul exec`](/docs/commands/exec.html) command uses events with the "\_rexec" prefix during The [`consul exec`](/docs/commands/exec) command uses events with the "\_rexec" prefix during
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
give agents a token with access to this event prefix, in addition to configuring give agents a token with access to this event prefix, in addition to configuring
[`disable_remote_exec`](/docs/agent/options.html#disable_remote_exec) to `false`. [`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
#### Key/Value Rules #### Key/Value Rules
The `key` policy controls access to key/value store operations in the [KV API](/api/kv.html). Key The `key` policy controls access to key/value store operations in the [KV API](/api/kv). Key
rules look like this: rules look like this:
```hcl ```hcl
@ -782,7 +782,7 @@ starts with "bar".
Consul 1.0 introduces a new `list` policy for keys that is only enforced when opted in via the boolean config param "acl_enable_key_list_policy". Consul 1.0 introduces a new `list` policy for keys that is only enforced when opted in via the boolean config param "acl_enable_key_list_policy".
`list` controls access to recursively list entries and keys, and enables more fine grained policies. With "acl_enable_key_list_policy", `list` controls access to recursively list entries and keys, and enables more fine grained policies. With "acl_enable_key_list_policy",
recursive reads via [the KV API](/api/kv.html#recurse) with an invalid token result in a 403. Example: recursive reads via [the KV API](/api/kv#recurse) with an invalid token result in a 403. Example:
```hcl ```hcl
key "" { key "" {
@ -821,12 +821,12 @@ EOF
} }
``` ```
For more detailed information, see the [Consul Sentinel documentation](/docs/agent/sentinel.html). For more detailed information, see the [Consul Sentinel documentation](/docs/agent/sentinel).
#### Keyring Rules #### Keyring Rules
The `keyring` policy controls access to keyring operations in the The `keyring` policy controls access to keyring operations in the
[Keyring API](/api/operator/keyring.html). [Keyring API](/api/operator/keyring).
Keyring rules look like this: Keyring rules look like this:
@ -839,8 +839,8 @@ dispositions. In the example above, the keyring may be read and updated.
#### Node Rules #### Node Rules
The `node` policy controls node-level registration and read access to the [Catalog API](/api/catalog.html), The `node` policy controls node-level registration and read access to the [Catalog API](/api/catalog),
service discovery with the [Health API](/api/health.html), and filters results in [Agent API](/api/agent.html) service discovery with the [Health API](/api/health), and filters results in [Agent API](/api/agent)
operations like fetching the list of cluster members. operations like fetching the list of cluster members.
Node rules look like this: Node rules look like this:
@ -862,43 +862,43 @@ the example above, the rules allow read-only access to any node name with the em
read-write access to any node name that starts with "app", and deny all access to any node name that read-write access to any node name that starts with "app", and deny all access to any node name that
starts with "admin". starts with "admin".
Agents need to be configured with an [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) Agents need to be configured with an [`acl_agent_token`](/docs/agent/options#acl_agent_token)
with at least "write" privileges to their own node name in order to register their information with with at least "write" privileges to their own node name in order to register their information with
the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent
will print an error to the console when it tries to sync its state with the catalog. will print an error to the console when it tries to sync its state with the catalog.
Consul's DNS interface is also affected by restrictions on node rules. If the Consul's DNS interface is also affected by restrictions on node rules. If the
[`acl_token`](/docs/agent/options.html#acl_token) used by the agent does not have "read" access to a [`acl_token`](/docs/agent/options#acl_token) used by the agent does not have "read" access to a
given node, then the DNS interface will return no records when queried for it. given node, then the DNS interface will return no records when queried for it.
When reading from the catalog or retrieving information from the health endpoints, node rules are When reading from the catalog or retrieving information from the health endpoints, node rules are
used to filter the results of the query. This allows for configurations where a token has access used to filter the results of the query. This allows for configurations where a token has access
to a given service name, but only on an allowed subset of node names. to a given service name, but only on an allowed subset of node names.
Node rules come into play when using the [Agent API](/api/agent.html) to register node-level Node rules come into play when using the [Agent API](/api/agent) to register node-level
checks. The agent will check tokens locally as a check is registered, and Consul also performs checks. The agent will check tokens locally as a check is registered, and Consul also performs
periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which may require an periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may require an
ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens
to use for registration events: to use for registration events:
1. Using the [acl_token](/docs/agent/options.html#acl_token) configuration 1. Using the [acl_token](/docs/agent/options#acl_token) configuration
directive. This allows a single token to be configured globally and used directive. This allows a single token to be configured globally and used
during all check registration operations. during all check registration operations.
2. Providing an ACL token with service and check definitions at 2. Providing an ACL token with service and check definitions at
registration time. This allows for greater flexibility and enables the use registration time. This allows for greater flexibility and enables the use
of multiple tokens on the same agent. Examples of what this looks like are of multiple tokens on the same agent. Examples of what this looks like are
available for both [services](/docs/agent/services.html) and available for both [services](/docs/agent/services) and
[checks](/docs/agent/checks.html). Tokens may also be passed to the [checks](/docs/agent/checks). Tokens may also be passed to the
[HTTP API](/api) for operations that require them. [HTTP API](/api) for operations that require them.
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
[`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) set to `true` in order to enable [`enable_script_checks`](/docs/agent/options#_enable_script_checks) set to `true` in order to enable
script checks. script checks.
#### Operator Rules #### Operator Rules
The `operator` policy controls access to cluster-level operations in the The `operator` policy controls access to cluster-level operations in the
[Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html). [Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring).
Operator rules look like this: Operator rules look like this:
@ -913,7 +913,7 @@ diagnostic purposes but not make any changes.
#### Prepared Query Rules #### Prepared Query Rules
The `query` policy controls access to create, update, and delete prepared queries in the The `query` policy controls access to create, update, and delete prepared queries in the
[Prepared Query API](/api/query.html). Executing queries is subject to `node` and `service` [Prepared Query API](/api/query). Executing queries is subject to `node` and `service`
policies, as will be explained below. policies, as will be explained below.
Query rules look like this: Query rules look like this:
@ -956,7 +956,7 @@ here, with examples:
that is used and known by many clients to provide geo-failover behavior for that is used and known by many clients to provide geo-failover behavior for
a database. a database.
- [Template queries](/api/query.html#templates) - [Template queries](/api/query#templates)
queries work like static queries with a `Name` defined, except that a catch-all queries work like static queries with a `Name` defined, except that a catch-all
template with an empty `Name` requires an ACL token that can write to any query template with an empty `Name` requires an ACL token that can write to any query
prefix. prefix.
@ -1003,8 +1003,8 @@ These differences are outlined in the table below:
#### Service Rules #### Service Rules
The `service` policy controls service-level registration and read access to the [Catalog API](/api/catalog.html) The `service` policy controls service-level registration and read access to the [Catalog API](/api/catalog)
and service discovery with the [Health API](/api/health.html). and service discovery with the [Health API](/api/health).
Service rules look like this: Service rules look like this:
@ -1026,40 +1026,40 @@ read-write access to any service name that starts with "app", and deny all acces
starts with "admin". starts with "admin".
Consul's DNS interface is affected by restrictions on service rules. If the Consul's DNS interface is affected by restrictions on service rules. If the
[`acl_token`](/docs/agent/options.html#acl_token) used by the agent does not have "read" access to a [`acl_token`](/docs/agent/options#acl_token) used by the agent does not have "read" access to a
given service, then the DNS interface will return no records when queried for it. given service, then the DNS interface will return no records when queried for it.
When reading from the catalog or retrieving information from the health endpoints, service rules are When reading from the catalog or retrieving information from the health endpoints, service rules are
used to filter the results of the query. used to filter the results of the query.
Service rules come into play when using the [Agent API](/api/agent.html) to register services or Service rules come into play when using the [Agent API](/api/agent) to register services or
checks. The agent will check tokens locally as a service or check is registered, and Consul also checks. The agent will check tokens locally as a service or check is registered, and Consul also
performs periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which may require an performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may require an
ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens
to use for registration events: to use for registration events:
1. Using the [acl_token](/docs/agent/options.html#acl_token) configuration 1. Using the [acl_token](/docs/agent/options#acl_token) configuration
directive. This allows a single token to be configured globally and used directive. This allows a single token to be configured globally and used
during all service and check registration operations. during all service and check registration operations.
2. Providing an ACL token with service and check definitions at registration 2. Providing an ACL token with service and check definitions at registration
time. This allows for greater flexibility and enables the use of multiple time. This allows for greater flexibility and enables the use of multiple
tokens on the same agent. Examples of what this looks like are available for tokens on the same agent. Examples of what this looks like are available for
both [services](/docs/agent/services.html) and both [services](/docs/agent/services) and
[checks](/docs/agent/checks.html). Tokens may also be passed to the [HTTP [checks](/docs/agent/checks). Tokens may also be passed to the [HTTP
API](/api) for operations that require them. **Note:** all tokens API](/api) for operations that require them. **Note:** all tokens
passed to an agent are persisted on local disk to allow recovery from passed to an agent are persisted on local disk to allow recovery from
restarts. See [`-data-dir` flag restarts. See [`-data-dir` flag
documentation](/docs/agent/options.html#acl_token) for notes on securing documentation](/docs/agent/options#acl_token) for notes on securing
access. access.
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
[`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) or [`enable_script_checks`](/docs/agent/options#_enable_script_checks) or
[`enable_local_script_checks`](/docs/agent/options.html#_enable_local_script_checks) [`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks)
set to `true` in order to enable script checks. set to `true` in order to enable script checks.
#### Session Rules #### Session Rules
The `session` policy controls access to [Session API](/api/session.html) operations. The `session` policy controls access to [Session API](/api/session) operations.
Session rules look like this: Session rules look like this:
@ -1085,22 +1085,22 @@ name that starts with "admin".
#### Outages and ACL Replication ((#replication)) #### Outages and ACL Replication ((#replication))
The Consul ACL system is designed with flexible rules to accommodate for an outage The Consul ACL system is designed with flexible rules to accommodate for an outage
of the [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) or networking of the [`acl_datacenter`](/docs/agent/options#acl_datacenter) or networking
issues preventing access to it. In this case, it may be impossible for issues preventing access to it. In this case, it may be impossible for
agents in non-authoritative datacenters to resolve tokens. Consul provides agents in non-authoritative datacenters to resolve tokens. Consul provides
a number of configurable [`acl_down_policy`](/docs/agent/options.html#acl_down_policy) a number of configurable [`acl_down_policy`](/docs/agent/options#acl_down_policy)
choices to tune behavior. It is possible to deny or permit all actions or to ignore choices to tune behavior. It is possible to deny or permit all actions or to ignore
cache TTLs and enter a fail-safe mode. The default is to ignore cache TTLs cache TTLs and enter a fail-safe mode. The default is to ignore cache TTLs
for any previously resolved tokens and to deny any uncached tokens. for any previously resolved tokens and to deny any uncached tokens.
Consul 0.7 added an ACL Replication capability that can allow non-authoritative Consul 0.7 added an ACL Replication capability that can allow non-authoritative
datacenter agents to resolve even uncached tokens. This is enabled by setting an datacenter agents to resolve even uncached tokens. This is enabled by setting an
[`acl_replication_token`](/docs/agent/options.html#acl_replication_token) in the [`acl_replication_token`](/docs/agent/options#acl_replication_token) in the
configuration on the servers in the non-authoritative datacenters. In Consul configuration on the servers in the non-authoritative datacenters. In Consul
0.9.1 and later you can enable ACL replication using 0.9.1 and later you can enable ACL replication using
[`enable_acl_replication`](/docs/agent/options.html#enable_acl_replication) and [`enable_acl_replication`](/docs/agent/options#enable_acl_replication) and
then set the token later using the then set the token later using the
[agent token API](/api/agent.html#update-acl-tokens) on each server. This can [agent token API](/api/agent#update-acl-tokens) on each server. This can
also be used to rotate the token without restarting the Consul servers. also be used to rotate the token without restarting the Consul servers.
With replication enabled, the servers will maintain a replica of the authoritative With replication enabled, the servers will maintain a replica of the authoritative
@ -1114,9 +1114,9 @@ every 30 seconds. Replicated changes are written at a rate that's throttled to
a large set of ACLs. a large set of ACLs.
If there's a partition or other outage affecting the authoritative datacenter, If there's a partition or other outage affecting the authoritative datacenter,
and the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy) and the [`acl_down_policy`](/docs/agent/options#acl_down_policy)
is set to "extend-cache", tokens will be resolved during the outage using the is set to "extend-cache", tokens will be resolved during the outage using the
replicated set of ACLs. An [ACL replication status](/api/acl/acl.html#acl_replication_status) replicated set of ACLs. An [ACL replication status](/api/acl/acl#acl_replication_status)
endpoint is available to monitor the health of the replication process. endpoint is available to monitor the health of the replication process.
Also note that in recent versions of Consul (greater than 1.2.0), using Also note that in recent versions of Consul (greater than 1.2.0), using
`acl_down_policy = "async-cache"` refreshes token asynchronously when an ACL is `acl_down_policy = "async-cache"` refreshes token asynchronously when an ACL is
@ -1124,7 +1124,7 @@ already cached and is expired while similar semantics than "extend-cache".
It allows to avoid having issues when connectivity with the authoritative is not completely It allows to avoid having issues when connectivity with the authoritative is not completely
broken, but very slow. broken, but very slow.
Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/options.html#acl_ttl) Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/options#acl_ttl)
setting of the non-authoritative datacenter, so these entries may persist in the setting of the non-authoritative datacenter, so these entries may persist in the
cache for up to the TTL, even after the authoritative datacenter comes back online. cache for up to the TTL, even after the authoritative datacenter comes back online.
@ -1134,7 +1134,7 @@ using a process like this:
1. Enable ACL replication in all datacenters to allow continuation of service 1. Enable ACL replication in all datacenters to allow continuation of service
during the migration, and to populate the target datacenter. Verify replication during the migration, and to populate the target datacenter. Verify replication
is healthy and caught up to the current ACL index in the target datacenter is healthy and caught up to the current ACL index in the target datacenter
using the [ACL replication status](/api/acl/acl.html#acl_replication_status) using the [ACL replication status](/api/acl/acl#acl_replication_status)
endpoint. endpoint.
2. Turn down the old authoritative datacenter servers. 2. Turn down the old authoritative datacenter servers.
3. Rolling restart the agents in the target datacenter and change the 3. Rolling restart the agents in the target datacenter and change the
@ -1150,7 +1150,7 @@ Consul 0.8 added many more ACL policy types and brought ACL enforcement to Consu
agents for the first time. To ease the transition to Consul 0.8 for existing ACL agents for the first time. To ease the transition to Consul 0.8 for existing ACL
users, there's a configuration option to disable these new features. To disable users, there's a configuration option to disable these new features. To disable
support for these new ACLs, set the support for these new ACLs, set the
[`acl_enforce_version_8`](/docs/agent/options.html#acl_enforce_version_8) configuration [`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8) configuration
option to `false` on Consul clients and servers. option to `false` on Consul clients and servers.
Here's a summary of the new features: Here's a summary of the new features:
@ -1173,31 +1173,31 @@ Here's a summary of the new features:
Two new configuration options are used once version 8 ACLs are enabled: Two new configuration options are used once version 8 ACLs are enabled:
- [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) is used as - [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) is used as
a special access token that has `agent` ACL policy `write` privileges on each agent where a special access token that has `agent` ACL policy `write` privileges on each agent where
it is configured, as well as `node` ACL policy `read` privileges for all nodes. This token it is configured, as well as `node` ACL policy `read` privileges for all nodes. This token
should only be used by operators during outages when Consul servers aren't available to should only be used by operators during outages when Consul servers aren't available to
resolve ACL tokens. Applications should use regular ACL tokens during normal operation. resolve ACL tokens. Applications should use regular ACL tokens during normal operation.
- [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) is used internally by - [`acl_agent_token`](/docs/agent/options#acl_agent_token) is used internally by
Consul agents to perform operations to the service catalog when registering themselves Consul agents to perform operations to the service catalog when registering themselves
or sending network coordinates to the servers. This token must at least have `node` ACL or sending network coordinates to the servers. This token must at least have `node` ACL
policy `write` access to the node name it will register as in order to register any policy `write` access to the node name it will register as in order to register any
node-level information like metadata or tagged addresses. node-level information like metadata or tagged addresses.
Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy) Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/options#acl_down_policy)
now applies to Consul clients as well as Consul servers. This will determine what the now applies to Consul clients as well as Consul servers. This will determine what the
client will do in the event that the servers are down. client will do in the event that the servers are down.
Consul clients must have [`acl_datacenter`](/docs/agent/options.html#acl_datacenter) configured Consul clients must have [`acl_datacenter`](/docs/agent/options#acl_datacenter) configured
in order to enable agent-level ACL features. If this is set, the agents will contact the Consul in order to enable agent-level ACL features. If this is set, the agents will contact the Consul
servers to determine if ACLs are enabled at the cluster level. If they detect that ACLs are not servers to determine if ACLs are enabled at the cluster level. If they detect that ACLs are not
enabled, they will check at most every 2 minutes to see if they have become enabled, and will enabled, they will check at most every 2 minutes to see if they have become enabled, and will
start enforcing ACLs automatically. If an agent has an `acl_datacenter` defined, operators will start enforcing ACLs automatically. If an agent has an `acl_datacenter` defined, operators will
need to use the [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token) to need to use the [`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token) to
perform agent-level operations if the Consul servers aren't present (such as for a manual join perform agent-level operations if the Consul servers aren't present (such as for a manual join
to the cluster), unless the [`acl_down_policy`](/docs/agent/options.html#acl_down_policy) on the to the cluster), unless the [`acl_down_policy`](/docs/agent/options#acl_down_policy) on the
agent is set to "allow". agent is set to "allow".
Non-server agents do not need to have the Non-server agents do not need to have the
[`acl_master_token`](/docs/agent/options.html#acl_master_token) configured; it is not [`acl_master_token`](/docs/agent/options#acl_master_token) configured; it is not
used by agents in any way. used by agents in any way.

10
website/pages/docs/acl/acl-migrate-tokens.mdx
View File

@ -61,7 +61,7 @@ blank `AccessorID`.
In addition, it is assumed that all clients that might _create_ ACL tokens (e.g. In addition, it is assumed that all clients that might _create_ ACL tokens (e.g.
Vault's Consul secrets engine) have been updated to use the [new ACL Vault's Consul secrets engine) have been updated to use the [new ACL
APIs](/api/acl/tokens.html). APIs](/api/acl/tokens).
Specifically if you are using Vault's Consul secrets engine you need to be Specifically if you are using Vault's Consul secrets engine you need to be
running Vault 1.0.0 or higher, _and_ you must update all roles defined in Vault running Vault 1.0.0 or higher, _and_ you must update all roles defined in Vault
@ -85,7 +85,7 @@ have.
The simplest and most automatic strategy is to create one new policy for every The simplest and most automatic strategy is to create one new policy for every
existing token. This is easy to automate, but may result in a lot of policies existing token. This is easy to automate, but may result in a lot of policies
with exactly the same rules and with non-human-readable names which will make with exactly the same rules and with non-human-readable names which will make
managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/docs/commands/acl/policy/create.html) command with managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/docs/commands/acl/policy/create) command with
`-from-token` option. `-from-token` option.
| Pros | Cons | | Pros | Cons |
@ -114,7 +114,7 @@ semantics of the old ACL system.
To assist with this approach, there is a CLI tool and corresponding API that can To assist with this approach, there is a CLI tool and corresponding API that can
translate a legacy ACL token's rules into a new ACL policy that is exactly translate a legacy ACL token's rules into a new ACL policy that is exactly
equivalent. See [`consul acl translate-rules`](/docs/commands/acl/translate-rules.html). equivalent. See [`consul acl translate-rules`](/docs/commands/acl/translate-rules).
| Pros | Cons | | Pros | Cons |
| ------------------------------------------------- | ------------------------------------------------------------------ | | ------------------------------------------------- | ------------------------------------------------------------------ |
@ -137,13 +137,13 @@ necessary access for existing clients; this is up to the operator to ensure.
#### Update via API #### Update via API
Use the [`PUT /v1/acl/token/:AccessorID`](/api/acl/tokens.html#update-a-token) Use the [`PUT /v1/acl/token/:AccessorID`](/api/acl/tokens#update-a-token)
endpoint. Specifically, ensure that the `Rules` field is omitted or empty. Empty endpoint. Specifically, ensure that the `Rules` field is omitted or empty. Empty
`Rules` indicates that this is now treated as a new token. `Rules` indicates that this is now treated as a new token.
#### Update via CLI #### Update via CLI
Use the [`consul acl token update`](/docs/commands/acl/token/update.html) Use the [`consul acl token update`](/docs/commands/acl/token/update)
command to update the token. Specifically you need to use `-upgrade-legacy` command to update the token. Specifically you need to use `-upgrade-legacy`
which will ensure that legacy rules are removed as well as the new policies which will ensure that legacy rules are removed as well as the new policies
added. added.

86
website/pages/docs/acl/acl-rules.mdx
View File

@ -12,11 +12,11 @@ description: >-
# ACL Rules # ACL Rules
-> **1.4.0 and later:** This document only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy.html) -> **1.4.0 and later:** This document only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy)
Consul provides an optional Access Control List (ACL) system which can be used Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. To learn more about Consul's ACL review the to control access to data and APIs. To learn more about Consul's ACL review the
[ACL system documentation](/docs/acl/acl-system.html) [ACL system documentation](/docs/acl/acl-system)
A core part of the ACL system is the rule language, which is used to describe the policy A core part of the ACL system is the rule language, which is used to describe the policy
that must be enforced. There are two types of rules: prefix based rules and exact matching that must be enforced. There are two types of rules: prefix based rules and exact matching
@ -45,7 +45,7 @@ Policies can have several control levels:
- `read`: allow the resource to be read but not modified. - `read`: allow the resource to be read but not modified.
- `write`: allow the resource to be read and modified. - `write`: allow the resource to be read and modified.
- `deny`: do not allow the resource to be read or modified. - `deny`: do not allow the resource to be read or modified.
- `list`: allows access to all the keys under a segment in the Consul KV. Note, this policy can only be used with the `key_prefix` resource and [`acl.enable_key_list_policy`](/docs/agent/options.html#acl_enable_key_list) must be set to true. - `list`: allows access to all the keys under a segment in the Consul KV. Note, this policy can only be used with the `key_prefix` resource and [`acl.enable_key_list_policy`](/docs/agent/options#acl_enable_key_list) must be set to true.
When using prefix-based rules, the most specific prefix match determines the action. This When using prefix-based rules, the most specific prefix match determines the action. This
allows for flexible rules like an empty prefix to allow read-only access to all allows for flexible rules like an empty prefix to allow read-only access to all
@ -105,7 +105,7 @@ This is equivalent to the following JSON input:
} }
``` ```
The [ACL API](/api/acl/acl.html) allows either HCL or JSON to be used to define the content The [ACL API](/api/acl/acl) allows either HCL or JSON to be used to define the content
of the rules section of a policy. of the rules section of a policy.
Here's a sample request using the HCL form: Here's a sample request using the HCL form:
@ -154,7 +154,7 @@ Below is a breakdown of each rule type.
#### ACL Resource Rules #### ACL Resource Rules
The `acl` resource controls access to ACL operations in the The `acl` resource controls access to ACL operations in the
[ACL API](/api/acl/acl.html). [ACL API](/api/acl/acl).
ACL rules look like this: ACL rules look like this:
@ -162,13 +162,13 @@ ACL rules look like this:
acl = "write" acl = "write"
``` ```
There is only one acl rule allowed per policy and its value is set to one of the [policy dispositions](/docs/acl/acl-rules.html#rule-specification). In the example There is only one acl rule allowed per policy and its value is set to one of the [policy dispositions](/docs/acl/acl-rules#rule-specification). In the example
above ACLs may be read or written including discovering any token's secret ID. Snapshotting also requires `acl = "write"` above ACLs may be read or written including discovering any token's secret ID. Snapshotting also requires `acl = "write"`
permissions due to the fact that all the token secrets are contained within the snapshot. permissions due to the fact that all the token secrets are contained within the snapshot.
#### Agent Rules #### Agent Rules
The `agent` and `agent_prefix` resources control access to the utility operations in the [Agent API](/api/agent.html), The `agent` and `agent_prefix` resources control access to the utility operations in the [Agent API](/api/agent),
such as join and leave. All of the catalog-related operations are covered by the [`node` or `node_prefix`](#node-rules) such as join and leave. All of the catalog-related operations are covered by the [`node` or `node_prefix`](#node-rules)
and [`service` or `service_prefix`](#service-rules) policies instead. and [`service` or `service_prefix`](#service-rules) policies instead.
@ -191,14 +191,14 @@ allow read-only access to any node name by using the empty prefix, read-write ac
the node with the _exact_ name `foo`, and denies all access to any node name that starts the node with the _exact_ name `foo`, and denies all access to any node name that starts
with `bar`. with `bar`.
Since [Agent API](/api/agent.html) utility operations may be required before an agent is joined to Since [Agent API](/api/agent) utility operations may be required before an agent is joined to
a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be
configured with [`acl.tokens.agent_master`](/docs/agent/options.html#acl_tokens_agent_master) to allow configured with [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) to allow
write access to these operations even if no ACL resolution capability is available. write access to these operations even if no ACL resolution capability is available.
#### Event Rules #### Event Rules
The `event` and `event_prefix` resources control access to event operations in the [Event API](/api/event.html), such as The `event` and `event_prefix` resources control access to event operations in the [Event API](/api/event), such as
firing events and listing events. firing events and listing events.
Event rules look like this: Event rules look like this:
@ -215,14 +215,14 @@ event "deploy" {
Event rules are segmented by the event name they apply to. In the example above, the rules allow Event rules are segmented by the event name they apply to. In the example above, the rules allow
read-only access to any event, and firing of the "deploy" event. read-only access to any event, and firing of the "deploy" event.
The [`consul exec`](/docs/commands/exec.html) command uses events with the "\_rexec" prefix during The [`consul exec`](/docs/commands/exec) command uses events with the "\_rexec" prefix during
operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to
give agents a token with access to this event prefix, in addition to configuring give agents a token with access to this event prefix, in addition to configuring
[`disable_remote_exec`](/docs/agent/options.html#disable_remote_exec) to `false`. [`disable_remote_exec`](/docs/agent/options#disable_remote_exec) to `false`.
#### Key/Value Rules #### Key/Value Rules
The `key` and `key_prefix` resources control access to key/value store operations in the [KV API](/api/kv.html). Key The `key` and `key_prefix` resources control access to key/value store operations in the [KV API](/api/kv). Key
rules look like this: rules look like this:
```hcl ```hcl
@ -244,7 +244,7 @@ to any key name with the empty prefix rule, allow read-write access to the "foo"
Consul 1.0 introduces a new `list` policy for keys that is only enforced when opted in via the boolean config param "acl.enable_key_list_policy". Consul 1.0 introduces a new `list` policy for keys that is only enforced when opted in via the boolean config param "acl.enable_key_list_policy".
`list` controls access to recursively list entries and keys, and enables more fine grained policies. With "acl.enable_key_list_policy", `list` controls access to recursively list entries and keys, and enables more fine grained policies. With "acl.enable_key_list_policy",
recursive reads via [the KV API](/api/kv.html#recurse) with an invalid token result in a 403. Example: recursive reads via [the KV API](/api/kv#recurse) with an invalid token result in a 403. Example:
```hcl ```hcl
key_prefix "" { key_prefix "" {
@ -283,12 +283,12 @@ EOF
} }
``` ```
For more detailed information, see the [Consul Sentinel documentation](/docs/agent/sentinel.html). For more detailed information, see the [Consul Sentinel documentation](/docs/agent/sentinel).
#### Keyring Rules #### Keyring Rules
The `keyring` resource controls access to keyring operations in the The `keyring` resource controls access to keyring operations in the
[Keyring API](/api/operator/keyring.html). [Keyring API](/api/operator/keyring).
Keyring rules look like this: Keyring rules look like this:
@ -301,8 +301,8 @@ dispositions. In the example above, the keyring may be read and updated.
#### Node Rules #### Node Rules
The `node` and `node_prefix` resources controls node-level registration and read access to the [Catalog API](/api/catalog.html), The `node` and `node_prefix` resources controls node-level registration and read access to the [Catalog API](/api/catalog),
service discovery with the [Health API](/api/health.html), and filters results in [Agent API](/api/agent.html) service discovery with the [Health API](/api/health), and filters results in [Agent API](/api/agent)
operations like fetching the list of cluster members. operations like fetching the list of cluster members.
Node rules look like this: Node rules look like this:
@ -322,43 +322,43 @@ node "admin" {
Node rules are segmented by the node name they apply to. In the example above, the rules allow read-only access to any node name with the empty prefix, allow Node rules are segmented by the node name they apply to. In the example above, the rules allow read-only access to any node name with the empty prefix, allow
read-write access to the "app" node, and deny all access to the "admin" node. read-write access to the "app" node, and deny all access to the "admin" node.
Agents need to be configured with an [`acl.tokens.agent`](/docs/agent/options.html#acl_tokens_agent) Agents need to be configured with an [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent)
with at least "write" privileges to their own node name in order to register their information with with at least "write" privileges to their own node name in order to register their information with
the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent
will print an error to the console when it tries to sync its state with the catalog. will print an error to the console when it tries to sync its state with the catalog.
Consul's DNS interface is also affected by restrictions on node rules. If the Consul's DNS interface is also affected by restrictions on node rules. If the
[`acl.token.default`](/docs/agent/options.html#acl_tokens_default) used by the agent does not have "read" access to a [`acl.token.default`](/docs/agent/options#acl_tokens_default) used by the agent does not have "read" access to a
given node, then the DNS interface will return no records when queried for it. given node, then the DNS interface will return no records when queried for it.
When reading from the catalog or retrieving information from the health endpoints, node rules are When reading from the catalog or retrieving information from the health endpoints, node rules are
used to filter the results of the query. This allows for configurations where a token has access used to filter the results of the query. This allows for configurations where a token has access
to a given service name, but only on an allowed subset of node names. to a given service name, but only on an allowed subset of node names.
Node rules come into play when using the [Agent API](/api/agent.html) to register node-level Node rules come into play when using the [Agent API](/api/agent) to register node-level
checks. The agent will check tokens locally as a check is registered, and Consul also performs checks. The agent will check tokens locally as a check is registered, and Consul also performs
periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which may require an periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may require an
ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens
to use for registration events: to use for registration events:
1. Using the [acl.tokens.default](/docs/agent/options.html#acl_tokens_default) configuration 1. Using the [acl.tokens.default](/docs/agent/options#acl_tokens_default) configuration
directive. This allows a single token to be configured globally and used directive. This allows a single token to be configured globally and used
during all check registration operations. during all check registration operations.
2. Providing an ACL token with service and check definitions at 2. Providing an ACL token with service and check definitions at
registration time. This allows for greater flexibility and enables the use registration time. This allows for greater flexibility and enables the use
of multiple tokens on the same agent. Examples of what this looks like are of multiple tokens on the same agent. Examples of what this looks like are
available for both [services](/docs/agent/services.html) and available for both [services](/docs/agent/services) and
[checks](/docs/agent/checks.html). Tokens may also be passed to the [checks](/docs/agent/checks). Tokens may also be passed to the
[HTTP API](/api) for operations that require them. [HTTP API](/api) for operations that require them.
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
[`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) set to `true` in order to enable [`enable_script_checks`](/docs/agent/options#_enable_script_checks) set to `true` in order to enable
script checks. script checks.
#### Operator Rules #### Operator Rules
The `operator` resource controls access to cluster-level operations in the The `operator` resource controls access to cluster-level operations in the
[Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html). [Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring).
Operator rules look like this: Operator rules look like this:
@ -373,7 +373,7 @@ diagnostic purposes but not make any changes.
#### Prepared Query Rules #### Prepared Query Rules
The `query` and `query_prefix` resources control access to create, update, and delete prepared queries in the The `query` and `query_prefix` resources control access to create, update, and delete prepared queries in the
[Prepared Query API](/api/query.html). Executing queries is subject to `node`/`node_prefix` and `service`/`service_prefix` [Prepared Query API](/api/query). Executing queries is subject to `node`/`node_prefix` and `service`/`service_prefix`
policies, as will be explained below. policies, as will be explained below.
Query rules look like this: Query rules look like this:
@ -414,7 +414,7 @@ here, with examples:
that is used and known by many clients to provide geo-failover behavior for that is used and known by many clients to provide geo-failover behavior for
a database. a database.
- [Template queries](/api/query.html#templates) - [Template queries](/api/query#templates)
queries work like static queries with a `Name` defined, except that a catch-all queries work like static queries with a `Name` defined, except that a catch-all
template with an empty `Name` requires an ACL token that can write to any query template with an empty `Name` requires an ACL token that can write to any query
prefix. prefix.
@ -461,8 +461,8 @@ These differences are outlined in the table below:
#### Service Rules #### Service Rules
The `service` and `service_prefix` resources control service-level registration and read access to the [Catalog API](/api/catalog.html) The `service` and `service_prefix` resources control service-level registration and read access to the [Catalog API](/api/catalog)
and service discovery with the [Health API](/api/health.html). and service discovery with the [Health API](/api/health).
Service rules look like this: Service rules look like this:
@ -483,42 +483,42 @@ access to any service name with the empty prefix, allow read-write access to the
access to the "admin" service. access to the "admin" service.
Consul's DNS interface is affected by restrictions on service rules. If the Consul's DNS interface is affected by restrictions on service rules. If the
[`acl.tokens.default`](/docs/agent/options.html#acl_tokens_default) used by the agent does not have "read" access to a [`acl.tokens.default`](/docs/agent/options#acl_tokens_default) used by the agent does not have "read" access to a
given service, then the DNS interface will return no records when queried for it. given service, then the DNS interface will return no records when queried for it.
When reading from the catalog or retrieving information from the health endpoints, service rules are When reading from the catalog or retrieving information from the health endpoints, service rules are
used to filter the results of the query. used to filter the results of the query.
Service rules come into play when using the [Agent API](/api/agent.html) to register services or Service rules come into play when using the [Agent API](/api/agent) to register services or
checks. The agent will check tokens locally as a service or check is registered, and Consul also checks. The agent will check tokens locally as a service or check is registered, and Consul also
performs periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which may require an performs periodic [anti-entropy](/docs/internals/anti-entropy) syncs, which may require an
ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens
to use for registration events: to use for registration events:
1. Using the [acl.tokens.default](/docs/agent/options.html#acl_tokens_default) configuration 1. Using the [acl.tokens.default](/docs/agent/options#acl_tokens_default) configuration
directive. This allows a single token to be configured globally and used directive. This allows a single token to be configured globally and used
during all service and check registration operations. during all service and check registration operations.
2. Providing an ACL token with service and check definitions at registration 2. Providing an ACL token with service and check definitions at registration
time. This allows for greater flexibility and enables the use of multiple time. This allows for greater flexibility and enables the use of multiple
tokens on the same agent. Examples of what this looks like are available for tokens on the same agent. Examples of what this looks like are available for
both [services](/docs/agent/services.html) and both [services](/docs/agent/services) and
[checks](/docs/agent/checks.html). Tokens may also be passed to the [HTTP [checks](/docs/agent/checks). Tokens may also be passed to the [HTTP
API](/api) for operations that require them. **Note:** all tokens API](/api) for operations that require them. **Note:** all tokens
passed to an agent are persisted on local disk to allow recovery from passed to an agent are persisted on local disk to allow recovery from
restarts. See [`-data-dir` flag restarts. See [`-data-dir` flag
documentation](/docs/agent/options.html#acl_token) for notes on securing documentation](/docs/agent/options#acl_token) for notes on securing
access. access.
In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
[`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) or [`enable_script_checks`](/docs/agent/options#_enable_script_checks) or
[`enable_local_script_checks`](/docs/agent/options.html#_enable_local_script_checks) [`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks)
set to `true` in order to enable script checks. set to `true` in order to enable script checks.
-> Note: [Intention privileges](/docs/connect/intentions.html#intention-management-permissions) are managed with service rules. -> Note: [Intention privileges](/docs/connect/intentions#intention-management-permissions) are managed with service rules.
#### Session Rules #### Session Rules
The `session` and `session_prefix` resources controls access to [Session API](/api/session.html) operations. The `session` and `session_prefix` resources controls access to [Session API](/api/session) operations.
Session rules look like this: Session rules look like this:
@ -540,7 +540,7 @@ and deny all access to any sessions on the "admin" node.
#### Namespace Rules <span class="label-enterprise label-enterprise-lg">Enterprise</span> #### Namespace Rules <span class="label-enterprise label-enterprise-lg">Enterprise</span>
[Consul Enterprise](https://www.hashicorp.com/consul.html) 1.7.0 adds support for namespacing many [Consul Enterprise](https://www.hashicorp.com/consul) 1.7.0 adds support for namespacing many
Consul resources. ACL rules themselves can then be defined to only to apply to specific namespaces. Consul resources. ACL rules themselves can then be defined to only to apply to specific namespaces.
A Namespace specific rule would look like this: A Namespace specific rule would look like this:

92
website/pages/docs/acl/acl-system.mdx
View File

@ -12,7 +12,7 @@ description: >-
# ACL System # ACL System
-> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy.html) -> **1.4.0 and later:** This guide only applies in Consul versions 1.4.0 and later. The documentation for the legacy ACL system is [here](/docs/acl/acl-legacy)
Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs.
The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which
@ -48,11 +48,11 @@ may benefit from additional components in the ACL system:
independently configured. (Added in Consul 1.5.0) independently configured. (Added in Consul 1.5.0)
- **ACL Auth Methods and Binding Rules** - To learn more about these topics, - **ACL Auth Methods and Binding Rules** - To learn more about these topics,
see the [dedicated auth methods documentation page](/docs/acl/acl-auth-methods.html). see the [dedicated auth methods documentation page](/docs/acl/acl-auth-methods).
ACL tokens, policies, roles, auth methods, and binding rules are managed by ACL tokens, policies, roles, auth methods, and binding rules are managed by
Consul operators via Consul's [ACL API](/api/acl/acl.html), Consul operators via Consul's [ACL API](/api/acl/acl),
[ACL CLI](/docs/commands/acl.html), or systems like [ACL CLI](/docs/commands/acl), or systems like
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul). [HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul).
If the ACL system becomes inoperable, you can follow the If the ACL system becomes inoperable, you can follow the
@ -65,11 +65,11 @@ An ACL policy is a named set of rules and is composed of the following elements:
- **ID** - The policy's auto-generated public identifier. - **ID** - The policy's auto-generated public identifier.
- **Name** - A unique meaningful name for the policy. - **Name** - A unique meaningful name for the policy.
- **Description** - A human readable description of the policy. (Optional) - **Description** - A human readable description of the policy. (Optional)
- **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules.html#rule-specification) documentation for more details. - **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules#rule-specification) documentation for more details.
- **Datacenters** - A list of datacenters the policy is valid within. - **Datacenters** - A list of datacenters the policy is valid within.
- **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) - **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0)
-> **Consul Enterprise Namespacing** - Rules defined in a policy in any namespace other than `default` will be [restricted](/docs/acl/acl-rules.html#namespace-rules-enterprise) to being able to grant a subset of the overall privileges and only affecting that single namespace. -> **Consul Enterprise Namespacing** - Rules defined in a policy in any namespace other than `default` will be [restricted](/docs/acl/acl-rules#namespace-rules-enterprise) to being able to grant a subset of the overall privileges and only affecting that single namespace.
#### Builtin Policies #### Builtin Policies
@ -84,7 +84,7 @@ An ACL policy is a named set of rules and is composed of the following elements:
-> Added in Consul 1.5.0 -> Added in Consul 1.5.0
An ACL service identity is an [ACL policy](/docs/acl/acl-system.html#acl-policies) template for expressing a link to a policy An ACL service identity is an [ACL policy](/docs/acl/acl-system#acl-policies) template for expressing a link to a policy
suitable for use in [Consul Connect](/docs/connect). They are usable suitable for use in [Consul Connect](/docs/connect). They are usable
on both tokens and roles and are composed of the following elements: on both tokens and roles and are composed of the following elements:
@ -98,7 +98,7 @@ template to aid in avoiding boilerplate policy creation.
During the authorization process, the configured service identity is automatically During the authorization process, the configured service identity is automatically
applied as a policy with the following preconfigured [ACL applied as a policy with the following preconfigured [ACL
rules](/docs/acl/acl-system.html#acl-rules-and-scope): rules](/docs/acl/acl-system#acl-rules-and-scope):
```hcl ```hcl
# Allow the service and its sidecar proxy to register into the catalog. # Allow the service and its sidecar proxy to register into the catalog.
@ -118,7 +118,7 @@ node_prefix "" {
} }
``` ```
The [API documentation for roles](/api/acl/roles.html#sample-payload) has some The [API documentation for roles](/api/acl/roles#sample-payload) has some
examples of using a service identity. examples of using a service identity.
-> **Consul Enterprise Namespacing** - Service Identity rules will be scoped to the single namespace that -> **Consul Enterprise Namespacing** - Service Identity rules will be scoped to the single namespace that
@ -191,7 +191,7 @@ token will be used.
The rules from all policies, roles, and service identities linked with a token are combined to form that token's The rules from all policies, roles, and service identities linked with a token are combined to form that token's
effective rule set. Policy rules can be defined in either a whitelist or blacklist effective rule set. Policy rules can be defined in either a whitelist or blacklist
mode depending on the configuration of [`acl_default_policy`](/docs/agent/options.html#acl_default_policy). mode depending on the configuration of [`acl_default_policy`](/docs/agent/options#acl_default_policy).
If the default policy is to "deny" access to all resources, then policy rules can be set to If the default policy is to "deny" access to all resources, then policy rules can be set to
whitelist access to specific resources. Conversely, if the default policy is “allow” then policy rules can whitelist access to specific resources. Conversely, if the default policy is “allow” then policy rules can
be used to explicitly deny access to resources. be used to explicitly deny access to resources.
@ -200,35 +200,35 @@ The following table summarizes the ACL resources that are available for construc
rules: rules:
| Resource | Scope | | Resource | Scope |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`acl`](#acl-rules) | Operations for managing the ACL system [ACL API](/api/acl/acl.html) | | [`acl`](#acl-rules) | Operations for managing the ACL system [ACL API](/api/acl/acl) |
| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent.html), other than service and check registration | | [`agent`](#agent-rules) | Utility operations in the [Agent API](/api/agent), other than service and check registration |
| [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event.html) | | [`event`](#event-rules) | Listing and firing events in the [Event API](/api/event) |
| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv.html) | | [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api/kv) |
| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring.html) | | [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api/operator/keyring) |
| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), [Network Coordinate API](/api/coordinate.html), and [Agent API](/api/agent.html) | | [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Prepared Query API](/api/query), [Network Coordinate API](/api/coordinate), and [Agent API](/api/agent) |
| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator.html), other than the [Keyring API](/api/operator/keyring.html) | | [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api/operator), other than the [Keyring API](/api/operator/keyring) |
| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query.html) | | [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api/query) |
| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog.html), [Health API](/api/health.html), [Prepared Query API](/api/query.html), and [Agent API](/api/agent.html) | | [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api/catalog), [Health API](/api/health), [Prepared Query API](/api/query), and [Agent API](/api/agent) |
| [`session`](#session-rules) | Session operations in the [Session API](/api/session.html) | | [`session`](#session-rules) | Session operations in the [Session API](/api/session) |
Since Consul snapshots actually contain ACL tokens, the [Snapshot API](/api/snapshot.html) Since Consul snapshots actually contain ACL tokens, the [Snapshot API](/api/snapshot)
requires a token with "write" privileges for the ACL system. requires a token with "write" privileges for the ACL system.
The following resources are not covered by ACL policies: The following resources are not covered by ACL policies:
1. The [Status API](/api/status.html) is used by servers when bootstrapping and exposes 1. The [Status API](/api/status) is used by servers when bootstrapping and exposes
basic IP and port information about the servers, and does not allow modification basic IP and port information about the servers, and does not allow modification
of any state. of any state.
2. The datacenter listing operation of the 2. The datacenter listing operation of the
[Catalog API](/api/catalog.html#list-datacenters) similarly exposes the names of known [Catalog API](/api/catalog#list-datacenters) similarly exposes the names of known
Consul datacenters, and does not allow modification of any state. Consul datacenters, and does not allow modification of any state.
3. The [connect CA roots endpoint](/api/connect/ca.html#list-ca-root-certificates) exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul. 3. The [connect CA roots endpoint](/api/connect/ca#list-ca-root-certificates) exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul.
Constructing rules from these policies is covered in detail on the Constructing rules from these policies is covered in detail on the
[ACL Rules](/docs/acl/acl-rules.html) page. [ACL Rules](/docs/acl/acl-rules) page.
-> **Consul Enterprise Namespacing** - In addition to directly linked policies, roles and service identities, Consul Enterprise -> **Consul Enterprise Namespacing** - In addition to directly linked policies, roles and service identities, Consul Enterprise
will include the ACL policies and roles defined in the [Namespaces definition](/docs/enterprise/namespaces#namespace-definition). (Added in Consul Enterprise 1.7.0) will include the ACL policies and roles defined in the [Namespaces definition](/docs/enterprise/namespaces#namespace-definition). (Added in Consul Enterprise 1.7.0)
@ -239,29 +239,29 @@ ACLs are configured using several different configuration options. These are mar
as to whether they are set on servers, clients, or both. as to whether they are set on servers, clients, or both.
| Configuration Option | Servers | Clients | Purpose | | Configuration Option | Servers | Clients | Purpose |
| ------------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- | | -------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- |
| [`acl.enabled`](/docs/agent/options.html#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled | | [`acl.enabled`](/docs/agent/options#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled |
| [`acl.default_policy`](/docs/agent/options.html#acl_default_policy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode | | [`acl.default_policy`](/docs/agent/options#acl_default_policy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode |
| [`acl.down_policy`](/docs/agent/options.html#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails | | [`acl.down_policy`](/docs/agent/options#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails |
| [`acl.role_ttl`](/docs/agent/options.html#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles | | [`acl.role_ttl`](/docs/agent/options#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles |
| [`acl.policy_ttl`](/docs/agent/options.html#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies | | [`acl.policy_ttl`](/docs/agent/options#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies |
| [`acl.token_ttl`](/docs/agent/options.html#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens | | [`acl.token_ttl`](/docs/agent/options#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens |
A number of special tokens can also be configured which allow for bootstrapping the ACL A number of special tokens can also be configured which allow for bootstrapping the ACL
system, or accessing Consul in special situations: system, or accessing Consul in special situations:
| Special Token | Servers | Clients | Purpose | | Special Token | Servers | Clients | Purpose |
| ----------------------------------------------------------------------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------------------------------------------------ | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`acl.tokens.agent_master`](/docs/agent/options.html#acl_tokens_agent_master) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent.html) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | | [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api/agent) when remote bearer token resolution fails; used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details |
| [`acl.tokens.agent`](/docs/agent/options.html#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | | [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details |
| [`acl.tokens.master`](/docs/agent/options.html#acl_tokens_master) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) guide for more details | | [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide) guide for more details |
| [`acl.tokens.default`](/docs/agent/options.html#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | | [`acl.tokens.default`](/docs/agent/options#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents |
All of these tokens except the `master` token can all be introduced or updated via the [/v1/agent/token API](/api/agent.html#update-acl-tokens). All of these tokens except the `master` token can all be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens).
#### ACL Agent Master Token #### ACL Agent Master Token
Since the [`acl.tokens.agent_master`](/docs/agent/options.html#acl_tokens_agent_master) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it Since the [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it
```hcl ```hcl
agent "<node name of agent>" { agent "<node name of agent>" {
@ -274,11 +274,11 @@ node_prefix "" {
#### ACL Agent Token #### ACL Agent Token
The [`acl.tokens.agent`](/docs/agent/options.html#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/docs/agent/options.html#acl_tokens_default), though if the `acl.tokens.agent_token` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent: The [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/docs/agent/options#acl_tokens_default), though if the `acl.tokens.agent_token` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent:
1. Updating the agent's node entry using the [Catalog API](/api/catalog.html), including updating its node metadata, tagged addresses, and network coordinates 1. Updating the agent's node entry using the [Catalog API](/api/catalog), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/internals/anti-entropy.html) syncing, in particular reading the node metadata and services registered with the catalog 2. Performing [anti-entropy](/docs/internals/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec.html) commands 3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/docs/commands/exec) commands
Here's an example policy sufficient to accomplish the above for a node called `mynode`: Here's an example policy sufficient to accomplish the above for a node called `mynode`:
@ -294,9 +294,9 @@ key_prefix "_rexec" {
} }
``` ```
The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options.html#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/options#disable_remote_exec), the default, then the `key_prefix` policy can be omitted.
## Next Steps ## Next Steps
Setup ACLs with the [Bootstrapping the ACL System guide](https://learn.hashicorp.com/consul/security-networking/production-acls?utm_source=consul.io&utm_medium=docs) or continue reading about Setup ACLs with the [Bootstrapping the ACL System guide](https://learn.hashicorp.com/consul/security-networking/production-acls?utm_source=consul.io&utm_medium=docs) or continue reading about
[ACL rules](/docs/acl/acl-rules.html). [ACL rules](/docs/acl/acl-rules).

22
website/pages/docs/acl/auth-methods/index.mdx
View File

@ -18,7 +18,7 @@ trusted external party to authorize the creation of an ACL tokens usable within
the local datacenter. the local datacenter.
The only supported type of auth method in Consul 1.5.0 is The only supported type of auth method in Consul 1.5.0 is
[`kubernetes`](/docs/acl/auth-methods/kubernetes.html). [`kubernetes`](/docs/acl/auth-methods/kubernetes).
## Overview ## Overview
@ -46,7 +46,7 @@ using the API or command line before they can be used by applications.
details about how to authenticate application credentials. Successful details about how to authenticate application credentials. Successful
validation of application credentials will return a set of trusted identity validation of application credentials will return a set of trusted identity
attributes (such as a username). These can be managed with the `consul acl auth-method` subcommands or the corresponding [API attributes (such as a username). These can be managed with the `consul acl auth-method` subcommands or the corresponding [API
endpoints](/api/acl/auth-methods.html). The specific details of endpoints](/api/acl/auth-methods). The specific details of
configuration are type dependent and described in their own documentation configuration are type dependent and described in their own documentation
pages. pages.
@ -54,10 +54,10 @@ using the API or command line before they can be used by applications.
how to translate trusted identity attributes from each auth method into how to translate trusted identity attributes from each auth method into
privileges assigned to the ACL token that is created. These can be managed privileges assigned to the ACL token that is created. These can be managed
with the `consul acl binding-rule` subcommands or the corresponding [API with the `consul acl binding-rule` subcommands or the corresponding [API
endpoints](/api/acl/binding-rules.html). endpoints](/api/acl/binding-rules).
-> **Note** - To configure auth methods in any connected secondary datacenter, -> **Note** - To configure auth methods in any connected secondary datacenter,
[ACL token replication](/docs/agent/options.html#acl_enable_token_replication) [ACL token replication](/docs/agent/options#acl_enable_token_replication)
must be enabled. Auth methods require the ability to create local tokens which must be enabled. Auth methods require the ability to create local tokens which
is restricted to the primary datacenter and any secondary datacenters with ACL is restricted to the primary datacenter and any secondary datacenters with ACL
token replication enabled. token replication enabled.
@ -65,8 +65,8 @@ token replication enabled.
## Binding Rules ## Binding Rules
Binding rules allow an operator to express a systematic way of automatically Binding rules allow an operator to express a systematic way of automatically
linking [roles](/docs/acl/acl-system.html#acl-roles) and [service linking [roles](/docs/acl/acl-system#acl-roles) and [service
identities](/docs/acl/acl-system.html#acl-service-identities) to newly created identities](/docs/acl/acl-system#acl-service-identities) to newly created
tokens without operator intervention. tokens without operator intervention.
Successful authentication with an auth method returns a set of trusted Successful authentication with an auth method returns a set of trusted
@ -80,12 +80,12 @@ Each binding rule is composed of two portions:
- **Selector** - A logical query that must match the trusted identity - **Selector** - A logical query that must match the trusted identity
attributes for the binding rule to be applicable to a given login attempt. attributes for the binding rule to be applicable to a given login attempt.
The syntax uses github.com/hashicorp/go-bexpr which is shared with the [API The syntax uses github.com/hashicorp/go-bexpr which is shared with the [API
filtering feature](/api/features/filtering.html). For example: filtering feature](/api/features/filtering). For example:
`"serviceaccount.namespace==default and serviceaccount.name!=vault"` `"serviceaccount.namespace==default and serviceaccount.name!=vault"`
- **Bind Type and Name** - A binding rule can bind a token to a - **Bind Type and Name** - A binding rule can bind a token to a
[role](/docs/acl/acl-system.html#acl-roles) or to a [service [role](/docs/acl/acl-system#acl-roles) or to a [service
identity](/docs/acl/acl-system.html#acl-service-identities) by name. The name identity](/docs/acl/acl-system#acl-service-identities) by name. The name
can be specified with a plain string or the bind name can be lightly can be specified with a plain string or the bind name can be lightly
templated using [HIL syntax](https://github.com/hashicorp/hil) to interpolate templated using [HIL syntax](https://github.com/hashicorp/hil) to interpolate
the same values that are usable by the `Selector` syntax. For example: the same values that are usable by the `Selector` syntax. For example:
@ -102,7 +102,7 @@ bearer token for a Consul ACL token by using the login process:
![diagram of auth method login](/img/auth-methods.svg) ![diagram of auth method login](/img/auth-methods.svg)
1. Applications use the `consul login` subcommand or the [login API 1. Applications use the `consul login` subcommand or the [login API
endpoint](/api/acl/acl.html#login-to-auth-method) to authenticate to a endpoint](/api/acl/acl#login-to-auth-method) to authenticate to a
specific auth method using their local Consul client. Applications provide specific auth method using their local Consul client. Applications provide
both the name of the auth method and a secret bearer token during login. both the name of the auth method and a secret bearer token during login.
@ -128,7 +128,7 @@ bearer token for a Consul ACL token by using the login process:
8. The Consul client returns the token details back to the application. 8. The Consul client returns the token details back to the application.
9. (later) Applications SHOULD use the `consul logout` subcommand or the 9. (later) Applications SHOULD use the `consul logout` subcommand or the
[logout API endpoint](/api/acl/acl.html#logout-from-auth-method) to destroy [logout API endpoint](/api/acl/acl#logout-from-auth-method) to destroy
their token when it is no longer required. their token when it is no longer required.
For more details about specific auth methods and how to configure them, click For more details about specific auth methods and how to configure them, click

8
website/pages/docs/acl/auth-methods/kubernetes.mdx
View File

@ -19,11 +19,11 @@ easy to introduce a Consul token into a Kubernetes pod.
This page assumes general knowledge of [Kubernetes](https://kubernetes.io/) and This page assumes general knowledge of [Kubernetes](https://kubernetes.io/) and
the concepts described in the main [auth method the concepts described in the main [auth method
documentation](/docs/acl/acl-auth-methods.html). documentation](/docs/acl/acl-auth-methods).
## Config Parameters ## Config Parameters
The following auth method [`Config`](/api/acl/auth-methods.html#config) The following auth method [`Config`](/api/acl/auth-methods#config)
parameters are required to properly configure an auth method of type parameters are required to properly configure an auth method of type
`kubernetes`: `kubernetes`:
@ -71,7 +71,7 @@ parameters are required to properly configure an auth method of type
## RBAC ## RBAC
The Kubernetes service account corresponding to the configured The Kubernetes service account corresponding to the configured
[`ServiceAccountJWT`](/docs/acl/auth-methods/kubernetes.html#serviceaccountjwt) [`ServiceAccountJWT`](/docs/acl/auth-methods/kubernetes#serviceaccountjwt)
needs to have access to two Kubernetes APIs: needs to have access to two Kubernetes APIs:
- [**TokenReview**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#create-tokenreview-v1-authentication-k8s-io) - [**TokenReview**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#create-tokenreview-v1-authentication-k8s-io)
@ -143,7 +143,7 @@ use in binding rule selectors and bind name interpolation.
## Kubernetes Authentication Details ## Kubernetes Authentication Details
Initially the Initially the
[`ServiceAccountJWT`](/docs/acl/auth-methods/kubernetes.html#serviceaccountjwt) [`ServiceAccountJWT`](/docs/acl/auth-methods/kubernetes#serviceaccountjwt)
given to the Consul leader uses the TokenReview API to validate the provided given to the Consul leader uses the TokenReview API to validate the provided
JWT. The trusted attributes of `serviceaccount.namespace`, JWT. The trusted attributes of `serviceaccount.namespace`,
`serviceaccount.name`, and `serviceaccount.uid` are populated directly from the `serviceaccount.name`, and `serviceaccount.uid` are populated directly from the

10
website/pages/docs/acl/index.mdx
View File

@ -25,32 +25,32 @@ ACLs.
Consul provides an optional Access Control List (ACL) system which can be used Consul provides an optional Access Control List (ACL) system which can be used
to control access to data and APIs. The ACL system is a Capability-based system to control access to data and APIs. The ACL system is a Capability-based system
that relies on tokens which can have fine grained rules applied to them. The that relies on tokens which can have fine grained rules applied to them. The
[ACL System documentation](/docs/acl/acl-system.html) details the functionality [ACL System documentation](/docs/acl/acl-system) details the functionality
of Consul ACLs. of Consul ACLs.
### ACL Rules ### ACL Rules
A core part of the ACL system is the rule language, which is used to describe A core part of the ACL system is the rule language, which is used to describe
the policy that must be enforced. Read the ACL rules the policy that must be enforced. Read the ACL rules
[documentation](/docs/acl/acl-rules.html) to learn about rule specifications. [documentation](/docs/acl/acl-rules) to learn about rule specifications.
### ACL Auth Methods ### ACL Auth Methods
An auth method is a component in Consul that performs authentication against a An auth method is a component in Consul that performs authentication against a
trusted external party to authorize the creation of an ACL tokens usable within trusted external party to authorize the creation of an ACL tokens usable within
the local datacenter. Read the ACL auth method the local datacenter. Read the ACL auth method
[documentation](/docs/acl/acl-auth-methods.html) to learn more about how they [documentation](/docs/acl/acl-auth-methods) to learn more about how they
work and why you may want to use them. work and why you may want to use them.
### ACL Legacy System ### ACL Legacy System
The ACL system in Consul 1.3.1 and older is now called legacy. For information The ACL system in Consul 1.3.1 and older is now called legacy. For information
on bootstrapping the legacy system, ACL rules, and a general ACL system on bootstrapping the legacy system, ACL rules, and a general ACL system
overview, read the legacy [documentation](/docs/acl/acl-legacy.html). overview, read the legacy [documentation](/docs/acl/acl-legacy).
### ACL Migration ### ACL Migration
[The migration documentation](/docs/acl/acl-migrate-tokens.html) details how to [The migration documentation](/docs/acl/acl-migrate-tokens) details how to
upgrade existing legacy tokens after upgrading to 1.4.0. It will briefly upgrade existing legacy tokens after upgrading to 1.4.0. It will briefly
describe what changed, and then walk through the high-level migration process describe what changed, and then walk through the high-level migration process
options, finally giving some specific examples of migration strategies. The new options, finally giving some specific examples of migration strategies. The new

18
website/pages/docs/agent/checks.mdx
View File

@ -36,10 +36,10 @@ There are several different kinds of checks:
In Consul 0.9.0 and later, script checks are not enabled by default. To use them you In Consul 0.9.0 and later, script checks are not enabled by default. To use them you
can either use : can either use :
- [`enable_local_script_checks`](/docs/agent/options.html#_enable_local_script_checks): - [`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks):
enable script checks defined in local config files. Script checks defined via the HTTP enable script checks defined in local config files. Script checks defined via the HTTP
API will not be allowed. API will not be allowed.
- [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks): enable - [`enable_script_checks`](/docs/agent/options#_enable_script_checks): enable
script checks regardless of how they are defined. script checks regardless of how they are defined.
~> **Security Warning:** Enabling script checks in some configurations may ~> **Security Warning:** Enabling script checks in some configurations may
@ -88,9 +88,9 @@ There are several different kinds of checks:
dead man's switch, relies on the application to directly report its health. For dead man's switch, relies on the application to directly report its health. For
example, a healthy app can periodically `PUT` a status update to the HTTP endpoint; example, a healthy app can periodically `PUT` a status update to the HTTP endpoint;
if the app fails, the TTL will expire and the health check enters a critical state. if the app fails, the TTL will expire and the health check enters a critical state.
The endpoints used to update health information for a given check are: [pass](/api/agent/check.html#ttl-check-pass), The endpoints used to update health information for a given check are: [pass](/api/agent/check#ttl-check-pass),
[warn](/api/agent/check.html#ttl-check-warn), [fail](/api/agent/check.html#ttl-check-fail), [warn](/api/agent/check#ttl-check-warn), [fail](/api/agent/check#ttl-check-fail),
and [update](/api/agent/check.html#ttl-check-update). TTL checks also persist their and [update](/api/agent/check#ttl-check-update). TTL checks also persist their
last known status to disk. This allows the Consul agent to restore the last known last known status to disk. This allows the Consul agent to restore the last known
status of the check across restarts. Persisted check status is valid through the status of the check across restarts. Persisted check status is valid through the
end of the TTL from the time of the last check. end of the TTL from the time of the last check.
@ -105,7 +105,7 @@ There are several different kinds of checks:
has to be performed is configurable which makes it possible to run containers which has to be performed is configurable which makes it possible to run containers which
have different shells on the same host. Check output for Docker is limited to have different shells on the same host. Check output for Docker is limited to
4KB. Any output larger than this will be truncated. In Consul 0.9.0 and later, the agent 4KB. Any output larger than this will be truncated. In Consul 0.9.0 and later, the agent
must be configured with [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) must be configured with [`enable_script_checks`](/docs/agent/options#_enable_script_checks)
set to `true` in order to enable Docker health checks. set to `true` in order to enable Docker health checks.
- `gRPC + Interval` - These checks are intended for applications that support the standard - `gRPC + Interval` - These checks are intended for applications that support the standard
@ -258,7 +258,7 @@ updating a TTL check via the HTTP interface can set the `notes` value.
Checks may also contain a `token` field to provide an ACL token. This token is Checks may also contain a `token` field to provide an ACL token. This token is
used for any interaction with the catalog for the check, including used for any interaction with the catalog for the check, including
[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. [anti-entropy syncs](/docs/internals/anti-entropy) and deregistration.
For Alias checks, this token is used if a remote blocking query is necessary For Alias checks, this token is used if a remote blocking query is necessary
to watch the state of the aliased node or service. to watch the state of the aliased node or service.
@ -300,7 +300,7 @@ This is the only convention that Consul depends on. Any output of the script
will be captured and stored in the `output` field. will be captured and stored in the `output` field.
In Consul 0.9.0 and later, the agent must be configured with In Consul 0.9.0 and later, the agent must be configured with
[`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) set to `true` [`enable_script_checks`](/docs/agent/options#_enable_script_checks) set to `true`
in order to enable script checks. in order to enable script checks.
## Initial Health Check Status ## Initial Health Check Status
@ -350,7 +350,7 @@ provided by the node will remain unchanged.
## Agent Certificates for TLS Checks ## Agent Certificates for TLS Checks
The [enable_agent_tls_for_checks](/docs/agent/options.html#enable_agent_tls_for_checks) The [enable_agent_tls_for_checks](/docs/agent/options#enable_agent_tls_for_checks)
agent configuration option can be utilized to have HTTP or gRPC health checks agent configuration option can be utilized to have HTTP or gRPC health checks
to use the agent's credentials when configured for TLS. to use the agent's credentials when configured for TLS.

26
website/pages/docs/agent/config-entries/index.mdx
View File

@ -26,34 +26,34 @@ Name = "<name of entry>"
The supported `Kind` names for configuration entries are: The supported `Kind` names for configuration entries are:
- [`service-router`](/docs/agent/config-entries/service-router.html) - defines - [`service-router`](/docs/agent/config-entries/service-router) - defines
where to send layer 7 traffic based on the HTTP route where to send layer 7 traffic based on the HTTP route
- [`service-splitter`](/docs/agent/config-entries/service-splitter.html) - defines - [`service-splitter`](/docs/agent/config-entries/service-splitter) - defines
how to divide requests for a single HTTP route based on percentages how to divide requests for a single HTTP route based on percentages
- [`service-resolver`](/docs/agent/config-entries/service-resolver.html) - matches - [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches
service instances with a specific Connect upstream discovery requests service instances with a specific Connect upstream discovery requests
- [`service-defaults`](/docs/agent/config-entries/service-defaults.html) - configures - [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures
defaults for all the instances of a given service defaults for all the instances of a given service
- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) - controls - [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - controls
proxy configuration proxy configuration
## Managing Configuration Entries ## Managing Configuration Entries
Configuration entries should be managed with the Consul Configuration entries should be managed with the Consul
[CLI](/docs/commands/config.html) or [API](/api/config.html). Additionally, as a [CLI](/docs/commands/config) or [API](/api/config). Additionally, as a
convenience for initial cluster bootstrapping, configuration entries can be convenience for initial cluster bootstrapping, configuration entries can be
specified in all of the Consul servers's specified in all of the Consul servers's
[configuration files](/docs/agent/options.html#config_entries_bootstrap) [configuration files](/docs/agent/options#config_entries_bootstrap)
### Managing Configuration Entries with the CLI ### Managing Configuration Entries with the CLI
#### Creating or Updating a Configuration Entry #### Creating or Updating a Configuration Entry
The [`consul config write`](/docs/commands/config/write.html) command is used to The [`consul config write`](/docs/commands/config/write) command is used to
create and update configuration entries. This command will load either a JSON or create and update configuration entries. This command will load either a JSON or
HCL file holding the configuration entry definition and then will push this HCL file holding the configuration entry definition and then will push this
configuration to Consul. configuration to Consul.
@ -83,7 +83,7 @@ overwriting other unknown modifications.
#### Reading a Configuration Entry #### Reading a Configuration Entry
The [`consul config read`](/docs/commands/config/read.html) command is used to The [`consul config read`](/docs/commands/config/read) command is used to
read the current value of a configuration entry. The configuration entry will be read the current value of a configuration entry. The configuration entry will be
displayed in JSON form which is how its transmitted between the CLI client and displayed in JSON form which is how its transmitted between the CLI client and
Consul's HTTP API. Consul's HTTP API.
@ -101,7 +101,7 @@ $ consul config read -kind service-defaults -name web
#### Listing Configuration Entries #### Listing Configuration Entries
The [`consul config list`](/docs/commands/config/list.html) command is used to The [`consul config list`](/docs/commands/config/list) command is used to
list out all the configuration entries for a given kind. list out all the configuration entries for a given kind.
Example: Example:
@ -115,7 +115,7 @@ db
#### Deleting Configuration Entries #### Deleting Configuration Entries
The [`consul config delete`](/docs/commands/config/delete.html) command is used The [`consul config delete`](/docs/commands/config/delete) command is used
to delete an entry by specifying both its `kind` and `name`. to delete an entry by specifying both its `kind` and `name`.
Example: Example:
@ -147,7 +147,7 @@ api
### Bootstrapping From A Configuration File ### Bootstrapping From A Configuration File
Configuration entries can be bootstrapped by adding them [inline to each Consul Configuration entries can be bootstrapped by adding them [inline to each Consul
server's configuration file](/docs/agent/options.html#config_entries). When a server's configuration file](/docs/agent/options#config_entries). When a
server gains leadership, it will attempt to initialize the configuration entries. server gains leadership, it will attempt to initialize the configuration entries.
If a configuration entry does not already exist outside of the servers If a configuration entry does not already exist outside of the servers
configuration, then it will create it. If a configuration entry does exist, that configuration, then it will create it. If a configuration entry does exist, that
@ -156,7 +156,7 @@ matches both `kind` and `name`, then the server will do nothing.
## Using Configuration Entries For Service Defaults ## Using Configuration Entries For Service Defaults
When the agent is When the agent is
[configured](/docs/agent/options.html#enable_central_service_config) to enable [configured](/docs/agent/options#enable_central_service_config) to enable
central service configurations, it will look for service configuration defaults central service configurations, it will look for service configuration defaults
that match a registering service instance. If it finds any, the agent will merge that match a registering service instance. If it finds any, the agent will merge
those defaults with the service instance configuration. This allows for things those defaults with the service instance configuration. This allows for things

12
website/pages/docs/agent/config-entries/proxy-defaults.mdx
View File

@ -52,17 +52,17 @@ config {
that your proxy allows can be configured globally here. To that your proxy allows can be configured globally here. To
explore these options please see the documentation for your chosen proxy. explore these options please see the documentation for your chosen proxy.
- [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration) - [Envoy](/docs/connect/proxies/envoy#bootstrap-configuration)
- [Consul's built-in proxy](/docs/connect/proxies/built-in.html) - [Consul's built-in proxy](/docs/connect/proxies/built-in)
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default - `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default
[mesh gateway configuration](/docs/connect/mesh_gateway.html#connect-proxy-configuration) [mesh gateway configuration](/docs/connect/mesh_gateway#connect-proxy-configuration)
for all proxies. Added in v1.6.0. for all proxies. Added in v1.6.0.
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`. - `Mode` `(string: "")` - One of `none`, `local`, or `remote`.
- `Expose` `(ExposeConfig: <optional>)` - Controls the default - `Expose` `(ExposeConfig: <optional>)` - Controls the default
[expose path configuration](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference) [expose path configuration](/docs/connect/registration/service-registration#expose-paths-configuration-reference)
for Envoy. Added in v1.6.2. for Envoy. Added in v1.6.2.
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
@ -71,8 +71,8 @@ config {
- `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. - `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
[advertise address](/docs/agent/options.html#advertise). The port for these listeners are dynamically allocated from [advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from
[expose_min_port](/docs/agent/options.html#expose_min_port) to [expose_max_port](/docs/agent/options.html#expose_max_port). [expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port).
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
Consul on Kubernetes, and Consul agents run in their own pods. Consul on Kubernetes, and Consul agents run in their own pods.
- `Paths` `array<Path>: []` - A list of paths to expose through Envoy. - `Paths` `array<Path>: []` - A list of paths to expose through Envoy.

12
website/pages/docs/agent/config-entries/service-defaults.mdx
View File

@ -34,12 +34,12 @@ Protocol = "http"
- `Protocol` `(string: "tcp")` - Sets the protocol of the service. This is used - `Protocol` `(string: "tcp")` - Sets the protocol of the service. This is used
by Connect proxies for things like observability features and to unlock usage by Connect proxies for things like observability features and to unlock usage
of the [`service-splitter`](/docs/agent/config-entries/service-splitter.html) and of the [`service-splitter`](/docs/agent/config-entries/service-splitter) and
[`service-router`](/docs/agent/config-entries/service-router.html) config [`service-router`](/docs/agent/config-entries/service-router) config
entries for a service. entries for a service.
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default - `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default
[mesh gateway configuration](/docs/connect/mesh_gateway.html#connect-proxy-configuration) [mesh gateway configuration](/docs/connect/mesh_gateway#connect-proxy-configuration)
for this service. Added in v1.6.0. for this service. Added in v1.6.0.
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`. - `Mode` `(string: "")` - One of `none`, `local`, or `remote`.
@ -50,7 +50,7 @@ Protocol = "http"
Added in v1.6.0. Added in v1.6.0.
- `Expose` `(ExposeConfig: <optional>)` - Controls the default - `Expose` `(ExposeConfig: <optional>)` - Controls the default
[expose path configuration](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference) [expose path configuration](/docs/connect/registration/service-registration#expose-paths-configuration-reference)
for Envoy. Added in v1.6.2. for Envoy. Added in v1.6.2.
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
@ -59,8 +59,8 @@ Protocol = "http"
- `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. - `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
[advertise address](/docs/agent/options.html#advertise). The port for these listeners are dynamically allocated from [advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from
[expose_min_port](/docs/agent/options.html#expose_min_port) to [expose_max_port](/docs/agent/options.html#expose_max_port). [expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port).
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
Consul on Kubernetes, and Consul agents run in their own pods. Consul on Kubernetes, and Consul agents run in their own pods.
- `Paths` `array<Path>: []` - A list of paths to expose through Envoy. - `Paths` `array<Path>: []` - A list of paths to expose through Envoy.

6
website/pages/docs/agent/config-entries/service-resolver.mdx
View File

@ -22,7 +22,7 @@ and discovery terminates.
## Interaction with other Config Entries ## Interaction with other Config Entries
- Service resolver config entries are a component of [L7 Traffic - Service resolver config entries are a component of [L7 Traffic
Management](/docs/connect/l7-traffic-management.html). Management](/docs/connect/l7-traffic-management).
## Sample Config Entries ## Sample Config Entries
@ -93,10 +93,10 @@ name = "web"
usable. usable.
- `Filter` `(string: "")` - The - `Filter` `(string: "")` - The
[filter expression](/api/features/filtering.html) to be used for selecting [filter expression](/api/features/filtering) to be used for selecting
instances of the requested service. If empty all healthy instances are instances of the requested service. If empty all healthy instances are
returned. This expression can filter on the same selectors as the returned. This expression can filter on the same selectors as the
[Health API endpoint](/api/health.html#filtering-2). [Health API endpoint](/api/health#filtering-2).
- `OnlyPassing` `(bool: false)` - Specifies the behavior of the resolver's - `OnlyPassing` `(bool: false)` - Specifies the behavior of the resolver's
health check interpretation. If this is set to false, instances with checks health check interpretation. If this is set to false, instances with checks

10
website/pages/docs/agent/config-entries/service-router.mdx
View File

@ -22,20 +22,20 @@ service of the same name.
## Interaction with other Config Entries ## Interaction with other Config Entries
- Service router config entries are a component of [L7 Traffic - Service router config entries are a component of [L7 Traffic
Management](/docs/connect/l7-traffic-management.html). Management](/docs/connect/l7-traffic-management).
- Service router config entries are restricted to only services that define - Service router config entries are restricted to only services that define
their protocol as http-based via a corresponding their protocol as http-based via a corresponding
[`service-defaults`](/docs/agent/config-entries/service-defaults.html) config [`service-defaults`](/docs/agent/config-entries/service-defaults) config
entry or globally via entry or globally via
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) . [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
- Any route destination that omits the `ServiceSubset` field is eligible for - Any route destination that omits the `ServiceSubset` field is eligible for
splitting via a splitting via a
[`service-splitter`](/docs/agent/config-entries/service-splitter.html) should [`service-splitter`](/docs/agent/config-entries/service-splitter) should
one be configured for that service, otherwise resolution proceeds according one be configured for that service, otherwise resolution proceeds according
to any configured to any configured
[`service-resolver`](/docs/agent/config-entries/service-resolver.html). [`service-resolver`](/docs/agent/config-entries/service-resolver).
## Sample Config Entries ## Sample Config Entries

8
website/pages/docs/agent/config-entries/service-splitter.mdx
View File

@ -26,19 +26,19 @@ resolution stage.
## Interaction with other Config Entries ## Interaction with other Config Entries
- Service splitter config entries are a component of [L7 Traffic - Service splitter config entries are a component of [L7 Traffic
Management](/docs/connect/l7-traffic-management.html). Management](/docs/connect/l7-traffic-management).
- Service splitter config entries are restricted to only services that define - Service splitter config entries are restricted to only services that define
their protocol as http-based via a corresponding their protocol as http-based via a corresponding
[`service-defaults`](/docs/agent/config-entries/service-defaults.html) config [`service-defaults`](/docs/agent/config-entries/service-defaults) config
entry or globally via entry or globally via
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) . [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
- Any split destination that specifies a different `Service` field and omits - Any split destination that specifies a different `Service` field and omits
the `ServiceSubset` field is eligible for further splitting should a splitter the `ServiceSubset` field is eligible for further splitting should a splitter
be configured for that other service, otherwise resolution proceeds according be configured for that other service, otherwise resolution proceeds according
to any configured to any configured
[`service-resolver`](/docs/agent/config-entries/service-resolver.html). [`service-resolver`](/docs/agent/config-entries/service-resolver).
## Sample Config Entries ## Sample Config Entries

28
website/pages/docs/agent/dns.mdx
View File

@ -23,18 +23,18 @@ are located in the `us-east-1` datacenter, and have no failing health checks.
It's that simple! It's that simple!
There are a number of configuration options that are important for the DNS interface, There are a number of configuration options that are important for the DNS interface,
specifically [`client_addr`](/docs/agent/options.html#client_addr), specifically [`client_addr`](/docs/agent/options#client_addr),
[`ports.dns`](/docs/agent/options.html#dns_port), [`recursors`](/docs/agent/options.html#recursors), [`ports.dns`](/docs/agent/options#dns_port), [`recursors`](/docs/agent/options#recursors),
[`domain`](/docs/agent/options.html#domain), and [`dns_config`](/docs/agent/options.html#dns_config). [`domain`](/docs/agent/options#domain), and [`dns_config`](/docs/agent/options#dns_config).
By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the `consul.` By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the `consul.`
domain, without support for further DNS recursion. Please consult the domain, without support for further DNS recursion. Please consult the
[documentation on configuration options](/docs/agent/options.html), [documentation on configuration options](/docs/agent/options),
specifically the configuration items linked above, for more details. specifically the configuration items linked above, for more details.
There are a few ways to use the DNS interface. One option is to use a custom There are a few ways to use the DNS interface. One option is to use a custom
DNS resolver library and point it at Consul. Another option is to set Consul DNS resolver library and point it at Consul. Another option is to set Consul
as the DNS server for a node and provide a as the DNS server for a node and provide a
[`recursors`](/docs/agent/options.html#recursors) configuration so that non-Consul queries [`recursors`](/docs/agent/options#recursors) configuration so that non-Consul queries
can also be resolved. The last method is to forward all queries for the "consul." can also be resolved. The last method is to forward all queries for the "consul."
domain to a Consul agent from the existing DNS server. Review the domain to a Consul agent from the existing DNS server. Review the
[DNS Forwarding guide](https://learn.hashicorp.com/consul/security-networking/forwarding?utm_source=consul.io&utm_medium=docs) for examples. [DNS Forwarding guide](https://learn.hashicorp.com/consul/security-networking/forwarding?utm_source=consul.io&utm_medium=docs) for examples.
@ -104,7 +104,7 @@ A service lookup is used to query for service providers. Service queries support
two lookup methods: standard and strict [RFC 2782](https://tools.ietf.org/html/rfc2782). two lookup methods: standard and strict [RFC 2782](https://tools.ietf.org/html/rfc2782).
By default, SRV weights are all set at 1, but changing weights is supported using the By default, SRV weights are all set at 1, but changing weights is supported using the
`Weights` attribute of the [service definition](/docs/agent/services.html). `Weights` attribute of the [service definition](/docs/agent/services).
Note that DNS is limited in size per request, even when performing DNS TCP Note that DNS is limited in size per request, even when performing DNS TCP
queries. queries.
@ -221,11 +221,11 @@ The `datacenter` is optional, and if not provided, the datacenter of this Consul
agent is assumed. agent is assumed.
The `query or name` is the ID or given name of an existing The `query or name` is the ID or given name of an existing
[Prepared Query](/api/query.html). These behave like standard service [Prepared Query](/api/query). These behave like standard service
queries but provide a much richer set of features, such as filtering by multiple queries but provide a much richer set of features, such as filtering by multiple
tags and automatically failing over to look for services in remote datacenters if tags and automatically failing over to look for services in remote datacenters if
no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also
added support for [prepared query templates](/api/query.html#templates) added support for [prepared query templates](/api/query#templates)
which can match names using a prefix match, allowing one template to apply to which can match names using a prefix match, allowing one template to apply to
potentially many services. potentially many services.
@ -247,15 +247,15 @@ endpoints for the given `service`. A Connect-capable endpoint may be
both a proxy for a service or a natively integrated Connect application. both a proxy for a service or a natively integrated Connect application.
The DNS interface does not differentiate the two. The DNS interface does not differentiate the two.
Most services will use a [proxy](/docs/connect/proxies.html) that handles Most services will use a [proxy](/docs/connect/proxies) that handles
service discovery automatically and therefore won't use this DNS format. service discovery automatically and therefore won't use this DNS format.
This DNS format is primarily useful for [Connect-native](/docs/connect/native.html) This DNS format is primarily useful for [Connect-native](/docs/connect/native)
applications. applications.
This endpoint currently only finds services within the same datacenter This endpoint currently only finds services within the same datacenter
and doesn't support tags. This DNS interface will be expanded over time. and doesn't support tags. This DNS interface will be expanded over time.
If you need more complex behavior, please use the If you need more complex behavior, please use the
[catalog API](/api/catalog.html). [catalog API](/api/catalog).
### UDP Based DNS Queries ### UDP Based DNS Queries
@ -276,8 +276,8 @@ for [DNS caching](https://learn.hashicorp.com/consul/security-networking/dns-cac
By default, Consul DNS queries will return a node's local address, even when By default, Consul DNS queries will return a node's local address, even when
being queried from a remote datacenter. If you need to use a different address being queried from a remote datacenter. If you need to use a different address
to reach a node from outside its datacenter, you can configure this behavior to reach a node from outside its datacenter, you can configure this behavior
using the [`advertise-wan`](/docs/agent/options.html#_advertise-wan) and using the [`advertise-wan`](/docs/agent/options#_advertise-wan) and
[`translate_wan_addrs`](/docs/agent/options.html#translate_wan_addrs) configuration [`translate_wan_addrs`](/docs/agent/options#translate_wan_addrs) configuration
options. options.
## Namespaced Services <span class="label-enterprise label-enterprise-lg">Enterprise</span> ## Namespaced Services <span class="label-enterprise label-enterprise-lg">Enterprise</span>
@ -293,7 +293,7 @@ services from other namespaces the following form can be used:
This is the canonical name of a Consul Enterprise service with all parts present. Like This is the canonical name of a Consul Enterprise service with all parts present. Like
Consul OSS some parts may be omitted but which parts depend on the value of the Consul OSS some parts may be omitted but which parts depend on the value of the
[`prefer_namespace` configuration](https://deploy-preview-6909--consul-docs-preview.netlify.com/docs/agent/options.html#dns_prefer_namespace). [`prefer_namespace` configuration](/docs/agent/options#dns_prefer_namespace).
With `prefer_namespace` set to `true` the datacenter may be omitted and will be defaulted With `prefer_namespace` set to `true` the datacenter may be omitted and will be defaulted
to the local agents datacenter: to the local agents datacenter:

28
website/pages/docs/agent/encryption.mdx
View File

@ -12,7 +12,7 @@ description: >-
# Encryption # Encryption
The Consul agent supports encrypting all of its network traffic. The exact The Consul agent supports encrypting all of its network traffic. The exact
method of encryption is described on the [encryption internals page](/docs/internals/security.html). method of encryption is described on the [encryption internals page](/docs/internals/security).
There are two separate encryption systems, one for gossip traffic and one for RPC. There are two separate encryption systems, one for gossip traffic and one for RPC.
To configure the encryption systems on a new cluster, review this following guides to To configure the encryption systems on a new cluster, review this following guides to
@ -27,7 +27,7 @@ starting the Consul agent. The key can be set via the `encrypt` parameter.
~> **WAN Joined Datacenters Note:** If using multiple WAN joined datacenters, be sure to use _the same encryption key_ in all datacenters. ~> **WAN Joined Datacenters Note:** If using multiple WAN joined datacenters, be sure to use _the same encryption key_ in all datacenters.
The key must be 32-bytes, Base64 encoded. As a convenience, Consul provides the The key must be 32-bytes, Base64 encoded. As a convenience, Consul provides the
[`consul keygen`](/docs/commands/keygen.html) command to generate a [`consul keygen`](/docs/commands/keygen) command to generate a
cryptographically suitable key: cryptographically suitable key:
```text ```text
@ -36,7 +36,7 @@ pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=
``` ```
With that key, you can enable encryption on the agent. If encryption is enabled, With that key, you can enable encryption on the agent. If encryption is enabled,
the output of [`consul agent`](/docs/commands/agent.html) will include "Encrypt: true": the output of [`consul agent`](/docs/commands/agent) will include "Encrypt: true":
```text ```text
$ cat encrypt.json $ cat encrypt.json
@ -75,17 +75,17 @@ CA then signs keys for each of the agents, as in
[this tutorial on generating both a CA and signing keys](https://learn.hashicorp.com/consul/security-networking/certificates). [this tutorial on generating both a CA and signing keys](https://learn.hashicorp.com/consul/security-networking/certificates).
TLS can be used to verify the authenticity of the servers or verify the authenticity of clients. TLS can be used to verify the authenticity of the servers or verify the authenticity of clients.
These modes are controlled by the [`verify_outgoing`](/docs/agent/options.html#verify_outgoing), These modes are controlled by the [`verify_outgoing`](/docs/agent/options#verify_outgoing),
[`verify_server_hostname`](/docs/agent/options.html#verify_server_hostname), [`verify_server_hostname`](/docs/agent/options#verify_server_hostname),
and [`verify_incoming`](/docs/agent/options.html#verify_incoming) options, respectively. and [`verify_incoming`](/docs/agent/options#verify_incoming) options, respectively.
If [`verify_outgoing`](/docs/agent/options.html#verify_outgoing) is set, agents verify the If [`verify_outgoing`](/docs/agent/options#verify_outgoing) is set, agents verify the
authenticity of Consul for outgoing connections. Server nodes must present a certificate signed authenticity of Consul for outgoing connections. Server nodes must present a certificate signed
by a common certificate authority present on all agents, set via the agent's by a common certificate authority present on all agents, set via the agent's
[`ca_file`](/docs/agent/options.html#ca_file) and [`ca_path`](/docs/agent/options.html#ca_path) [`ca_file`](/docs/agent/options#ca_file) and [`ca_path`](/docs/agent/options#ca_path)
options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/options.html#cert_file) and [`key_file`](/docs/agent/options.html#key_file). options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/options#cert_file) and [`key_file`](/docs/agent/options#key_file).
If [`verify_server_hostname`](/docs/agent/options.html#verify_server_hostname) is set, then If [`verify_server_hostname`](/docs/agent/options#verify_server_hostname) is set, then
outgoing connections perform hostname verification. All servers must have a certificate outgoing connections perform hostname verification. All servers must have a certificate
valid for `server.<datacenter>.<domain>` or the client will reject the handshake. This is valid for `server.<datacenter>.<domain>` or the client will reject the handshake. This is
a new configuration as of 0.5.1, and it is used to prevent a compromised client from being a new configuration as of 0.5.1, and it is used to prevent a compromised client from being
@ -93,12 +93,12 @@ able to restart in server mode and perform a MITM (Man-In-The-Middle) attack. Ne
to true, and generate the proper certificates, but this is defaulted to false to avoid breaking to true, and generate the proper certificates, but this is defaulted to false to avoid breaking
existing deployments. existing deployments.
If [`verify_incoming`](/docs/agent/options.html#verify_incoming) is set, the servers verify the If [`verify_incoming`](/docs/agent/options#verify_incoming) is set, the servers verify the
authenticity of all incoming connections. All clients must have a valid key pair set using authenticity of all incoming connections. All clients must have a valid key pair set using
[`cert_file`](/docs/agent/options.html#cert_file) and [`cert_file`](/docs/agent/options#cert_file) and
[`key_file`](/docs/agent/options.html#key_file). Servers will [`key_file`](/docs/agent/options#key_file). Servers will
also disallow any non-TLS connections. To force clients to use TLS, also disallow any non-TLS connections. To force clients to use TLS,
[`verify_outgoing`](/docs/agent/options.html#verify_outgoing) must also be set. [`verify_outgoing`](/docs/agent/options#verify_outgoing) must also be set.
TLS is used to secure the RPC calls between agents, but gossip between nodes is done over UDP TLS is used to secure the RPC calls between agents, but gossip between nodes is done over UDP
and is secured using a symmetric key. See above for enabling gossip encryption. and is secured using a symmetric key. See above for enabling gossip encryption.

22
website/pages/docs/agent/index.mdx
View File

@ -16,7 +16,7 @@ information, registers services, runs checks, responds to queries,
and more. The agent must run on every node that is part of a Consul cluster. and more. The agent must run on every node that is part of a Consul cluster.
Any agent may run in one of two modes: client or server. A server Any agent may run in one of two modes: client or server. A server
node takes on the additional responsibility of being part of the [consensus quorum](/docs/internals/consensus.html). node takes on the additional responsibility of being part of the [consensus quorum](/docs/internals/consensus).
These nodes take part in Raft and provide strong consistency and availability in These nodes take part in Raft and provide strong consistency and availability in
the case of failure. The higher burden on the server nodes means that usually they the case of failure. The higher burden on the server nodes means that usually they
should be run on dedicated instances -- they are more resource intensive than a client should be run on dedicated instances -- they are more resource intensive than a client
@ -26,13 +26,13 @@ of their own.
## Running an Agent ## Running an Agent
The agent is started with the [`consul agent`](/docs/commands/agent.html) command. This The agent is started with the [`consul agent`](/docs/commands/agent) command. This
command blocks, running forever or until told to quit. You can test a local agent by following the [Getting Started guides](https://learn.hashicorp.com/consul/getting-started/install?utm_source=consul.io&utm_medium=docs). command blocks, running forever or until told to quit. You can test a local agent by following the [Getting Started guides](https://learn.hashicorp.com/consul/getting-started/install?utm_source=consul.io&utm_medium=docs).
The agent command takes a variety The agent command takes a variety
of [`configuration options`](/docs/agent/options.html#command-line-options), but most have sane defaults. of [`configuration options`](/docs/agent/options#command-line-options), but most have sane defaults.
When running [`consul agent`](/docs/commands/agent.html), you should see output similar to this: When running [`consul agent`](/docs/commands/agent), you should see output similar to this:
```text ```text
$ consul agent -data-dir=/tmp/consul $ consul agent -data-dir=/tmp/consul
@ -50,28 +50,28 @@ $ consul agent -data-dir=/tmp/consul
... ...
``` ```
There are several important messages that [`consul agent`](/docs/commands/agent.html) outputs: There are several important messages that [`consul agent`](/docs/commands/agent) outputs:
- **Node name**: This is a unique name for the agent. By default, this - **Node name**: This is a unique name for the agent. By default, this
is the hostname of the machine, but you may customize it using the is the hostname of the machine, but you may customize it using the
[`-node`](/docs/agent/options.html#_node) flag. [`-node`](/docs/agent/options#_node) flag.
- **Datacenter**: This is the datacenter in which the agent is configured to run. - **Datacenter**: This is the datacenter in which the agent is configured to run.
Consul has first-class support for multiple datacenters; however, to work efficiently, Consul has first-class support for multiple datacenters; however, to work efficiently,
each node must be configured to report its datacenter. The [`-datacenter`](/docs/agent/options.html#_datacenter) each node must be configured to report its datacenter. The [`-datacenter`](/docs/agent/options#_datacenter)
flag can be used to set the datacenter. For single-DC configurations, the agent flag can be used to set the datacenter. For single-DC configurations, the agent
will default to "dc1". will default to "dc1".
- **Server**: This indicates whether the agent is running in server or client mode. - **Server**: This indicates whether the agent is running in server or client mode.
Server nodes have the extra burden of participating in the consensus quorum, Server nodes have the extra burden of participating in the consensus quorum,
storing cluster state, and handling queries. Additionally, a server may be storing cluster state, and handling queries. Additionally, a server may be
in ["bootstrap"](/docs/agent/options.html#_bootstrap_expect) mode. Multiple servers in ["bootstrap"](/docs/agent/options#_bootstrap_expect) mode. Multiple servers
cannot be in bootstrap mode as that would put the cluster in an inconsistent state. cannot be in bootstrap mode as that would put the cluster in an inconsistent state.
- **Client Addr**: This is the address used for client interfaces to the agent. - **Client Addr**: This is the address used for client interfaces to the agent.
This includes the ports for the HTTP and DNS interfaces. By default, this binds only This includes the ports for the HTTP and DNS interfaces. By default, this binds only
to localhost. If you change this address or port, you'll have to specify a `-http-addr` to localhost. If you change this address or port, you'll have to specify a `-http-addr`
whenever you run commands such as [`consul members`](/docs/commands/members.html) to whenever you run commands such as [`consul members`](/docs/commands/members) to
indicate how to reach the agent. Other applications can also use the HTTP address and port indicate how to reach the agent. Other applications can also use the HTTP address and port
[to control Consul](/api). [to control Consul](/api).
@ -114,7 +114,7 @@ with a cluster and how the cluster treats a node.
When an agent is first started, it does not know about any other node in the cluster. When an agent is first started, it does not know about any other node in the cluster.
To discover its peers, it must _join_ the cluster. This is done with the To discover its peers, it must _join_ the cluster. This is done with the
[`join`](/docs/commands/join.html) [`join`](/docs/commands/join)
command or by providing the proper configuration to auto-join on start. Once a node command or by providing the proper configuration to auto-join on start. Once a node
joins, this information is gossiped to the entire cluster, meaning all nodes will joins, this information is gossiped to the entire cluster, meaning all nodes will
eventually be aware of each other. If the agent is a server, existing servers will eventually be aware of each other. If the agent is a server, existing servers will
@ -125,7 +125,7 @@ In this case, unreachable nodes are marked as _failed_. It is impossible to dist
between a network failure and an agent crash, so both cases are handled the same. between a network failure and an agent crash, so both cases are handled the same.
Once a node is marked as failed, this information is updated in the service catalog. Once a node is marked as failed, this information is updated in the service catalog.
-> **Note:** There is some nuance here since this update is only possible if the servers can still [form a quorum](/docs/internals/consensus.html). Once the network recovers or a crashed agent restarts the cluster will repair itself and unmark a node as failed. The health check in the catalog will also be updated to reflect this. -> **Note:** There is some nuance here since this update is only possible if the servers can still [form a quorum](/docs/internals/consensus). Once the network recovers or a crashed agent restarts the cluster will repair itself and unmark a node as failed. The health check in the catalog will also be updated to reflect this.
When a node _leaves_, it specifies its intent to do so, and the cluster When a node _leaves_, it specifies its intent to do so, and the cluster
marks that node as having _left_. Unlike the _failed_ case, all of the marks that node as having _left_. Unlike the _failed_ case, all of the

18
website/pages/docs/agent/kv.mdx
View File

@ -17,7 +17,7 @@ similarities to one.
The Consul KV datastore is located on the servers, but can be accessed by any The Consul KV datastore is located on the servers, but can be accessed by any
agent (client or server). The natively integrated [RPC agent (client or server). The natively integrated [RPC
functionality](/docs/internals/architecture.html) allows clients to forward functionality](/docs/internals/architecture) allows clients to forward
requests to servers, including key/value reads and writes. Part of Consul’s requests to servers, including key/value reads and writes. Part of Consul’s
core design allows data to be replicated automatically across all the servers. core design allows data to be replicated automatically across all the servers.
Having a quorum of servers will decrease the risk of data loss if an outage Having a quorum of servers will decrease the risk of data loss if an outage
@ -30,19 +30,19 @@ Learn.
## Accessing the KV store ## Accessing the KV store
The KV store can be accessed by the [consul kv CLI The KV store can be accessed by the [consul kv CLI
subcommands](/docs/commands/kv.html), [HTTP API](/api/kv.html), and Consul UI. subcommands](/docs/commands/kv), [HTTP API](/api/kv), and Consul UI.
To restrict access, enable and configure To restrict access, enable and configure
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls). [ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
Once the ACL system has been bootstrapped, users and services, will need a Once the ACL system has been bootstrapped, users and services, will need a
valid token with KV [privileges](/docs/agent/acl-rules.html#key-value-rules) to valid token with KV [privileges](/docs/agent/acl-rules#key-value-rules) to
access the the data store, this includes even reads. We recommend creating a access the the data store, this includes even reads. We recommend creating a
token with limited privileges, for example, you could create a token with write token with limited privileges, for example, you could create a token with write
privileges on one key for developers to update the value related to their privileges on one key for developers to update the value related to their
application. application.
The datastore itself is located on the Consul servers in the [data The datastore itself is located on the Consul servers in the [data
directory](/docs/agent/options.html#_data_dir). To ensure data is not lost in directory](/docs/agent/options#_data_dir). To ensure data is not lost in
the event of a complete outage, use the [`consul snapshot`](/docs/commands/snapshot/restore.html) feature to backup the data. the event of a complete outage, use the [`consul snapshot`](/docs/commands/snapshot/restore) feature to backup the data.
## Using Consul KV ## Using Consul KV
@ -50,7 +50,7 @@ Objects are opaque to Consul, meaning there are no restrictions on the type of
object stored in a key/value entry. The main restriction on an object is size - object stored in a key/value entry. The main restriction on an object is size -
the maximum is 512 KB. Due to the maximum object size and main use cases, you the maximum is 512 KB. Due to the maximum object size and main use cases, you
should not need extra storage; the general [sizing should not need extra storage; the general [sizing
recommendations](/docs/commands/snapshot/restore.html) are usually sufficient. recommendations](/docs/commands/snapshot/restore) are usually sufficient.
Keys, like objects are not restricted by type and can include any character. Keys, like objects are not restricted by type and can include any character.
However, we recommend using URL-safe chars - `[a-zA-Z0-9-_]` with the However, we recommend using URL-safe chars - `[a-zA-Z0-9-_]` with the
@ -76,9 +76,9 @@ to be initiated on value changes to a Consul key.
### Watches ### Watches
Consul KV can also be extended with the use of watches. Consul KV can also be extended with the use of watches.
[Watches](/docs/agent/watches.html) are a way to monitor data for updates. When [Watches](/docs/agent/watches) are a way to monitor data for updates. When
an update is detected, an external handler is invoked. To use watches with the an update is detected, an external handler is invoked. To use watches with the
KV store the [key](/docs/agent/watches.html#key) watch type should be used. KV store the [key](/docs/agent/watches#key) watch type should be used.
### Consul Sessions ### Consul Sessions
@ -88,7 +88,7 @@ API supports an `acquire` and `release` operation. The `acquire` operation acts
like a Check-And-Set operation. On success, there is a key update and an like a Check-And-Set operation. On success, there is a key update and an
increment to the `LockIndex` and the session value is updated to reflect the increment to the `LockIndex` and the session value is updated to reflect the
session holding the lock. Review the session documentation for more information session holding the lock. Review the session documentation for more information
on the [integration](/docs/internals/sessions.html#k-v-integration). on the [integration](/docs/internals/sessions#k-v-integration).
Review the following guides to learn how to use Consul sessions for [application leader election](https://learn.hashicorp.com/consul/developer-configuration/elections) and Review the following guides to learn how to use Consul sessions for [application leader election](https://learn.hashicorp.com/consul/developer-configuration/elections) and
to [build distributed semaphores](https://learn.hashicorp.com/consul/developer-configuration/semaphore). to [build distributed semaphores](https://learn.hashicorp.com/consul/developer-configuration/semaphore).

90
website/pages/docs/agent/options.mdx
View File

@ -38,7 +38,7 @@ Consul also supports reloading configuration when it receives the
SIGHUP signal. Not all changes are respected, but those that are SIGHUP signal. Not all changes are respected, but those that are
documented below in the documented below in the
[Reloadable Configuration](#reloadable-configuration) section. The [Reloadable Configuration](#reloadable-configuration) section. The
[reload command](/docs/commands/reload.html) can also be used to trigger a [reload command](/docs/commands/reload) can also be used to trigger a
configuration reload. configuration reload.
You can test the following configuration options by following the [Getting Started](https://learn.hashicorp.com/consul/getting-started/install?utm_source=consul.io&utm_medium=docs) guides to install a local agent. You can test the following configuration options by following the [Getting Started](https://learn.hashicorp.com/consul/getting-started/install?utm_source=consul.io&utm_medium=docs) guides to install a local agent.
@ -93,10 +93,10 @@ The options below are all specified on the command-line.
- `-bind` ((#\_bind) - The address that should be bound to for internal - `-bind` ((#\_bind) - The address that should be bound to for internal
cluster communications. This is an IP address that should be reachable by all other cluster communications. This is an IP address that should be reachable by all other
nodes in the cluster. By default, this is "0.0.0.0", meaning Consul will bind to nodes in the cluster. By default, this is "0.0.0.0", meaning Consul will bind to
all addresses on the local machine and will [advertise](/docs/agent/options.html#_advertise) all addresses on the local machine and will [advertise](/docs/agent/options#_advertise)
the private IPv4 address to the rest of the cluster. If there are multiple private the private IPv4 address to the rest of the cluster. If there are multiple private
IPv4 addresses available, Consul will exit with an error at startup. If you specify IPv4 addresses available, Consul will exit with an error at startup. If you specify
`"[::]"`, Consul will [advertise](/docs/agent/options.html#_advertise) the public `"[::]"`, Consul will [advertise](/docs/agent/options#_advertise) the public
IPv6 address. If there are multiple public IPv6 addresses available, Consul will IPv6 address. If there are multiple public IPv6 addresses available, Consul will
exit with an error at startup. Consul uses both TCP and UDP and the same port for exit with an error at startup. Consul uses both TCP and UDP and the same port for
both. If you have any firewalls, be sure to allow both protocols. In Consul 1.0 both. If you have any firewalls, be sure to allow both protocols. In Consul 1.0
@ -184,7 +184,7 @@ The options below are all specified on the command-line.
- `-dev` ((#\_dev)) - Enable development server mode. This is useful for - `-dev` ((#\_dev)) - Enable development server mode. This is useful for
quickly starting a Consul agent with all persistence options turned off, enabling quickly starting a Consul agent with all persistence options turned off, enabling
an in-memory server which can be used for rapid prototyping or developing against an in-memory server which can be used for rapid prototyping or developing against
the API. In this mode, [Connect is enabled](/docs/connect/configuration.html) and the API. In this mode, [Connect is enabled](/docs/connect/configuration) and
will by default create a new root CA certificate on startup. This mode is **not** will by default create a new root CA certificate on startup. This mode is **not**
intended for production use as it does not write any data to disk. The gRPC port intended for production use as it does not write any data to disk. The gRPC port
is also defaulted to `8502` in this mode. is also defaulted to `8502` in this mode.
@ -217,7 +217,7 @@ The options below are all specified on the command-line.
no alternate domain is used. no alternate domain is used.
- `-enable-script-checks` ((#\_enable_script_checks)) This controls whether - `-enable-script-checks` ((#\_enable_script_checks)) This controls whether
[health checks that execute scripts](/docs/agent/checks.html) are enabled on this [health checks that execute scripts](/docs/agent/checks) are enabled on this
agent, and defaults to `false` so operators must opt-in to allowing these. This agent, and defaults to `false` so operators must opt-in to allowing these. This
was added in Consul 0.9.0. was added in Consul 0.9.0.
@ -234,7 +234,7 @@ The options below are all specified on the command-line.
- `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption - `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption
of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The
easiest way to create an encryption key is to use [`consul keygen`](/docs/commands/keygen.html). easiest way to create an encryption key is to use [`consul keygen`](/docs/commands/keygen).
All nodes within a cluster must share the same encryption key to communicate. The All nodes within a cluster must share the same encryption key to communicate. The
provided key is automatically persisted to the data directory and loaded automatically provided key is automatically persisted to the data directory and loaded automatically
whenever the agent is restarted. This means that to encrypt Consul's gossip protocol, whenever the agent is restarted. This means that to encrypt Consul's gossip protocol,
@ -337,7 +337,7 @@ The options below are all specified on the command-line.
As of Consul 0.9.1, `retry-join` accepts a unified interface using the As of Consul 0.9.1, `retry-join` accepts a unified interface using the
[go-discover](https://github.com/hashicorp/go-discover) library for doing [go-discover](https://github.com/hashicorp/go-discover) library for doing
automatic cluster joining using cloud metadata. For more information, see automatic cluster joining using cloud metadata. For more information, see
the [Cloud Auto-join page](/docs/agent/cloud-auto-join.html). the [Cloud Auto-join page](/docs/agent/cloud-auto-join).
```shell ```shell
# Using Cloud Auto-Joining # Using Cloud Auto-Joining
@ -380,7 +380,7 @@ The options below are all specified on the command-line.
- `-log-level` ((#\_log_level)) - The level of logging to show after the - `-log-level` ((#\_log_level)) - The level of logging to show after the
Consul agent has started. This defaults to "info". The available log levels are Consul agent has started. This defaults to "info". The available log levels are
"trace", "debug", "info", "warn", and "err". You can always connect to an agent "trace", "debug", "info", "warn", and "err". You can always connect to an agent
via [`consul monitor`](/docs/commands/monitor.html) and use any log level. Also, via [`consul monitor`](/docs/commands/monitor) and use any log level. Also,
the log level can be changed during a config reload. the log level can be changed during a config reload.
- `-log-json` ((#\_log_json)) - This flag enables the agent to output logs - `-log-json` ((#\_log_json)) - This flag enables the agent to output logs
@ -417,7 +417,7 @@ The options below are all specified on the command-line.
to close the agent or `SIGHUP` to update check definite to close the agent or `SIGHUP` to update check definite
- `-protocol` ((#\_protocol)) - The Consul protocol version to use. Consul - `-protocol` ((#\_protocol)) - The Consul protocol version to use. Consul
agents speak protocol 2 by default, however agents will automatically use protocol > 2 when speaking to compatible agents. This should be set only when [upgrading](/docs/upgrading.html). You can view the protocol versions supported by Consul by running `consul -v`. agents speak protocol 2 by default, however agents will automatically use protocol > 2 when speaking to compatible agents. This should be set only when [upgrading](/docs/upgrading). You can view the protocol versions supported by Consul by running `consul -v`.
- `-primary-gateway` ((#\_primary_gateway)) - Similar to [`retry-join-wan`](#_retry_join_wan) - `-primary-gateway` ((#\_primary_gateway)) - Similar to [`retry-join-wan`](#_retry_join_wan)
but allows retrying discovery of fallback addresses for the mesh gateways in the but allows retrying discovery of fallback addresses for the mesh gateways in the
@ -428,7 +428,7 @@ The options below are all specified on the command-line.
- `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version - `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version
of the Raft consensus protocol used for server communications. This must be set of the Raft consensus protocol used for server communications. This must be set
to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific.html#raft-protocol-version-compatibility) for more details. to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific#raft-protocol-version-compatibility) for more details.
- `-recursor` ((#\_recursor)) - Specifies the address of an upstream DNS - `-recursor` ((#\_recursor)) - Specifies the address of an upstream DNS
server. This option may be provided multiple times, and is functionally equivalent server. This option may be provided multiple times, and is functionally equivalent
@ -507,8 +507,8 @@ as a single JSON object with configuration within it.
Configuration files are used for more than just setting up the agent, Configuration files are used for more than just setting up the agent,
they are also used to provide check and service definitions. These are used they are also used to provide check and service definitions. These are used
to announce the availability of system servers to the rest of the cluster. to announce the availability of system servers to the rest of the cluster.
They are documented separately under [check configuration](/docs/agent/checks.html) and They are documented separately under [check configuration](/docs/agent/checks) and
[service configuration](/docs/agent/services.html) respectively. The service and check [service configuration](/docs/agent/services) respectively. The service and check
definitions support being updated during a reload. definitions support being updated during a reload.
#### Example Configuration File #### Example Configuration File
@ -627,8 +627,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `enable_token_replication` ((#acl_enable_token_replication)) - By default - `enable_token_replication` ((#acl_enable_token_replication)) - By default
secondary Consul datacenters will perform replication of only ACL policies and secondary Consul datacenters will perform replication of only ACL policies and
roles. Setting this configuration will will enable ACL token replication and roles. Setting this configuration will will enable ACL token replication and
allow for the creation of both [local tokens](/api/acl/tokens.html#local) and allow for the creation of both [local tokens](/api/acl/tokens#local) and
[auth methods](/docs/acl/acl-auth-methods.html) in connected secondary datacenters. [auth methods](/docs/acl/acl-auth-methods) in connected secondary datacenters.
- `enable_token_persistence` ((#acl_enable_token_persistence)) - Either - `enable_token_persistence` ((#acl_enable_token_persistence)) - Either
`true` or `false`. When `true` tokens set using the API will be persisted to `true` or `false`. When `true` tokens set using the API will be persisted to
@ -670,7 +670,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `replication` ((#acl_tokens_replication)) - The ACL token used to - `replication` ((#acl_tokens_replication)) - The ACL token used to
authorize secondary datacenters with the primary datacenter for replication authorize secondary datacenters with the primary datacenter for replication
operations. This token is required for servers outside the [`primary_datacenter`](#primary_datacenter) when ACLs are enabled. This token may be provided later using the [agent token API](/api/agent.html#update-acl-tokens) on each server. This token must have at least "read" permissions on ACL data but if ACL token replication is enabled then it must have "write" permissions. This also enables Connect replication, for which the token will require both operator "write" and intention "read" permissions for replicating CA and Intention data. operations. This token is required for servers outside the [`primary_datacenter`](#primary_datacenter) when ACLs are enabled. This token may be provided later using the [agent token API](/api/agent#update-acl-tokens) on each server. This token must have at least "read" permissions on ACL data but if ACL token replication is enabled then it must have "write" permissions. This also enables Connect replication, for which the token will require both operator "write" and intention "read" permissions for replicating CA and Intention data.
- `managed_service_provider` ((#acl_tokens_managed_service_provider)) - **(Enterprise Only)** An - `managed_service_provider` ((#acl_tokens_managed_service_provider)) - **(Enterprise Only)** An
array of ACL tokens used by Consul managed service providers for cluster operations. array of ACL tokens used by Consul managed service providers for cluster operations.
@ -752,12 +752,12 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
using this ACL replication using this token to retrieve and replicate the ACLs using this ACL replication using this token to retrieve and replicate the ACLs
to the non-authoritative local datacenter. In Consul 0.9.1 and later you can enable to the non-authoritative local datacenter. In Consul 0.9.1 and later you can enable
ACL replication using [`enable_acl_replication`](#enable_acl_replication) and then ACL replication using [`enable_acl_replication`](#enable_acl_replication) and then
set the token later using the [agent token API](/api/agent.html#update-acl-tokens) set the token later using the [agent token API](/api/agent#update-acl-tokens)
on each server. If the `acl_replication_token` is set in the config, it will automatically on each server. If the `acl_replication_token` is set in the config, it will automatically
set [`enable_acl_replication`](#enable_acl_replication) to true for backward compatibility. set [`enable_acl_replication`](#enable_acl_replication) to true for backward compatibility.
If there's a partition or other outage affecting the authoritative datacenter, and the If there's a partition or other outage affecting the authoritative datacenter, and the
[`acl_down_policy`](/docs/agent/options.html#acl_down_policy) is set to "extend-cache", tokens not [`acl_down_policy`](/docs/agent/options#acl_down_policy) is set to "extend-cache", tokens not
in the cache can be resolved during the outage using the replicated set of ACLs. in the cache can be resolved during the outage using the replicated set of ACLs.
- `acl_token` ((#acl_token_legacy)) - **Deprecated in Consul 1.4.0. See - `acl_token` ((#acl_token_legacy)) - **Deprecated in Consul 1.4.0. See
@ -814,7 +814,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
Consul servers. When these keys are provided as configuration, they will only be Consul servers. When these keys are provided as configuration, they will only be
respected on bootstrapping. If they are not provided, the defaults will be used. respected on bootstrapping. If they are not provided, the defaults will be used.
In order to change the value of these options after bootstrapping, you will need In order to change the value of these options after bootstrapping, you will need
to use the [Consul Operator Autopilot](https://www.consul.io/docs/commands/operator/autopilot.html) to use the [Consul Operator Autopilot](/docs/commands/operator/autopilot)
command. For more information about Autopilot, see the [Autopilot Guide](https://learn.hashicorp.com/consul/day-2-operations/autopilot). command. For more information about Autopilot, see the [Autopilot Guide](https://learn.hashicorp.com/consul/day-2-operations/autopilot).
The following sub-keys are available: The following sub-keys are available:
@ -930,7 +930,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
the Consul server gains leadership. This option is only applicable to server the Consul server gains leadership. This option is only applicable to server
nodes. Each bootstrap entry will be created only if it does not exist. When reloading, nodes. Each bootstrap entry will be created only if it does not exist. When reloading,
any new entries that have been added to the configuration will be processed. any new entries that have been added to the configuration will be processed.
See the [configuration entry docs](/docs/agent/config_entries.html) for more See the [configuration entry docs](/docs/agent/config_entries) for more
details about the contents of each entry. details about the contents of each entry.
- `connect` This object allows setting options for the Connect feature. - `connect` This object allows setting options for the Connect feature.
@ -947,12 +947,12 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `ca_provider` ((#connect_ca_provider)) Controls which CA provider to - `ca_provider` ((#connect_ca_provider)) Controls which CA provider to
use for Connect's CA. Currently only the `consul` and `vault` providers are supported. use for Connect's CA. Currently only the `consul` and `vault` providers are supported.
This is only used when initially bootstrapping the cluster. For an existing cluster, This is only used when initially bootstrapping the cluster. For an existing cluster,
use the [Update CA Configuration Endpoint](/api/connect/ca.html#update-ca-configuration). use the [Update CA Configuration Endpoint](/api/connect/ca#update-ca-configuration).
- `ca_config` ((#connect_ca_config)) An object which allows setting different - `ca_config` ((#connect_ca_config)) An object which allows setting different
config options based on the CA provider chosen. This is only used when initially config options based on the CA provider chosen. This is only used when initially
bootstrapping the cluster. For an existing cluster, use the [Update CA Configuration bootstrapping the cluster. For an existing cluster, use the [Update CA Configuration
Endpoint](/api/connect/ca.html#update-ca-configuration). Endpoint](/api/connect/ca#update-ca-configuration).
The following providers are supported: The following providers are supported:
@ -1180,25 +1180,25 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
in seconds, default value is 600, ie: 10 minutes. in seconds, default value is 600, ie: 10 minutes.
- `use_cache` ((#dns_use_cache)) - When set to true, DNS resolution will - `use_cache` ((#dns_use_cache)) - When set to true, DNS resolution will
use the agent cache described in [agent caching](/api/features/caching.html). use the agent cache described in [agent caching](/api/features/caching).
This setting affects all service and prepared queries DNS requests. Implies [`allow_stale`](#allow_stale) This setting affects all service and prepared queries DNS requests. Implies [`allow_stale`](#allow_stale)
- `cache_max_age` ((#dns_cache_max_age)) - When [use_cache](#dns_use_cache) - `cache_max_age` ((#dns_cache_max_age)) - When [use_cache](#dns_use_cache)
is enabled, the agent will attempt to re-fetch the result from the servers if is enabled, the agent will attempt to re-fetch the result from the servers if
the cached value is older than this duration. See: [agent caching](/api/features/caching.html). the cached value is older than this duration. See: [agent caching](/api/features/caching).
- `prefer_namespace` ((#dns_prefer_namespace)) - **(Enterprise Only)** - `prefer_namespace` ((#dns_prefer_namespace)) - **(Enterprise Only)**
When set to true, in a DNS query for a service, the label between the domain When set to true, in a DNS query for a service, the label between the domain
and the `service` label will be treated as a namespace name instead of a datacenter. and the `service` label will be treated as a namespace name instead of a datacenter.
When set to false, the default, the behavior will be the same as non-Enterprise When set to false, the default, the behavior will be the same as non-Enterprise
versions and will assume the label is the datacenter. See: [this section](/docs/agent/dns.html#namespaced-services-enterprise) versions and will assume the label is the datacenter. See: [this section](/docs/agent/dns#namespaced-services-enterprise)
for more details. for more details.
- `domain` Equivalent to the [`-domain` command-line flag](#_domain). - `domain` Equivalent to the [`-domain` command-line flag](#_domain).
- `enable_acl_replication` When set on a Consul server, enables ACL replication without having to set - `enable_acl_replication` When set on a Consul server, enables ACL replication without having to set
the replication token via [`acl_replication_token`](#acl_replication_token). Instead, enable ACL replication the replication token via [`acl_replication_token`](#acl_replication_token). Instead, enable ACL replication
and then introduce the token using the [agent token API](/api/agent.html#update-acl-tokens) on each server. and then introduce the token using the [agent token API](/api/agent#update-acl-tokens) on each server.
See [`acl_replication_token`](#acl_replication_token) for more details. See [`acl_replication_token`](#acl_replication_token) for more details.
- `enable_agent_tls_for_checks` When set, uses a subset of the agent's TLS configuration (`key_file`, - `enable_agent_tls_for_checks` When set, uses a subset of the agent's TLS configuration (`key_file`,
@ -1227,13 +1227,13 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `encrypt_verify_incoming` - This is an optional - `encrypt_verify_incoming` - This is an optional
parameter that can be used to disable enforcing encryption for incoming gossip parameter that can be used to disable enforcing encryption for incoming gossip
in order to upshift from unencrypted to encrypted gossip on a running cluster. in order to upshift from unencrypted to encrypted gossip on a running cluster.
See [this section](/docs/agent/encryption.html#configuring-gossip-encryption-on-an-existing-cluster) See [this section](/docs/agent/encryption#configuring-gossip-encryption-on-an-existing-cluster)
for more information. Defaults to true. for more information. Defaults to true.
- `encrypt_verify_outgoing` - This is an optional - `encrypt_verify_outgoing` - This is an optional
parameter that can be used to disable enforcing encryption for outgoing gossip parameter that can be used to disable enforcing encryption for outgoing gossip
in order to upshift from unencrypted to encrypted gossip on a running cluster. in order to upshift from unencrypted to encrypted gossip on a running cluster.
See [this section](/docs/agent/encryption.html#configuring-gossip-encryption-on-an-existing-cluster) See [this section](/docs/agent/encryption#configuring-gossip-encryption-on-an-existing-cluster)
for more information. Defaults to true. for more information. Defaults to true.
- `disable_keyring_file` - Equivalent to the - `disable_keyring_file` - Equivalent to the
@ -1372,8 +1372,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `rpc_max_conns_per_client` - Configures a limit of how many concurrent TCP connections a single source IP address is allowed to open to a single server. It affects both clients connections and other server connections. In general Consul clients multiplex many RPC calls over a single TCP connection so this can typically be kept low. It needs to be more than one though since servers open at least one additional connection for raft RPC, possibly more for WAN federation when using network areas, and snapshot requests from clients run over a separate TCP conn. A reasonably low limit significantly reduces the ability of an unauthenticated attacker to consume unbounded resources by holding open many connections. You may need to increase this if WAN federated servers connect via proxies or NAT gateways or similar causing many legitimate connections from a single source IP. Default value is `100` which is designed to be extremely conservative to limit issues with certain deployment patterns. Most deployments can probably reduce this safely. 100 connections on modern server hardware should not cause a significant impact on resource usage from an unauthenticated attacker though. - `rpc_max_conns_per_client` - Configures a limit of how many concurrent TCP connections a single source IP address is allowed to open to a single server. It affects both clients connections and other server connections. In general Consul clients multiplex many RPC calls over a single TCP connection so this can typically be kept low. It needs to be more than one though since servers open at least one additional connection for raft RPC, possibly more for WAN federation when using network areas, and snapshot requests from clients run over a separate TCP conn. A reasonably low limit significantly reduces the ability of an unauthenticated attacker to consume unbounded resources by holding open many connections. You may need to increase this if WAN federated servers connect via proxies or NAT gateways or similar causing many legitimate connections from a single source IP. Default value is `100` which is designed to be extremely conservative to limit issues with certain deployment patterns. Most deployments can probably reduce this safely. 100 connections on modern server hardware should not cause a significant impact on resource usage from an unauthenticated attacker though.
- `rpc_rate` - Configures the RPC rate limiter on Consul _clients_ by setting the maximum request rate that this agent is allowed to make for RPC requests to Consul servers, in requests per second. Defaults to infinite, which disables rate limiting. - `rpc_rate` - Configures the RPC rate limiter on Consul _clients_ by setting the maximum request rate that this agent is allowed to make for RPC requests to Consul servers, in requests per second. Defaults to infinite, which disables rate limiting.
- `rpc_max_burst` - The size of the token bucket used to recharge the RPC rate limiter on Consul _clients_. Defaults to 1000 tokens, and each token is good for a single RPC call to a Consul server. See https://en.wikipedia.org/wiki/Token_bucket for more details about how token bucket rate limiters operate. - `rpc_max_burst` - The size of the token bucket used to recharge the RPC rate limiter on Consul _clients_. Defaults to 1000 tokens, and each token is good for a single RPC call to a Consul server. See https://en.wikipedia.org/wiki/Token_bucket for more details about how token bucket rate limiters operate.
- `kv_max_value_size` - **(Advanced)** Configures the maximum number of bytes for a kv request body to the [`/v1/kv`](/api/kv.html) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration. This option affects the txn endpoint too, but Consul 1.7.2 introduced `txn_max_req_len` which is the preferred way to set the limit for the txn endpoint. If both limits are set, the higher one takes precedence. - `kv_max_value_size` - **(Advanced)** Configures the maximum number of bytes for a kv request body to the [`/v1/kv`](/api/kv) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration. This option affects the txn endpoint too, but Consul 1.7.2 introduced `txn_max_req_len` which is the preferred way to set the limit for the txn endpoint. If both limits are set, the higher one takes precedence.
- `txn_max_req_len` - **(Advanced)** Configures the maximum number of bytes for a transaction request body to the [`/v1/txn`](/api/txn.html) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration. - `txn_max_req_len` - **(Advanced)** Configures the maximum number of bytes for a transaction request body to the [`/v1/txn`](/api/txn) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration.
- `log_file` Equivalent to the [`-log-file` command-line flag](#_log_file). - `log_file` Equivalent to the [`-log-file` command-line flag](#_log_file).
@ -1405,20 +1405,20 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
} }
``` ```
- `performance` Available in Consul 0.7 and later, this is a nested object that allows tuning the performance of different subsystems in Consul. See the [Server Performance](/docs/install/performance.html) documentation for more details. The following parameters are available: - `performance` Available in Consul 0.7 and later, this is a nested object that allows tuning the performance of different subsystems in Consul. See the [Server Performance](/docs/install/performance) documentation for more details. The following parameters are available:
- `leave_drain_time` - A duration that a server will dwell during a graceful leave in order to allow requests to be retried against other Consul servers. Under normal circumstances, this can prevent clients from experiencing "no leader" errors when performing a rolling update of the Consul servers. This was added in Consul 1.0. Must be a duration value such as 10s. Defaults to 5s. - `leave_drain_time` - A duration that a server will dwell during a graceful leave in order to allow requests to be retried against other Consul servers. Under normal circumstances, this can prevent clients from experiencing "no leader" errors when performing a rolling update of the Consul servers. This was added in Consul 1.0. Must be a duration value such as 10s. Defaults to 5s.
- `raft_multiplier` - An integer multiplier used by Consul servers to scale key Raft timing parameters. Omitting this value or setting it to 0 uses default timing described below. Lower values are used to tighten timing and increase sensitivity while higher values relax timings and reduce sensitivity. Tuning this affects the time it takes Consul to detect leader failures and to perform leader elections, at the expense of requiring more network and CPU resources for better performance. - `raft_multiplier` - An integer multiplier used by Consul servers to scale key Raft timing parameters. Omitting this value or setting it to 0 uses default timing described below. Lower values are used to tighten timing and increase sensitivity while higher values relax timings and reduce sensitivity. Tuning this affects the time it takes Consul to detect leader failures and to perform leader elections, at the expense of requiring more network and CPU resources for better performance.
By default, Consul will use a lower-performance timing that's suitable By default, Consul will use a lower-performance timing that's suitable
for [minimal Consul servers](/docs/install/performance.html#minimum), currently equivalent for [minimal Consul servers](/docs/install/performance#minimum), currently equivalent
to setting this to a value of 5 (this default may be changed in future versions of Consul, to setting this to a value of 5 (this default may be changed in future versions of Consul,
depending if the target minimum server profile changes). Setting this to a value of 1 will depending if the target minimum server profile changes). Setting this to a value of 1 will
configure Raft to its highest-performance mode, equivalent to the default timing of Consul configure Raft to its highest-performance mode, equivalent to the default timing of Consul
prior to 0.7, and is recommended for [production Consul servers](/docs/install/performance.html#production). prior to 0.7, and is recommended for [production Consul servers](/docs/install/performance#production).
See the note on [last contact](/docs/install/performance.html#last-contact) timing for more See the note on [last contact](/docs/install/performance#last-contact) timing for more
details on tuning this parameter. The maximum allowed value is 10. details on tuning this parameter. The maximum allowed value is 10.
- `rpc_hold_timeout` - A duration that a client - `rpc_hold_timeout` - A duration that a client
@ -1450,16 +1450,16 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `server` ((#server_rpc_port)) - Server RPC address. Default 8300. TCP - `server` ((#server_rpc_port)) - Server RPC address. Default 8300. TCP
only. only.
- `sidecar_min_port` ((#sidecar_min_port)) - Inclusive minimum port number - `sidecar_min_port` ((#sidecar_min_port)) - Inclusive minimum port number
to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service.html). to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service).
Default 21000. Set to `0` to disable automatic port assignment. Default 21000. Set to `0` to disable automatic port assignment.
- `sidecar_max_port` ((#sidecar_max_port)) - Inclusive maximum port number - `sidecar_max_port` ((#sidecar_max_port)) - Inclusive maximum port number
to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service.html). to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service).
Default 21255. Set to `0` to disable automatic port assignment. Default 21255. Set to `0` to disable automatic port assignment.
- `expose_min_port` ((#expose_min_port)) - Inclusive minimum port number - `expose_min_port` ((#expose_min_port)) - Inclusive minimum port number
to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference). to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration#expose-paths-configuration-reference).
Default 21500. Set to `0` to disable automatic port assignment. Default 21500. Set to `0` to disable automatic port assignment.
- `expose_max_port` ((#expose_max_port)) - Inclusive maximum port number - `expose_max_port` ((#expose_max_port)) - Inclusive maximum port number
to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration.html#expose-paths-configuration-reference). to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration#expose-paths-configuration-reference).
Default 21755. Set to `0` to disable automatic port assignment. Default 21755. Set to `0` to disable automatic port assignment.
- `primary_datacenter` ((#primary_datacenter)) - This designates the datacenter - `primary_datacenter` ((#primary_datacenter)) - This designates the datacenter
@ -1709,7 +1709,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
2 times the interval of scrape of Prometheus, but you might also put a very high 2 times the interval of scrape of Prometheus, but you might also put a very high
retention time such as a few days (for instance 744h to enable retention to 31 retention time such as a few days (for instance 744h to enable retention to 31
days). Fetching the metrics using prometheus can then be performed using the days). Fetching the metrics using prometheus can then be performed using the
[`/v1/agent/metrics?format=prometheus`](/api/agent.html#view-metrics) endpoint. [`/v1/agent/metrics?format=prometheus`](/api/agent#view-metrics) endpoint.
The format is compatible natively with prometheus. When running in this mode, The format is compatible natively with prometheus. When running in this mode,
it is recommended to also enable the option `disable_hostname` ((#telemetry-disable_hostname)) it is recommended to also enable the option `disable_hostname` ((#telemetry-disable_hostname))
to avoid having prefixed metrics with hostname. Consul does not use the default to avoid having prefixed metrics with hostname. Consul does not use the default
@ -1767,11 +1767,11 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
The following endpoints translate addresses: The following endpoints translate addresses:
- [`/v1/catalog/nodes`](/api/catalog.html#catalog_nodes) - [`/v1/catalog/nodes`](/api/catalog#catalog_nodes)
- [`/v1/catalog/node/<node>`](/api/catalog.html#catalog_node) - [`/v1/catalog/node/<node>`](/api/catalog#catalog_node)
- [`/v1/catalog/service/<service>`](/api/catalog.html#catalog_service) - [`/v1/catalog/service/<service>`](/api/catalog#catalog_service)
- [`/v1/health/service/<service>`](/api/health.html#health_service) - [`/v1/health/service/<service>`](/api/health#health_service)
- [`/v1/query/<query or name>/execute`](/api/query.html#execute) - [`/v1/query/<query or name>/execute`](/api/query#execute)
- `ui` - Equivalent to the [`-ui`](#_ui) command-line flag. - `ui` - Equivalent to the [`-ui`](#_ui) command-line flag.
@ -1853,7 +1853,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `watches` - Watches is a list of watch specifications which - `watches` - Watches is a list of watch specifications which
allow an external process to be automatically invoked when a particular data view allow an external process to be automatically invoked when a particular data view
is updated. See the [watch documentation](/docs/agent/watches.html) for more detail. is updated. See the [watch documentation](/docs/agent/watches) for more detail.
Watches can be modified when the configuration is reloaded. Watches can be modified when the configuration is reloaded.
## Ports Used ## Ports Used
@ -1861,7 +1861,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
Consul requires up to 6 different ports to work properly, some on Consul requires up to 6 different ports to work properly, some on
TCP, UDP, or both protocols. TCP, UDP, or both protocols.
Review the [required ports](/docs/install/ports.html) table for a list of Review the [required ports](/docs/install/ports) table for a list of
required ports and their default settings. required ports and their default settings.
## Reloadable Configuration ## Reloadable Configuration

6
website/pages/docs/agent/sentinel.mdx
View File

@ -21,7 +21,7 @@ policies to support full conditional logic and integration with external systems
Sentinel policies are applied during writes to the KV Store. Sentinel policies are applied during writes to the KV Store.
An optional `sentinel` field specifying code and enforcement level can be added to [ACL policy definitions](/docs/agent/acl-rules.html#sentinel-integration) for Consul KV. The following policy ensures that the value written during a KV update must end with "dc1". An optional `sentinel` field specifying code and enforcement level can be added to [ACL policy definitions](/docs/agent/acl-rules#sentinel-integration) for Consul KV. The following policy ensures that the value written during a KV update must end with "dc1".
```text ```text
key "datacenter_name" { key "datacenter_name" {
@ -49,10 +49,10 @@ Consul passes some context as variables into Sentinel, which are available to us
#### Variables injected during KV store writes #### Variables injected during KV store writes
| Variable Name | Type | Description | | Variable Name | Type | Description |
| ------------- | -------- | --------------------------- | | ------------- | -------- | ---------------------- |
| `key` | `string` | Key being written | | `key` | `string` | Key being written |
| `value` | `string` | Value being written | | `value` | `string` | Value being written |
| `flags` | `uint64` | [Flags](/api/kv.html#flags) | | `flags` | `uint64` | [Flags](/api/kv#flags) |
## Sentinel Examples ## Sentinel Examples

32
website/pages/docs/agent/services.mdx
View File

@ -116,7 +116,7 @@ can be used to distinguish between `primary` or `secondary` nodes,
different versions, or any other service level labels. different versions, or any other service level labels.
We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames)
for service definition names and tags for [compatibility with external DNS](/docs/agent/services.html#service-and-tag-names-with-dns) for service definition names and tags for [compatibility with external DNS](/docs/agent/services#service-and-tag-names-with-dns)
The `address` field can be used to specify a service-specific IP address. By The `address` field can be used to specify a service-specific IP address. By
default, the IP address of the agent is used, and this does not need to be provided. default, the IP address of the agent is used, and this does not need to be provided.
@ -134,12 +134,12 @@ and all the instances of a given service have their own copy of it.
Services may also contain a `token` field to provide an ACL token. This token is Services may also contain a `token` field to provide an ACL token. This token is
used for any interaction with the catalog for the service, including used for any interaction with the catalog for the service, including
[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. [anti-entropy syncs](/docs/internals/anti-entropy) and deregistration.
The `enable_tag_override` can optionally be specified to disable the The `enable_tag_override` can optionally be specified to disable the
anti-entropy feature for this service. If `enable_tag_override` is set to anti-entropy feature for this service. If `enable_tag_override` is set to
`TRUE` then external agents can update this service in the `TRUE` then external agents can update this service in the
[catalog](/api/catalog.html) and modify the tags. Subsequent [catalog](/api/catalog) and modify the tags. Subsequent
local sync operations by this agent will ignore the updated tags. For local sync operations by this agent will ignore the updated tags. For
example, if an external agent modified both the tags and the port for example, if an external agent modified both the tags and the port for
this service and `enable_tag_override` was set to `TRUE` then after the next this service and `enable_tag_override` was set to `TRUE` then after the next
@ -157,7 +157,7 @@ configuration items are independent of one another. Updating the tags
for the service registered on one node is independent of the same for the service registered on one node is independent of the same
service (by name) registered on another node. If `enable_tag_override` is service (by name) registered on another node. If `enable_tag_override` is
not specified the default value is false. See [anti-entropy not specified the default value is false. See [anti-entropy
syncs](/docs/internals/anti-entropy.html) for more info. syncs](/docs/internals/anti-entropy) for more info.
For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0 For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0
supports both `enable_tag_override` and `enableTagOverride` but the latter is supports both `enable_tag_override` and `enableTagOverride` but the latter is
@ -173,30 +173,30 @@ node has any failing system-level check, the DNS interface will omit that
node from any service query. node from any service query.
There are several check types that have differing required options as There are several check types that have differing required options as
[documented here](/docs/agent/checks.html). The check name is automatically [documented here](/docs/agent/checks). The check name is automatically
generated as `service:<service-id>`. If there are multiple service checks generated as `service:<service-id>`. If there are multiple service checks
registered, the ID will be generated as `service:<service-id>:<num>` where registered, the ID will be generated as `service:<service-id>:<num>` where
`<num>` is an incrementing number starting from `1`. `<num>` is an incrementing number starting from `1`.
-> **Note:** There is more information about [checks here](/docs/agent/checks.html). -> **Note:** There is more information about [checks here](/docs/agent/checks).
### Proxy ### Proxy
Service definitions allow for an optional proxy registration. Proxies used with Connect Service definitions allow for an optional proxy registration. Proxies used with Connect
are registered as services in Consul's catalog. are registered as services in Consul's catalog.
See the [Proxy Service Registration](/docs/connect/registration/service-registration.html) reference See the [Proxy Service Registration](/docs/connect/registration/service-registration) reference
for the available configuration options. for the available configuration options.
### Connect ### Connect
The `kind` field is used to optionally identify the service as a [Connect The `kind` field is used to optionally identify the service as a [Connect
proxy](/docs/connect/proxies.html) instance with the value `connect-proxy` or proxy](/docs/connect/proxies) instance with the value `connect-proxy` or
a [Mesh Gateway](/docs/connect/mesh_gateway.html) instance with the value `mesh-gateway`. For a [Mesh Gateway](/docs/connect/mesh_gateway) instance with the value `mesh-gateway`. For
typical non-proxy instances the `kind` field must be omitted. The `proxy` field typical non-proxy instances the `kind` field must be omitted. The `proxy` field
is also required for Connect proxy registrations and is only valid if `kind` is is also required for Connect proxy registrations and is only valid if `kind` is
`connect-proxy`. The only required `proxy` field is `destination_service_name`. `connect-proxy`. The only required `proxy` field is `destination_service_name`.
For more detail please see [complete proxy configuration For more detail please see [complete proxy configuration
example](/docs/connect/registration/service-registration.html#complete-configuration-example) example](/docs/connect/registration/service-registration#complete-configuration-example)
-> **Deprecation Notice:** From version 1.2.0 to 1.3.0, proxy destination was -> **Deprecation Notice:** From version 1.2.0 to 1.3.0, proxy destination was
specified using `proxy_destination` at the top level. This will continue to work specified using `proxy_destination` at the top level. This will continue to work
@ -206,15 +206,15 @@ until at least 1.5.0 but it's highly recommended to switch to using
The `connect` field can be specified to configure The `connect` field can be specified to configure
[Connect](/docs/connect) for a service. This field is available in [Connect](/docs/connect) for a service. This field is available in
Consul 1.2.0 and later. The `native` value can be set to true to advertise the Consul 1.2.0 and later. The `native` value can be set to true to advertise the
service as [Connect-native](/docs/connect/native.html). The `sidecar_service` service as [Connect-native](/docs/connect/native). The `sidecar_service`
field is an optional nested service definition its behavior and defaults are field is an optional nested service definition its behavior and defaults are
described in [Sidecar Service described in [Sidecar Service
Registration](/docs/connect/registration/sidecar-service.html). If `native` is true, Registration](/docs/connect/registration/sidecar-service). If `native` is true,
it is an error to also specify a sidecar service registration. it is an error to also specify a sidecar service registration.
-> **Deprecation Notice:** From version 1.2.0 to 1.3.0 during beta, Connect -> **Deprecation Notice:** From version 1.2.0 to 1.3.0 during beta, Connect
supported "Managed" proxies which are specified with the `connect.proxy` field. supported "Managed" proxies which are specified with the `connect.proxy` field.
[Managed Proxies are deprecated](/docs/connect/proxies/managed-deprecated.html) [Managed Proxies are deprecated](/docs/connect/proxies/managed-deprecated)
and the `connect.proxy` field will be removed in a future major release. and the `connect.proxy` field will be removed in a future major release.
### DNS SRV Weights ### DNS SRV Weights
@ -236,7 +236,7 @@ weight.
Services may also contain a `token` field to provide an ACL token. This token is Services may also contain a `token` field to provide an ACL token. This token is
used for any interaction with the catalog for the service, including used for any interaction with the catalog for the service, including
[anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. [anti-entropy syncs](/docs/internals/anti-entropy) and deregistration.
You can optionally disable the anti-entropy feature for this service using the You can optionally disable the anti-entropy feature for this service using the
`enable_tag_override` flag. External agents can modify tags on services in the `enable_tag_override` flag. External agents can modify tags on services in the
@ -253,7 +253,7 @@ configuration items are independent of one another. Updating the tags
for the service registered on one node is independent of the same for the service registered on one node is independent of the same
service (by name) registered on another node. If `enable_tag_override` is service (by name) registered on another node. If `enable_tag_override` is
not specified the default value is false. See [anti-entropy not specified the default value is false. See [anti-entropy
syncs](/docs/internals/anti-entropy.html) for more info. syncs](/docs/internals/anti-entropy) for more info.
For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0 For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0
supports both `enable_tag_override` and `enableTagOverride` but the latter is supports both `enable_tag_override` and `enableTagOverride` but the latter is
@ -345,7 +345,7 @@ services {
## Service and Tag Names with DNS ## Service and Tag Names with DNS
Consul exposes service definitions and tags over the [DNS](/docs/agent/dns.html) Consul exposes service definitions and tags over the [DNS](/docs/agent/dns)
interface. DNS queries have a strict set of allowed characters and a interface. DNS queries have a strict set of allowed characters and a
well-defined format that Consul cannot override. While it is possible to well-defined format that Consul cannot override. While it is possible to
register services or tags with names that don't match the conventions, those register services or tags with names that don't match the conventions, those

24
website/pages/docs/agent/telemetry.mdx
View File

@ -23,14 +23,14 @@ This telemetry information can be used for debugging or otherwise
getting a better view of what Consul is doing. Review the [Monitoring and getting a better view of what Consul is doing. Review the [Monitoring and
Metrics guide](https://learn.hashicorp.com/consul/day-2-operations/monitoring?utm_source=consul.io&utm_medium=docs) to learn how collect and interpret Consul data. Metrics guide](https://learn.hashicorp.com/consul/day-2-operations/monitoring?utm_source=consul.io&utm_medium=docs) to learn how collect and interpret Consul data.
Additionally, if the [`telemetry` configuration options](/docs/agent/options.html#telemetry) Additionally, if the [`telemetry` configuration options](/docs/agent/options#telemetry)
are provided, the telemetry information will be streamed to a are provided, the telemetry information will be streamed to a
[statsite](http://github.com/armon/statsite) or [statsd](http://github.com/etsy/statsd) server where [statsite](http://github.com/armon/statsite) or [statsd](http://github.com/etsy/statsd) server where
it can be aggregated and flushed to Graphite or any other metrics store. it can be aggregated and flushed to Graphite or any other metrics store.
For a configuration example for Telegraf, review the [Monitoring with Telegraf guide](https://learn.hashicorp.com/consul/integrations/telegraf?utm_source=consul.io&utm_medium=docs). For a configuration example for Telegraf, review the [Monitoring with Telegraf guide](https://learn.hashicorp.com/consul/integrations/telegraf?utm_source=consul.io&utm_medium=docs).
This This
information can also be viewed with the [metrics endpoint](/api/agent.html#view-metrics) in JSON information can also be viewed with the [metrics endpoint](/api/agent#view-metrics) in JSON
format or using [Prometheus](https://prometheus.io/) format. format or using [Prometheus](https://prometheus.io/) format.
Below is sample output of a telemetry dump: Below is sample output of a telemetry dump:
@ -119,9 +119,9 @@ you will need to apply a function such as InfluxDB's [`non_negative_difference()
### Network activity - RPC Count ### Network activity - RPC Count
| Metric Name | Description | | Metric Name | Description |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server |
| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options.html#limits) configuration. | | `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options#limits) configuration. |
| `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. |
**Why they're important:** These measurements indicate the current load created from a Consul agent, including when the load becomes high enough to be rate limited. A high RPC count, especially from `consul.client.rpcexceeded` meaning that the requests are being rate-limited, could imply a misconfigured Consul agent. **Why they're important:** These measurements indicate the current load created from a Consul agent, including when the load becomes high enough to be rate limited. A high RPC count, especially from `consul.client.rpcexceeded` meaning that the requests are being rate-limited, could imply a misconfigured Consul agent.
@ -139,11 +139,11 @@ when retrieving metrics from the built-in store using the above described signal
This is a full list of metrics emitted by Consul. This is a full list of metrics emitted by Consul.
| Metric | Description | Unit | Type | | Metric | Description | Unit | Type |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | ------- | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------- |
| `consul.acl.blocked.service.registration` | This increments whenever a deregistration fails for a service (blocked by an ACL) | requests | counter | | `consul.acl.blocked.service.registration` | This increments whenever a deregistration fails for a service (blocked by an ACL) | requests | counter |
| `consul.acl.blocked..registration` | This increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL | requests | counter | | `consul.acl.blocked..registration` | This increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL | requests | counter |
| `consul.client.rpc` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter | | `consul.client.rpc` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter |
| `consul.client.rpc.exceeded` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options.html#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter | | `consul.client.rpc.exceeded` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter |
| `consul.client.rpc.failed` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | | `consul.client.rpc.failed` | This increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter |
| `consul.client.api.catalog_register.` | This increments whenever a Consul agent receives a catalog register request. | requests | counter | | `consul.client.api.catalog_register.` | This increments whenever a Consul agent receives a catalog register request. | requests | counter |
| `consul.client.api.success.catalog_register.` | This increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter | | `consul.client.api.success.catalog_register.` | This increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter |
@ -182,7 +182,7 @@ This is a full list of metrics emitted by Consul.
These metrics are used to monitor the health of the Consul servers. These metrics are used to monitor the health of the Consul servers.
| Metric | Description | Unit | Type | | Metric | Description | Unit | Type |
| ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- | | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `consul.raft.fsm.snapshot` | This metric measures the time taken by the FSM to record the current state for the snapshot. | ms | timer | | `consul.raft.fsm.snapshot` | This metric measures the time taken by the FSM to record the current state for the snapshot. | ms | timer |
| `consul.raft.fsm.apply` | This metric gives the number of logs committed since the last interval. | commit logs / interval | counter | | `consul.raft.fsm.apply` | This metric gives the number of logs committed since the last interval. | commit logs / interval | counter |
| `consul.raft.commitNumLogs` | This metric measures the count of logs processed for application to the FSM in a single batch. | logs | gauge | | `consul.raft.commitNumLogs` | This metric measures the count of logs processed for application to the FSM in a single batch. | logs | gauge |
@ -216,7 +216,7 @@ These metrics are used to monitor the health of the Consul servers.
| `consul.raft.rpc.installSnapshot` | This metric measures the time taken to process the installSnapshot RPC call. This metric should only be seen on agents which are currently in the follower state. | ms | timer | | `consul.raft.rpc.installSnapshot` | This metric measures the time taken to process the installSnapshot RPC call. This metric should only be seen on agents which are currently in the follower state. | ms | timer |
| `consul.raft.replication.appendEntries.rpc` | This metric measures the time taken by the append entries RFC, to replicate the log entries of a leader agent onto its follower agent(s) | ms | timer | | `consul.raft.replication.appendEntries.rpc` | This metric measures the time taken by the append entries RFC, to replicate the log entries of a leader agent onto its follower agent(s) | ms | timer |
| `consul.raft.replication.appendEntries.logs` | This metric measures the number of logs replicated to an agent, to bring it up to speed with the leader's logs. | logs appended/ interval | counter | | `consul.raft.replication.appendEntries.logs` | This metric measures the number of logs replicated to an agent, to bring it up to speed with the leader's logs. | logs appended/ interval | counter |
| `consul.raft.leader.lastContact` | This will only be emitted by the Raft leader and measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/docs/agent/options.html#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/docs/install/performance.html) guide for more details. | ms | timer | | `consul.raft.leader.lastContact` | This will only be emitted by the Raft leader and measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/docs/agent/options#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/docs/install/performance) guide for more details. | ms | timer |
| `consul.acl.apply` | This measures the time it takes to complete an update to the ACL store. | ms | timer | | `consul.acl.apply` | This measures the time it takes to complete an update to the ACL store. | ms | timer |
| `consul.acl.fault` | This measures the time it takes to fault in the rules for an ACL during a cache miss. | ms | timer | | `consul.acl.fault` | This measures the time it takes to fault in the rules for an ACL during a cache miss. | ms | timer |
| `consul.acl.fetchRemoteACLs` | This measures the time it takes to fetch remote ACLs during replication. | ms | timer | | `consul.acl.fetchRemoteACLs` | This measures the time it takes to fetch remote ACLs during replication. | ms | timer |
@ -269,7 +269,7 @@ These metrics give insight into the health of the cluster as a whole.
| `consul.memberlist.degraded.timeout` | This metric counts the number of times an agent was marked as a dead node, whilst not getting enough confirmations from a randomly selected list of agent nodes in an agent's membership. | occurrence / interval | counter | | `consul.memberlist.degraded.timeout` | This metric counts the number of times an agent was marked as a dead node, whilst not getting enough confirmations from a randomly selected list of agent nodes in an agent's membership. | occurrence / interval | counter |
| `consul.memberlist.msg.dead` | This metric counts the number of times an agent has marked another agent to be a dead node. | messages / interval | counter | | `consul.memberlist.msg.dead` | This metric counts the number of times an agent has marked another agent to be a dead node. | messages / interval | counter |
| `consul.memberlist.health.score` | This metric describes a node's perception of its own health based on how well it is meeting the soft real-time requirements of the protocol. This metric ranges from 0 to 8, where 0 indicates "totally healthy". This health score is used to scale the time between outgoing probes, and higher scores translate into longer probing intervals. For more details see section IV of the Lifeguard paper: https://arxiv.org/pdf/1707.00788.pdf | score | gauge | | `consul.memberlist.health.score` | This metric describes a node's perception of its own health based on how well it is meeting the soft real-time requirements of the protocol. This metric ranges from 0 to 8, where 0 indicates "totally healthy". This health score is used to scale the time between outgoing probes, and higher scores translate into longer probing intervals. For more details see section IV of the Lifeguard paper: https://arxiv.org/pdf/1707.00788.pdf | score | gauge |
| `consul.memberlist.msg.suspect` | This increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/docs/agent/options.html#ports). | suspect messages received / interval | counter | | `consul.memberlist.msg.suspect` | This increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/docs/agent/options#ports). | suspect messages received / interval | counter |
| `consul.memberlist.tcp.accept` | This metric counts the number of times an agent has accepted an incoming TCP stream connection. | connections accepted / interval | counter | | `consul.memberlist.tcp.accept` | This metric counts the number of times an agent has accepted an incoming TCP stream connection. | connections accepted / interval | counter |
| `consul.memberlist.udp.sent/received` | This metric measures the total number of bytes sent/received by an agent through the UDP protocol. | bytes sent or bytes received / interval | counter | | `consul.memberlist.udp.sent/received` | This metric measures the total number of bytes sent/received by an agent through the UDP protocol. | bytes sent or bytes received / interval | counter |
| `consul.memberlist.tcp.connect` | This metric counts the number of times an agent has initiated a push/pull sync with an other agent. | push/pull initiated / interval | counter | | `consul.memberlist.tcp.connect` | This metric counts the number of times an agent has initiated a push/pull sync with an other agent. | push/pull initiated / interval | counter |
@ -280,11 +280,11 @@ These metrics give insight into the health of the cluster as a whole.
| `consul.memberlist.msg_suspect` | This metric gives the number of suspect nodes, that the agent has mapped out so far, based on the message information given by the network layer. | nodes / Interval | counter | | `consul.memberlist.msg_suspect` | This metric gives the number of suspect nodes, that the agent has mapped out so far, based on the message information given by the network layer. | nodes / Interval | counter |
| `consul.memberlist.probeNode` | This metric measures the time taken to perform a single round of failure detection on a select agent. | nodes / Interval | counter | | `consul.memberlist.probeNode` | This metric measures the time taken to perform a single round of failure detection on a select agent. | nodes / Interval | counter |
| `consul.memberlist.pushPullNode` | This metric measures the number of agents that have exchanged state with this agent. | nodes / Interval | counter | | `consul.memberlist.pushPullNode` | This metric measures the number of agents that have exchanged state with this agent. | nodes / Interval | counter |
| `consul.serf.member.failed` | This increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options.html#ports). | failures / interval | counter | | `consul.serf.member.failed` | This increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options#ports). | failures / interval | counter |
| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options.html#ports). | flaps / interval | counter | | `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/options#ports). | flaps / interval | counter |
| `consul.serf.member.join` | This increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter | | `consul.serf.member.join` | This increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter |
| `consul.serf.member.left` | This increments when an agent leaves the cluster. | leaves / interval | counter | | `consul.serf.member.left` | This increments when an agent leaves the cluster. | leaves / interval | counter |
| `consul.serf.events` | This increments when an agent processes an [event](/docs/commands/event.html). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter | | `consul.serf.events` | This increments when an agent processes an [event](/docs/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter |
| `consul.autopilot.failure_tolerance` | This tracks the number of voting servers that the cluster can lose while continuing to function. | servers | gauge | | `consul.autopilot.failure_tolerance` | This tracks the number of voting servers that the cluster can lose while continuing to function. | servers | gauge |
| `consul.autopilot.healthy` | This tracks the overall health of the local server cluster. If all servers are considered healthy by Autopilot, this will be set to 1. If any are unhealthy, this will be 0. | boolean | gauge | | `consul.autopilot.healthy` | This tracks the overall health of the local server cluster. If all servers are considered healthy by Autopilot, this will be set to 1. If any are unhealthy, this will be 0. | boolean | gauge |
| `consul.session_ttl.active` | This tracks the active number of sessions being tracked. | sessions | gauge | | `consul.session_ttl.active` | This tracks the active number of sessions being tracked. | sessions | gauge |

6
website/pages/docs/agent/watches.mdx
View File

@ -22,11 +22,11 @@ Watches are implemented using blocking queries in the [HTTP API](/api).
Agents automatically make the proper API calls to watch for changes Agents automatically make the proper API calls to watch for changes
and inform a handler when the data view has updated. and inform a handler when the data view has updated.
Watches can be configured as part of the [agent's configuration](/docs/agent/options.html#watches), Watches can be configured as part of the [agent's configuration](/docs/agent/options#watches),
causing them to run once the agent is initialized. Reloading the agent configuration causing them to run once the agent is initialized. Reloading the agent configuration
allows for adding or removing watches dynamically. allows for adding or removing watches dynamically.
Alternatively, the [watch command](/docs/commands/watch.html) enables a watch to be Alternatively, the [watch command](/docs/commands/watch) enables a watch to be
started outside of the agent. This can be used by an operator to inspect data in Consul started outside of the agent. This can be used by an operator to inspect data in Consul
or to easily pipe data into processes without being tied to the agent lifecycle. or to easily pipe data into processes without being tied to the agent lifecycle.
@ -423,7 +423,7 @@ An example of the output of this command:
### Type: event ((#event)) ### Type: event ((#event))
The "event" watch type is used to monitor for custom user The "event" watch type is used to monitor for custom user
events. These are fired using the [consul event](/docs/commands/event.html) command. events. These are fired using the [consul event](/docs/commands/event) command.
It takes only a single optional "name" parameter which restricts It takes only a single optional "name" parameter which restricts
the watch to only events with the given name. the watch to only events with the given name.

2
website/pages/docs/commands/acl/auth-method/index.mdx
View File

@ -13,7 +13,7 @@ The `acl auth-method` command is used to manage Consul's ACL auth methods.
It exposes commands for creating, updating, reading, deleting, and listing auth methods. It exposes commands for creating, updating, reading, deleting, and listing auth methods.
This command is available in Consul 1.5.0 and newer. This command is available in Consul 1.5.0 and newer.
ACL auth methods may also be managed via the [HTTP API](/api/acl/auth-methods.html). ACL auth methods may also be managed via the [HTTP API](/api/acl/auth-methods).
-> **Note:** All of the example subcommands in this document will require a valid -> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the Consul token with the appropriate permissions. Either set the

2
website/pages/docs/commands/acl/binding-rule/index.mdx
View File

@ -13,7 +13,7 @@ The `acl binding-rule` command is used to manage Consul's ACL binding rules.
It exposes commands for creating, updating, reading, deleting, and listing binding rules. It exposes commands for creating, updating, reading, deleting, and listing binding rules.
This command is available in Consul 1.5.0 and newer. This command is available in Consul 1.5.0 and newer.
ACL binding rules may also be managed via the [HTTP API](/api/acl/binding-rules.html). ACL binding rules may also be managed via the [HTTP API](/api/acl/binding-rules).
-> **Note:** All of the example subcommands in this document will require a valid -> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the Consul token with the appropriate permissions. Either set the

2
website/pages/docs/commands/acl/bootstrap.mdx
View File

@ -14,7 +14,7 @@ for management purposes and output its details. This can only be done once and a
will be disabled. If all tokens are lost and you need to bootstrap again you can follow the bootstrap will be disabled. If all tokens are lost and you need to bootstrap again you can follow the bootstrap
[reset procedure](https://learn.hashicorp.com/consul/security-networking/acl-troubleshooting?utm_source=consul.io&utm_medium=docs#reset-the-acl-system). [reset procedure](https://learn.hashicorp.com/consul/security-networking/acl-troubleshooting?utm_source=consul.io&utm_medium=docs#reset-the-acl-system).
The ACL system can also be bootstrapped via the [HTTP API](/api/acl/acl.html#bootstrap-acls). The ACL system can also be bootstrapped via the [HTTP API](/api/acl/acl#bootstrap-acls).
## Usage ## Usage

2
website/pages/docs/commands/acl/index.mdx
View File

@ -14,7 +14,7 @@ line. It exposes top-level commands for bootstrapping the ACL system,
managing tokens and policies, translating legacy rules, and setting the managing tokens and policies, translating legacy rules, and setting the
tokens for use by an agent. tokens for use by an agent.
ACLs are also accessible via the [HTTP API](/api/acl/acl.html). ACLs are also accessible via the [HTTP API](/api/acl/acl).
Bootstrap Consul's ACLs: Bootstrap Consul's ACLs:

2
website/pages/docs/commands/acl/policy/index.mdx
View File

@ -13,7 +13,7 @@ The `acl policy` command is used to manage Consul's ACL policies.
It exposes commands for creating, updating, reading, deleting, and listing policies. It exposes commands for creating, updating, reading, deleting, and listing policies.
This command is available in Consul 1.4.0 and newer. This command is available in Consul 1.4.0 and newer.
ACL policies may also be managed via the [HTTP API](/api/acl/policies.html). ACL policies may also be managed via the [HTTP API](/api/acl/policies).
-> **Note:** All of the example subcommands in this document will require a valid -> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the Consul token with the appropriate permissions. Either set the

2
website/pages/docs/commands/acl/role/index.mdx
View File

@ -13,7 +13,7 @@ The `acl role` command is used to manage Consul's ACL roles.
It exposes commands for creating, updating, reading, deleting, and listing roles. It exposes commands for creating, updating, reading, deleting, and listing roles.
This command is available in Consul 1.5.0 and newer. This command is available in Consul 1.5.0 and newer.
ACL roles may also be managed via the [HTTP API](/api/acl/roles.html). ACL roles may also be managed via the [HTTP API](/api/acl/roles).
-> **Note:** All of the example subcommands in this document will require a valid -> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the Consul token with the appropriate permissions. Either set the

2
website/pages/docs/commands/acl/token/index.mdx
View File

@ -13,7 +13,7 @@ The `acl token` command is used to manage Consul's ACL tokens.
It exposes commands for creating, updating, reading, deleting, and listing tokens. It exposes commands for creating, updating, reading, deleting, and listing tokens.
This command is available in Consul 1.4.0 and newer. This command is available in Consul 1.4.0 and newer.
ACL tokens may also be managed via the [HTTP API](/api/acl/tokens.html). ACL tokens may also be managed via the [HTTP API](/api/acl/tokens).
-> **Note:** All of the example subcommands in this document will require a valid -> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the Consul token with the appropriate permissions. Either set the

2
website/pages/docs/commands/agent.mdx
View File

@ -16,6 +16,6 @@ performs the important task of maintaining membership information,
running checks, announcing services, handling queries, etc. running checks, announcing services, handling queries, etc.
Due to the power and flexibility of this command, the Consul agent Due to the power and flexibility of this command, the Consul agent
is documented in its own section. See the [Consul Agent](/docs/agent/basics.html) is documented in its own section. See the [Consul Agent](/docs/agent/basics)
section for more information on how to use this command and the section for more information on how to use this command and the
options it has. options it has.

2
website/pages/docs/commands/catalog/index.mdx
View File

@ -13,7 +13,7 @@ The `catalog` command is used to interact with Consul's catalog via the command
line. It exposes top-level commands for reading and filtering data from the line. It exposes top-level commands for reading and filtering data from the
registry. registry.
The catalog is also accessible via the [HTTP API](/api/catalog.html). The catalog is also accessible via the [HTTP API](/api/catalog).
## Basic Examples ## Basic Examples

2
website/pages/docs/commands/catalog/nodes.mdx
View File

@ -76,5 +76,5 @@ Usage: `consul catalog nodes [options]`
- `-filter=<filter>` - Expression to use for filtering the results. Can be passed - `-filter=<filter>` - Expression to use for filtering the results. Can be passed
via stdin by using `-` for the value or from a file by passing `@<file path>`. via stdin by using `-` for the value or from a file by passing `@<file path>`.
See the [`/catalog/nodes` API documentation](/api/catalog.html#filtering) for a See the [`/catalog/nodes` API documentation](/api/catalog#filtering) for a
description of what is filterable. description of what is filterable.

2
website/pages/docs/commands/config/delete.mdx
View File

@ -10,7 +10,7 @@ sidebar_current: docs-commands-config-delete
Command: `consul config delete` Command: `consul config delete`
The `config delete` command deletes the configuration entry specified by the The `config delete` command deletes the configuration entry specified by the
kind and name. See the [configuration entries docs](/docs/agent/config_entries.html) kind and name. See the [configuration entries docs](/docs/agent/config_entries)
for more details about configuration entries. for more details about configuration entries.
## Usage ## Usage

4
website/pages/docs/commands/config/index.mdx
View File

@ -12,9 +12,9 @@ Command: `consul config`
The `config` command is used to interact with Consul's central configuration The `config` command is used to interact with Consul's central configuration
system. It exposes commands for creating, updating, reading, and deleting system. It exposes commands for creating, updating, reading, and deleting
different kinds of config entries. See the different kinds of config entries. See the
[agent configuration](/docs/agent/options.html#enable_central_service_config) [agent configuration](/docs/agent/options#enable_central_service_config)
for more information on how to enable this functionality for centrally for more information on how to enable this functionality for centrally
configuring services and [configuration entries docs](/docs/agent/config_entries.html) for a description configuring services and [configuration entries docs](/docs/agent/config_entries) for a description
of the configuration entries content. of the configuration entries content.
## Usage ## Usage

2
website/pages/docs/commands/config/list.mdx
View File

@ -10,7 +10,7 @@ sidebar_current: docs-commands-config-list
Command: `consul config list` Command: `consul config list`
The `config list` command lists all given config entries of the given kind. The `config list` command lists all given config entries of the given kind.
See the [configuration entries docs](/docs/agent/config_entries.html) for more See the [configuration entries docs](/docs/agent/config_entries) for more
details about configuration entries. details about configuration entries.
## Usage ## Usage

2
website/pages/docs/commands/config/read.mdx
View File

@ -11,7 +11,7 @@ Command: `consul config read`
The `config read` command reads the config entry specified by the given The `config read` command reads the config entry specified by the given
kind and name and outputs its JSON representation. See the kind and name and outputs its JSON representation. See the
[configuration entries docs](/docs/agent/config_entries.html) for more [configuration entries docs](/docs/agent/config_entries) for more
details about configuration entries. details about configuration entries.
## Usage ## Usage

2
website/pages/docs/commands/config/write.mdx
View File

@ -10,7 +10,7 @@ sidebar_current: docs-commands-config-write
Command: `consul config write` Command: `consul config write`
The `config write` command creates or updates a centralized config entry. The `config write` command creates or updates a centralized config entry.
See the [configuration entries docs](/docs/agent/config_entries.html) for more See the [configuration entries docs](/docs/agent/config_entries) for more
details about configuration entries. details about configuration entries.
## Usage ## Usage

6
website/pages/docs/commands/connect/ca.mdx
View File

@ -14,7 +14,7 @@ Command: `consul connect ca`
The CA connect command is used to interact with Consul Connect's Certificate Authority The CA connect command is used to interact with Consul Connect's Certificate Authority
subsystem. The command can be used to view or modify the current CA configuration. See the subsystem. The command can be used to view or modify the current CA configuration. See the
[Connect CA documentation](/docs/connect/ca.html) for more information. [Connect CA documentation](/docs/connect/ca) for more information.
```text ```text
Usage: consul connect ca <subcommand> [options] [args] Usage: consul connect ca <subcommand> [options] [args]
@ -66,7 +66,7 @@ The output looks like this:
## set-config ## set-config
Modifies the current CA configuration. If this results in a new root certificate Modifies the current CA configuration. If this results in a new root certificate
being used, the [Root Rotation](/docs/connect/ca.html#root-certificate-rotation) process being used, the [Root Rotation](/docs/connect/ca#root-certificate-rotation) process
will be triggered. will be triggered.
Usage: `consul connect ca set-config [options]` Usage: `consul connect ca set-config [options]`
@ -81,7 +81,7 @@ Usage: `consul connect ca set-config [options]`
- `-config-file` - (required) Specifies a JSON-formatted file to use for the new configuration. - `-config-file` - (required) Specifies a JSON-formatted file to use for the new configuration.
The format of this config file matches the request payload documented in the The format of this config file matches the request payload documented in the
[Update CA Configuration API](/api/connect/ca.html#update-ca-configuration). [Update CA Configuration API](/api/connect/ca#update-ca-configuration).
The output looks like this: The output looks like this:

10
website/pages/docs/commands/connect/envoy.mdx
View File

@ -45,7 +45,7 @@ proxy configuration needed.
be used instead. The scheme can also be set to HTTPS by setting the be used instead. The scheme can also be set to HTTPS by setting the
environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket
using `unix:///path/to/socket` if the [agent is configured to using `unix:///path/to/socket` if the [agent is configured to
listen](/docs/agent/options.html#addresses) that way. listen](/docs/agent/options#addresses) that way.
-> **Note:** gRPC uses the same TLS -> **Note:** gRPC uses the same TLS
settings as the HTTPS API. If HTTPS is enabled then gRPC will require HTTPS settings as the HTTPS API. If HTTPS is enabled then gRPC will require HTTPS
@ -55,7 +55,7 @@ proxy configuration needed.
#### Envoy Options for both Sidecars and Gateways #### Envoy Options for both Sidecars and Gateways
- `-proxy-id` - The [proxy service](/docs/connect/registration/service-registration.html) ID on the - `-proxy-id` - The [proxy service](/docs/connect/registration/service-registration) ID on the
local agent. This must already be present on the local agent. local agent. This must already be present on the local agent.
- `-envoy-binary` - The full path to a specific Envoy binary to exec. By - `-envoy-binary` - The full path to a specific Envoy binary to exec. By
@ -73,7 +73,7 @@ proxy configuration needed.
ACL token from `-token` or the environment and so should be handled as a secret. ACL token from `-token` or the environment and so should be handled as a secret.
This token grants the identity of any service it has `service:write` permission This token grants the identity of any service it has `service:write` permission
for and so can be used to access any upstream service that that service is for and so can be used to access any upstream service that that service is
allowed to access by [Connect intentions](/docs/connect/intentions.html). allowed to access by [Connect intentions](/docs/connect/intentions).
- `-envoy-version` - The version of envoy that is being started. Default is - `-envoy-version` - The version of envoy that is being started. Default is
`1.13.0`. This is required so that the correct configuration can be generated. `1.13.0`. This is required so that the correct configuration can be generated.
@ -89,7 +89,7 @@ proxy configuration needed.
- `-sidecar-for` - The _ID_ (not name if they differ) of the service instance - `-sidecar-for` - The _ID_ (not name if they differ) of the service instance
this proxy will represent. The target service doesn't need to exist on the this proxy will represent. The target service doesn't need to exist on the
local agent yet but a [sidecar proxy local agent yet but a [sidecar proxy
registration](/docs/connect/registration/service-registration.html) with registration](/docs/connect/registration/service-registration) with
`proxy.destination_service_id` equal to the passed value must be present. If `proxy.destination_service_id` equal to the passed value must be present. If
multiple proxy registrations targeting the same local service instance are multiple proxy registrations targeting the same local service instance are
present the command will error and `-proxy-id` should be used instead. present the command will error and `-proxy-id` should be used instead.
@ -137,7 +137,7 @@ does not allow decrypting any of their communications.
Assume a local service instance is registered on the local agent with a Assume a local service instance is registered on the local agent with a
sidecar proxy (using the [sidecar service sidecar proxy (using the [sidecar service
registration](/docs/connect/registration/service-registration.html) helper) as below. registration](/docs/connect/registration/service-registration) helper) as below.
```hcl ```hcl
service { service {

2
website/pages/docs/commands/connect/index.mdx
View File

@ -10,7 +10,7 @@ sidebar_current: docs-commands-connect
Command: `consul connect` Command: `consul connect`
The `connect` command is used to interact with Connect The `connect` command is used to interact with Connect
[Connect](/docs/connect/intentions.html) subsystems. It exposes commands for [Connect](/docs/connect/intentions) subsystems. It exposes commands for
running the built-in mTLS proxy and viewing/updating the Certificate Authority running the built-in mTLS proxy and viewing/updating the Certificate Authority
(CA) configuration. This command is available in Consul 1.2 and later. (CA) configuration. This command is available in Consul 1.2 and later.

8
website/pages/docs/commands/connect/proxy.mdx
View File

@ -32,13 +32,13 @@ Usage: `consul connect proxy [options]`
- `-sidecar-for` - The _ID_ (not name if they differ) of the service instance - `-sidecar-for` - The _ID_ (not name if they differ) of the service instance
this proxy will represent. The target service doesn't need to exist on the this proxy will represent. The target service doesn't need to exist on the
local agent yet but a [sidecar proxy local agent yet but a [sidecar proxy
registration](/docs/connect/registration/service-registration.html) with registration](/docs/connect/registration/service-registration) with
`proxy.destination_service_id` equal to the passed value must be present. If `proxy.destination_service_id` equal to the passed value must be present. If
multiple proxy registrations targeting the same local service instance are multiple proxy registrations targeting the same local service instance are
present the command will error and `-proxy-id` should be used instead. present the command will error and `-proxy-id` should be used instead.
- `-proxy-id` - The [proxy - `-proxy-id` - The [proxy
service](/docs/connect/registration/service-registration.html) ID on the service](/docs/connect/registration/service-registration) ID on the
local agent. This must already be present on the local agent. local agent. This must already be present on the local agent.
- `-log-level` - Specifies the log level. - `-log-level` - Specifies the log level.
@ -50,7 +50,7 @@ Usage: `consul connect proxy [options]`
doesn't need to actually exist in the Consul catalog, but proper ACL doesn't need to actually exist in the Consul catalog, but proper ACL
permissions (`service:write`) are required. This and the remaining options can permissions (`service:write`) are required. This and the remaining options can
be used to setup a proxy that is not registered already with local config be used to setup a proxy that is not registered already with local config
[useful for development](/docs/connect/dev.html). [useful for development](/docs/connect/dev).
- `-upstream` - Upstream service to support connecting to. The format should be - `-upstream` - Upstream service to support connecting to. The format should be
'name:addr', such as 'db:8181'. This will make 'db' available on port 8181. 'name:addr', such as 'db:8181'. This will make 'db' available on port 8181.
@ -72,7 +72,7 @@ Usage: `consul connect proxy [options]`
- `-register-id` - Optional ID suffix for the service when `-register` is set to - `-register-id` - Optional ID suffix for the service when `-register` is set to
disambiguate the service ID. By default the service ID is `<service>-proxy` disambiguate the service ID. By default the service ID is `<service>-proxy`
where `<service>` is the `-service` value. In most cases it is now preferable where `<service>` is the `-service` value. In most cases it is now preferable
to use [`consul services register`](/docs/commands/services/register.html) to to use [`consul services register`](/docs/commands/services/register) to
register a fully configured proxy instance rather than specify config and register a fully configured proxy instance rather than specify config and
registration via this command. registration via this command.

4
website/pages/docs/commands/debug.mdx
View File

@ -74,13 +74,13 @@ The `-capture` flag can be specified multiple times to capture specific
information when `debug` is running. By default, it captures all information. information when `debug` is running. By default, it captures all information.
| Target | Description | | Target | Description |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | Version and configuration information about the agent. | | `agent` | Version and configuration information about the agent. |
| `host` | Information about resources on the host running the target agent such as CPU, memory, and disk. | | `host` | Information about resources on the host running the target agent such as CPU, memory, and disk. |
| `cluster` | A list of all the WAN and LAN members in the cluster. | | `cluster` | A list of all the WAN and LAN members in the cluster. |
| `metrics` | Metrics from the in-memory metrics endpoint in the target, captured at the interval. | | `metrics` | Metrics from the in-memory metrics endpoint in the target, captured at the interval. |
| `logs` | `DEBUG` level logs for the target agent, captured for the interval. | | `logs` | `DEBUG` level logs for the target agent, captured for the interval. |
| `pprof` | Golang heap, CPU, goroutine, and trace profiling. This information is not retrieved unless [`enable_debug`](/docs/agent/options.html#enable_debug) is set to `true` on the target agent. | | `pprof` | Golang heap, CPU, goroutine, and trace profiling. This information is not retrieved unless [`enable_debug`](/docs/agent/options#enable_debug) is set to `true` on the target agent. |
## Examples ## Examples

6
website/pages/docs/commands/event.mdx
View File

@ -19,14 +19,14 @@ The `event` command provides a mechanism to fire a custom user event to an
entire datacenter. These events are opaque to Consul, but they can be used entire datacenter. These events are opaque to Consul, but they can be used
to build scripting infrastructure to do automated deploys, restart services, to build scripting infrastructure to do automated deploys, restart services,
or perform any other orchestration action. Events can be handled by or perform any other orchestration action. Events can be handled by
[using a watch](/docs/agent/watches.html). [using a watch](/docs/agent/watches).
Under the hood, events are propagated using the [gossip protocol](/docs/internals/gossip.html). Under the hood, events are propagated using the [gossip protocol](/docs/internals/gossip).
While the details are not important for using events, an understanding of While the details are not important for using events, an understanding of
the semantics is useful. The gossip layer will make a best-effort to deliver the semantics is useful. The gossip layer will make a best-effort to deliver
the event, but there is **no guaranteed delivery**. Unlike most Consul data, which is the event, but there is **no guaranteed delivery**. Unlike most Consul data, which is
replicated using [consensus](/docs/internals/consensus.html), event data replicated using [consensus](/docs/internals/consensus), event data
is purely peer-to-peer over gossip. This means it is not persisted and does is purely peer-to-peer over gossip. This means it is not persisted and does
not have a total ordering. In practice, this means you cannot rely on the not have a total ordering. In practice, this means you cannot rely on the
order of message delivery. An advantage however is that events can still order of message delivery. An advantage however is that events can still

4
website/pages/docs/commands/exec.mdx
View File

@ -18,8 +18,8 @@ this can be used to run the `uptime` command across all machines providing
the `web` service. the `web` service.
Remote execution works by specifying a job, which is stored in the KV store. Remote execution works by specifying a job, which is stored in the KV store.
Agents are informed about the new job using the [event system](/docs/commands/event.html), Agents are informed about the new job using the [event system](/docs/commands/event),
which propagates messages via the [gossip protocol](/docs/internals/gossip.html). which propagates messages via the [gossip protocol](/docs/internals/gossip).
As a result, delivery is best-effort, and there is **no guarantee** of execution. As a result, delivery is best-effort, and there is **no guarantee** of execution.
While events are purely gossip driven, remote execution relies on the KV store While events are purely gossip driven, remote execution relies on the KV store

4
website/pages/docs/commands/force-leave.mdx
View File

@ -15,13 +15,13 @@ Command: `consul force-leave`
The `force-leave` command forces a member of a Consul cluster to enter the The `force-leave` command forces a member of a Consul cluster to enter the
"left" state. The purpose of this method is to force-remove a node that has failed or "left" state. The purpose of this method is to force-remove a node that has failed or
was shutdown without a [graceful leave](https://www.consul.io/docs/commands/leave.html). was shutdown without a [graceful leave](/docs/commands/leave).
Consul periodically tries to reconnect to "failed" nodes in case failure was due Consul periodically tries to reconnect to "failed" nodes in case failure was due
to a network partition. After some configured amount of time (by default 72 hours), to a network partition. After some configured amount of time (by default 72 hours),
Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave` Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave`
command can be used to transition the "failed" nodes to a "left" state more command can be used to transition the "failed" nodes to a "left" state more
quickly, as reported by [`consul members`](https://www.consul.io/docs/commands/members.html). quickly, as reported by [`consul members`](/docs/commands/members).
This can be particularly useful for a node that was running as a server, This can be particularly useful for a node that was running as a server,
as it will eventually be removed from the Raft configuration by the leader. as it will eventually be removed from the Raft configuration by the leader.

6
website/pages/docs/commands/index.mdx
View File

@ -227,8 +227,8 @@ CONSUL_TLS_SERVER_NAME=consulserver.domain
Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the address the Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the address the
local agent is listening for gRPC requests. Currently gRPC is only used for local agent is listening for gRPC requests. Currently gRPC is only used for
integrating [Envoy proxy](/docs/connect/proxies/envoy.html) and must be [enabled integrating [Envoy proxy](/docs/connect/proxies/envoy) and must be [enabled
explicitly](/docs/agent/options.html#grpc_port) in agent configuration. explicitly](/docs/agent/options#grpc_port) in agent configuration.
``` ```
CONSUL_GRPC_ADDR=127.0.0.1:8502 CONSUL_GRPC_ADDR=127.0.0.1:8502
@ -241,7 +241,7 @@ CONSUL_GRPC_ADDR=unix://var/run/consul_grpc.sock
``` ```
If the agent is [configured with TLS If the agent is [configured with TLS
certificates](/docs/agent/encryption.html#rpc-encryption-with-tls), then the certificates](/docs/agent/encryption#rpc-encryption-with-tls), then the
gRPC listener will require TLS and present the same certificate as the https gRPC listener will require TLS and present the same certificate as the https
listener. As with `CONSUL_HTTP_ADDR`, if TLS is enabled either the `https://` listener. As with `CONSUL_HTTP_ADDR`, if TLS is enabled either the `https://`
scheme should be used, or `CONSUL_HTTP_SSL` set. scheme should be used, or `CONSUL_HTTP_SSL` set.

6
website/pages/docs/commands/info.mdx
View File

@ -21,9 +21,9 @@ There are currently the top-level keys for:
- agent: Provides information about the agent - agent: Provides information about the agent
- consul: Information about the consul library (client or server) - consul: Information about the consul library (client or server)
- raft: Provides info about the Raft [consensus library](/docs/internals/consensus.html) - raft: Provides info about the Raft [consensus library](/docs/internals/consensus)
- serf_lan: Provides info about the LAN [gossip pool](/docs/internals/gossip.html) - serf_lan: Provides info about the LAN [gossip pool](/docs/internals/gossip)
- serf_wan: Provides info about the WAN [gossip pool](/docs/internals/gossip.html) - serf_wan: Provides info about the WAN [gossip pool](/docs/internals/gossip)
Here is an example output: Here is an example output:

2
website/pages/docs/commands/intention/check.mdx
View File

@ -16,7 +16,7 @@ Consul configuration.
This command requires less ACL permissions than other intention-related This command requires less ACL permissions than other intention-related
tasks because no information about the intention is revealed. Therefore, tasks because no information about the intention is revealed. Therefore,
callers only need to have `service:read` access for the destination. Richer callers only need to have `service:read` access for the destination. Richer
commands like [match](/docs/commands/intention/match.html) require full commands like [match](/docs/commands/intention/match) require full
intention read permissions and don't evaluate the result. intention read permissions and don't evaluate the result.
## Usage ## Usage

4
website/pages/docs/commands/intention/index.mdx
View File

@ -10,11 +10,11 @@ sidebar_current: docs-commands-intention
Command: `consul intention` Command: `consul intention`
The `intention` command is used to interact with Connect The `intention` command is used to interact with Connect
[intentions](/docs/connect/intentions.html). It exposes commands for [intentions](/docs/connect/intentions). It exposes commands for
creating, updating, reading, deleting, checking, and managing intentions. creating, updating, reading, deleting, checking, and managing intentions.
This command is available in Consul 1.2 and later. This command is available in Consul 1.2 and later.
Intentions may also be managed via the [HTTP API](/api/connect/intentions.html). Intentions may also be managed via the [HTTP API](/api/connect/intentions).
## Usage ## Usage

2
website/pages/docs/commands/intention/match.mdx
View File

@ -13,7 +13,7 @@ The `intention match` command shows the list of intentions that match
a given source or destination. The list of intentions is listed in evaluation a given source or destination. The list of intentions is listed in evaluation
order: the first intention that matches a request would be evaluated. order: the first intention that matches a request would be evaluated.
The [check](/docs/commands/intention/check.html) command can be used to The [check](/docs/commands/intention/check) command can be used to
check whether a connection would be authorized between any two services. check whether a connection would be authorized between any two services.
## Usage ## Usage

2
website/pages/docs/commands/keygen.mdx
View File

@ -14,6 +14,6 @@ description: >-
Command: `consul keygen` Command: `consul keygen`
The `keygen` command generates an encryption key that can be used for The `keygen` command generates an encryption key that can be used for
[Consul agent traffic encryption](/docs/agent/encryption.html). [Consul agent traffic encryption](/docs/agent/encryption).
The keygen command uses a cryptographically The keygen command uses a cryptographically
strong pseudo-random number generator to generate the key. strong pseudo-random number generator to generate the key.

2
website/pages/docs/commands/keyring.mdx
View File

@ -10,7 +10,7 @@ sidebar_current: docs-commands-keyring
Command: `consul keyring` Command: `consul keyring`
The `keyring` command is used to examine and modify the encryption keys used in The `keyring` command is used to examine and modify the encryption keys used in
Consul's [Gossip Pools](/docs/internals/gossip.html). It is capable of Consul's [Gossip Pools](/docs/internals/gossip). It is capable of
distributing new encryption keys to the cluster, retiring old encryption keys, distributing new encryption keys to the cluster, retiring old encryption keys,
and changing the keys used by the cluster to encrypt messages. and changing the keys used by the cluster to encrypt messages.

12
website/pages/docs/commands/kv/index.mdx
View File

@ -15,7 +15,7 @@ and deleting from the store. This command is available in Consul 0.7.1 and
later. later.
The KV store is also accessible via the The KV store is also accessible via the
[HTTP API](/api/kv.html). [HTTP API](/api/kv).
## Usage ## Usage
@ -41,11 +41,11 @@ Subcommands:
For more information, examples, and usage about a subcommand, click on the name For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar or one of the links below: of the subcommand in the sidebar or one of the links below:
- [delete](/docs/commands/kv/delete.html) - [delete](/docs/commands/kv/delete)
- [export](/docs/commands/kv/export.html) - [export](/docs/commands/kv/export)
- [get](/docs/commands/kv/get.html) - [get](/docs/commands/kv/get)
- [import](/docs/commands/kv/import.html) - [import](/docs/commands/kv/import)
- [put](/docs/commands/kv/put.html) - [put](/docs/commands/kv/put)
## Basic Examples ## Basic Examples

2
website/pages/docs/commands/kv/put.mdx
View File

@ -142,5 +142,5 @@ Success! Lock released on: redis/lock/update
~> **Warning!** If you are trying to build a locking mechanism with these ~> **Warning!** If you are trying to build a locking mechanism with these
low-level primitives, you may want to look at the [<tt>consul low-level primitives, you may want to look at the [<tt>consul
lock</tt>](/docs/commands/lock.html) command. It provides higher-level lock</tt>](/docs/commands/lock) command. It provides higher-level
functionality without exposing the internal APIs of Consul. functionality without exposing the internal APIs of Consul.

4
website/pages/docs/commands/operator/area.mdx
View File

@ -214,14 +214,14 @@ server over its server RPC interface.
`Build` has the Consul version running on the node. `Build` has the Consul version running on the node.
`Protocol` is the [protocol version](/docs/upgrading.html#protocol-versions) being `Protocol` is the [protocol version](/docs/upgrading#protocol-versions) being
spoken by the node. spoken by the node.
`DC` is the node's Consul datacenter. `DC` is the node's Consul datacenter.
`RTT` is an estimated network round trip time from the server answering the query `RTT` is an estimated network round trip time from the server answering the query
to the given server, in a human-readable format. This is computed using to the given server, in a human-readable format. This is computed using
[network coordinates](/docs/internals/coordinates.html). [network coordinates](/docs/internals/coordinates).
The return code will indicate success or failure. The return code will indicate success or failure.

4
website/pages/docs/commands/operator/autopilot.mdx
View File

@ -85,10 +85,10 @@ Usage: `consul operator autopilot set-config [options]`
- `-disable-upgrade-migration` - (Enterprise-only) Controls whether Consul will avoid promoting - `-disable-upgrade-migration` - (Enterprise-only) Controls whether Consul will avoid promoting
new servers until it can perform a migration. Must be one of `[true|false]`. new servers until it can perform a migration. Must be one of `[true|false]`.
- `-redundancy-zone-tag`- (Enterprise-only) Controls the [`-node-meta`](/docs/agent/options.html#_node_meta) - `-redundancy-zone-tag`- (Enterprise-only) Controls the [`-node-meta`](/docs/agent/options#_node_meta)
key name used for separating servers into different redundancy zones. key name used for separating servers into different redundancy zones.
- `-upgrade-version-tag` - (Enterprise-only) Controls the [`-node-meta`](/docs/agent/options.html#_node_meta) - `-upgrade-version-tag` - (Enterprise-only) Controls the [`-node-meta`](/docs/agent/options#_node_meta)
tag to use for version info when performing upgrade migrations. If left blank, the Consul version will be used. tag to use for version info when performing upgrade migrations. If left blank, the Consul version will be used.
The output looks like this: The output looks like this:

8
website/pages/docs/commands/operator/index.mdx
View File

@ -24,7 +24,7 @@ if required, so this can be run from any Consul node in a cluster. See the
See the [Outage Recovery](https://learn.hashicorp.com/consul/day-2-operations/outage) guide for some examples of how See the [Outage Recovery](https://learn.hashicorp.com/consul/day-2-operations/outage) guide for some examples of how
this command is used. For an API to perform these operations programmatically, this command is used. For an API to perform these operations programmatically,
please see the documentation for the [Operator](/api/operator.html) please see the documentation for the [Operator](/api/operator)
endpoint. endpoint.
## Usage ## Usage
@ -44,6 +44,6 @@ Subcommands:
For more information, examples, and usage about a subcommand, click on the name For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar or one of the links below: of the subcommand in the sidebar or one of the links below:
- [area](/docs/commands/operator/area.html) - [area](/docs/commands/operator/area)
- [autopilot](/docs/commands/operator/autopilot.html) - [autopilot](/docs/commands/operator/autopilot)
- [raft](/docs/commands/operator/raft.html) - [raft](/docs/commands/operator/raft)

4
website/pages/docs/commands/operator/raft.mdx
View File

@ -70,9 +70,9 @@ There are rare cases where a peer may be left behind in the Raft configuration
even though the server is no longer present and known to the cluster. This command even though the server is no longer present and known to the cluster. This command
can be used to remove the failed server so that it is no longer affects the can be used to remove the failed server so that it is no longer affects the
Raft quorum. If the server still shows in the output of the Raft quorum. If the server still shows in the output of the
[`consul members`](/docs/commands/members.html) command, it is preferable to [`consul members`](/docs/commands/members) command, it is preferable to
clean up by simply running clean up by simply running
[`consul force-leave`](/docs/commands/force-leave.html) [`consul force-leave`](/docs/commands/force-leave)
instead of this command. instead of this command.
Usage: `consul operator raft remove-peer -address="IP:port"` Usage: `consul operator raft remove-peer -address="IP:port"`

2
website/pages/docs/commands/reload.mdx
View File

@ -22,7 +22,7 @@ reload will be present in the agent logs and not in the output of this command.
**NOTE** **NOTE**
Not all configuration options are reloadable. See the Not all configuration options are reloadable. See the
[Reloadable Configuration](/docs/agent/options.html#reloadable-configuration) [Reloadable Configuration](/docs/agent/options#reloadable-configuration)
section on the agent options page for details on which options are supported. section on the agent options page for details on which options are supported.
## Usage ## Usage

2
website/pages/docs/commands/rtt.mdx
View File

@ -14,7 +14,7 @@ Command: `consul rtt`
The `rtt` command estimates the network round trip time between two nodes using The `rtt` command estimates the network round trip time between two nodes using
Consul's network coordinate model of the cluster. Consul's network coordinate model of the cluster.
See the [Network Coordinates](/docs/internals/coordinates.html) internals guide See the [Network Coordinates](/docs/internals/coordinates) internals guide
for more information on how these coordinates are computed. for more information on how these coordinates are computed.
## Usage ## Usage

4
website/pages/docs/commands/services/deregister.mdx
View File

@ -16,8 +16,8 @@ be paired with `services register`.
This is just one method for service deregistration. If the service was This is just one method for service deregistration. If the service was
registered with a configuration file, then deleting that file and registered with a configuration file, then deleting that file and
[reloading](/docs/commands/reload.html) Consul is the correct method to [reloading](/docs/commands/reload) Consul is the correct method to
deregister. See [Service Definition](/docs/agent/services.html) for more deregister. See [Service Definition](/docs/agent/services) for more
information about registering services generally. information about registering services generally.
## Usage ## Usage

Some files were not shown because too many files have changed in this diff Show More