github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Sync docs from main

ap/main-docs
freddygv 2021-12-09 17:53:15 -07:00
parent 24e3ca2b28
commit f58392aa97
37 changed files with 563 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/Dockerfile
View File

@ -1,4 +1,4 @@
FROM docker.mirror.hashicorp.services/node:10.16.3-alpine
FROM docker.mirror.hashicorp.services/node:14.17.0-alpine
RUN apk add --update --no-cache git make g++ automake autoconf libtool nasm libpng-dev
COPY ./package.json /website/package.json

12
website/content/api-docs/acl/index.mdx
View File

@ -16,7 +16,7 @@ the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-s
## Bootstrap ACLs
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#acl_tokens_master)
management token if the [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management)
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,
and requires all Consul servers to be upgraded in order to operate.
@ -144,7 +144,7 @@ $ curl \
- `ReplicationType` - The type of replication that is currently in use.
- `legacy` - ACL replication is in legacy mode and is replicating legacy ACL tokens.
- `legacy` - (removed in Consul 1.11.0) ACL replication is in legacy mode and is replicating legacy ACL tokens.
- `policies` - ACL replication is only replicating policies as token replication
is disabled.
@ -181,8 +181,8 @@ $ curl \
## Translate Rules
-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system. It
will be removed in a future major Consul version when support for legacy ACLs is removed.
-> **Deprecated** - This endpoint was removed in Consul 1.11.0.
This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.
This endpoint translates the legacy rule syntax into the latest syntax. It is intended
to be used by operators managing Consul's ACLs and performing legacy token to new policy
@ -226,8 +226,8 @@ agent_prefix "" {
## Translate a Legacy Token's Rules
-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.. It
will be removed in a future major Consul version when support for legacy ACLs is removed.
-> **Deprecated** - This endpoint was removed in Consul 1.11.0.
This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.
This endpoint translates the legacy rules embedded within a legacy ACL into the latest
syntax. It is intended to be used by operators managing Consul's ACLs and performing

8
website/content/api-docs/acl/legacy.mdx
View File

@ -2,17 +2,17 @@
layout: api
page_title: Legacy ACLs - HTTP API
description: >-
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in
The legacy /acl endpoints to create, update, destroy, and query legacy ACL tokens in
Consul.
---
# ACL HTTP API
-> **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
-> **The legacy ACL system was deprecated in Consul 1.4.0 and removed in Consul 1.11.0.** It's _strongly_
recommended you do not build anything using the legacy system and use
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 legacy `/acl` endpoints to create, update, destroy, and query legacy ACL tokens in Consul.
For more information about ACLs, please check the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).

17
website/content/api-docs/agent/check.mdx
View File

@ -183,10 +183,14 @@ The table below shows this endpoint's support for
If TLS is enabled, then by default, a valid TLS certificate is expected. Certificate
verification can be turned off by setting `TLSSkipVerify` to `true`.
- `H2PING` `(string "")` - Specifies an address that uses http2 with TLS to run a ping check on.
- `H2PING` `(string "")` - Specifies an address that uses http2 to run a ping check on.
At the specified `Interval`, a connection is made to the address, and a ping is sent.
If the ping is successful, the check will be classified as `passing`, otherwise it will be marked as `critical`.
A valid SSL certificate is required by default, but verification can be removed with `TLSSkipVerify`.
TLS is used by default. To disable TLS and use h2c, set `H2PingUseTLS` to `false`.
If TLS is enabled, a valid SSL certificate is required by default, but verification can be removed with `TLSSkipVerify`.
- `H2PingUseTLS` `(bool: true)` - Specifies if TLS should be used for H2PING check.
If TLS is enabled, a valid SSL certificate is required by default, but verification can be removed with `TLSSkipVerify`.
- `HTTP` `(string: "")` - Specifies an `HTTP` check to perform a `GET` request
against the value of `HTTP` (expected to be a URL) every `Interval`. If the
@ -240,11 +244,16 @@ The table below shows this endpoint's support for
- `SuccessBeforePassing` `(int: 0)` - Specifies the number of consecutive successful
results required before check status transitions to passing. Available for HTTP,
TCP, gRPC, Docker & Monitor checks.
TCP, gRPC, Docker & Monitor checks. Added in Consul 1.7.0.
- `FailuresBeforeWarning` `(int: 0)` - Specifies the number of consecutive unsuccessful
results required before check status transitions to warning. Defaults to the same value
as `FailuresBeforeCritical`. Values higher than `FailuresBeforeCritical` are invalid.
Available for HTTP, TCP, gRPC, Docker & Monitor checks. Added in Consul 1.11.0.
- `FailuresBeforeCritical` `(int: 0)` - Specifies the number of consecutive unsuccessful
results required before check status transitions to critical. Available for HTTP,
TCP, gRPC, Docker & Monitor checks.
TCP, gRPC, Docker & Monitor checks. Added in Consul 1.7.0.
### Sample Payload

12
website/content/api-docs/agent/connect.mdx
View File

@ -169,10 +169,14 @@ The agent generates a CSR locally and calls the
is cached and returned by this API until it is near expiry or the root
certificates change.
This API supports blocking queries. The blocking query will block until
a new certificate is necessary because the existing certificate will expire
or the root certificate is being rotated. This blocking behavior allows
clients to efficiently wait for certificate rotations.
Non blocking queries to this endpoint will always check that the leaf certificate is not expired
and that the root certificates have not changed. Otherwise, a new leaf certificate is generated.
This API supports blocking queries. The blocking query will block until
a new certificate is necessary (because the existing certificate will expire, is expired,
or the root certificate is being rotated), or until the query timeout is reached. The current
query timeout is set to 10 minutes. This blocking behavior allows clients to
wait for certificate rotations.
| Method | Path | Produces |
| ------ | --------------------------------- | ------------------ |

23
website/content/api-docs/agent/index.mdx
View File

@ -727,18 +727,27 @@ only if the [`acl.enable_token_persistence`](/docs/agent/options#acl_enable_toke
configuration is `true`. When not being persisted, they will need to be reset if the agent
is restarted.
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `PUT` | `/agent/token/default` | `application/json` |
| `PUT` | `/agent/token/agent` | `application/json` |
| `PUT` | `/agent/token/agent_master` | `application/json` |
| `PUT` | `/agent/token/replication` | `application/json` |
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `PUT` | `/agent/token/default` | `application/json` |
| `PUT` | `/agent/token/agent` | `application/json` |
| `PUT` | `/agent/token/agent_recovery` | `application/json` |
| `PUT` | `/agent/token/replication` | `application/json` |
The paths above correspond to the token names as found in the agent configuration:
[`default`](/docs/agent/options#acl_tokens_default), [`agent`](/docs/agent/options#acl_tokens_agent),
[`agent_master`](/docs/agent/options#acl_tokens_agent_master), and
[`agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery), and
[`replication`](/docs/agent/options#acl_tokens_replication).
-> **Deprecation Note:** The following paths were deprecated in version 1.11
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `PUT` | `/agent/token/agent_master` | `application/json` |
The paths above correspond to the token names as found in the agent configuration:
[`agent_master`](/docs/agent/options#acl_tokens_agent_master).
-> **Deprecation Note:** The following paths were deprecated in version 1.4.3
| Method | Path | Produces |

6
website/content/api-docs/config.mdx
View File

@ -276,6 +276,12 @@ The table below shows this endpoint's support for
`X-Consul-Namespace` header. If not provided, the namespace will be inherited
from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0.
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. Unlike `PUT`,
the index must be greater than 0 for Consul to take any action: a 0 index will
not delete the config entry. If the index is non-zero, the config entry is only
deleted if the index matches the `ModifyIndex` of that config entry. This is
specified as part of the URL as a query parameter.
### Sample Request
```shell-session

9
website/content/api-docs/index.mdx
View File

@ -97,6 +97,15 @@ action if no intention matches.
This is returned even if ACLs are disabled.
## Results Filtered by ACLs
As of Consul 1.11, most list endpoints support an `X-Consul-Results-Filtered-By-ACLs`
HTTP response header. This indicates that the response contains a partial subset
of results, because some have been filtered out by ACL policies.
In order to limit information leakage, this header is only present for requests
authenticated by a valid ACL token.
## UUID Format
UUID-format identifiers generated by the Consul API use the

5
website/content/commands/acl/set-agent-token.mdx
View File

@ -28,8 +28,9 @@ Usage: `consul acl set-agent-token [options] TYPE TOKEN`
- `agent` - The token that the agent will use for internal agent operations.
If not given then the default token is used for these operations.
- `master` - This sets the token that can be used to access the Agent APIs in
the event that the ACL datacenter cannot be reached.
- `recovery` - This sets the token that can be used to access the Agent APIs
in the event that the ACL datacenter cannot be reached. In Consul versions
prior to 1.11, this token type was called `master`.
- `replication` - This is the token that the agent will use for replication
operations. This token will need to be configured with read access to

80
website/content/commands/admin-partition.mdx
View File

@ -1,32 +1,32 @@
---
layout: commands
page_title: 'Commands: admin-partition'
page_title: 'Commands: partition'
description: |
The admin-partition command enables you create and manage Consul Enterprise admin partitions.
The partition command enables you create and manage Consul Enterprise admin partitions.
---
# Consul Admin Partition
Command: `consul admin-partition`
Command: `consul partition`
<EnterpriseAlert />
The `admin-partition` command enables you to create and manage Consul Enterprise administrative or admin partitions. Admin partitions are boundaries that allow multiple tenants to exist independently of each other on a shared set of Consul servers. This feature is currently in beta.
The `partition` command enables you to create and manage Consul Enterprise administrative or admin partitions. Admin partitions are boundaries that allow multiple tenants to exist independently of each other on a shared set of Consul servers. This feature is currently in beta.
If ACLs are enabled then a token with operator privileges may be required in order to use this command.
If ACLs are enabled then a token with operator privileges may be required in order to use this command.
You should only run the `admin-partition` command in the primary datacenter.
You should only run the `partition` command in the primary datacenter.
## Usage
```shell-session
consul admin-partition <SUBCOMMAND> <OPTIONS>
consul partition <SUBCOMMAND> <OPTIONS>
```
Issue the `consul admin-partition -h` command to view the subcommands.
Issue the `consul partition -h` command to view the subcommands.
```shell-session
Usage: consul admin-partition <subcommand> [options] [args]
Usage: consul partition <subcommand> [options] [args]
This command has subcommands for interacting with Consul Enterprise
admin partitions. Here are some simple examples. More detailed
@ -34,41 +34,41 @@ Usage: consul admin-partition <subcommand> [options] [args]
Create an admin partition
$ consul admin-partition create -name team1
$ consul partition create -name team1
Create or Update an admin partition from its full definition:
$ consul admin-partition write part1
$ consul partition write part1
Read an admin partition:
$ consul admin-partition read team1
$ consul partition read team1
List all admin partitions:
$ consul admin-partition list
$ consul partition list
Update an admin partition
$ consul admin-partition update -name team1 -description "first admin-partition"
$ consul partition update -name team1 -description "first partition"
Delete an admin partition:
$ consul admin-partition delete team1
$ consul partition delete team1
For more examples, ask for subcommand help or view the documentation.
```
## Subcommands
You can issue the folloing subcommands with the `consul admin-partition` command.
You can issue the following subcommands with the `consul partition` command.
### `create`
The `create` subcommand sends a request to the server to create a new admin partition.
The `create` subcommand sends a request to the server to create a new admin partition.
```shell-session
consul admin-partition create <OPTIONS>
consul partition create <OPTIONS>
```
The admin partition is created according to the values specified in the options. You can specify the following options:
@ -78,12 +78,12 @@ The admin partition is created according to the values specified in the options.
| `-name` | String value that specifies the name for the new partition. | none | Required |
| `-description` &nbsp; &nbsp; &nbsp; &nbsp; | String value that specifies a description of the new partition. | none | Optional |
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
In the following example, a partition named `webdev` is created:
```shell-session
consul admin-partition create -name "webdev" -description "Partition for admin of webdev services" -format json -show-meta
consul partition create -name "webdev" -description "Partition for admin of webdev services" -format json -show-meta
{
"Name": "webdev",
@ -100,28 +100,28 @@ The `write` subcommand sends a request to the server to create a new admin parti
Use the following syntax to write from file:
```shell-session
consul admin-partition write <OPTIONS> <FILE>
consul partition write <OPTIONS> <FILE>
```
Use the following syntax to write from `stdin`:
```shell-session
consul admin-partition write <OPTIONS> -
consul partition write <OPTIONS> -
```
The definition file or `stdin` values can be provided in JSON or HCL format. Refer to the [Admin Partition Definition](#admin-partition-definition) section for details about the supported parameters.
The definition file or `stdin` values can be provided in JSON or HCL format. Refer to the [Admin Partition Definition](#partition-definition) section for details about the supported parameters.
You can specify the following options:
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
| `-show-meta` &nbsp; &nbsp; | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
| `-show-meta` &nbsp; &nbsp; | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
In the following example, the `webdev-bu` partition is written using `stdin` values:
```shell-session
consul admin-partition write -format json -show-meta - <<< 'name = "webdev-bu" description = "backup webdev partition"'
consul partition write -format json -show-meta - <<< 'name = "webdev-bu" description = "backup webdev partition"'
{
"Name": "webdev-bu",
@ -133,10 +133,10 @@ consul admin-partition write -format json -show-meta - <<< 'name = "webdev-bu"
### `read`
The `read` subcommand sends a request to the server to read the configuration for the specified partition and print it to the console.
The `read` subcommand sends a request to the server to read the configuration for the specified partition and print it to the console.
```shell-session
consul admin-partition read <OPTIONS> <PARTITION_NAME>
consul partition read <OPTIONS> <PARTITION_NAME>
```
The admin partition is created according to the values specified in the options. You can specify the following options:
@ -144,12 +144,12 @@ The admin partition is created according to the values specified in the options.
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `-format` &nbsp; &nbsp; | Specifies how to format the output of the operation in the console. | none | Optional |
| `-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
| `-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
In the following example, the configuration for the `webdev` partition is read:
```shell-session
consul admin-partition read -format json -meta webdev
consul partition read -format json -meta webdev
{
"Name": "webdev",
@ -160,10 +160,10 @@ consul admin-partition read -format json -meta webdev
### `list`
The `list` subcommand prints existing admin partitions to the console.
The `list` subcommand prints existing admin partitions to the console.
```shell-session
consul admin-partition list <OPTIONS>
consul partition list <OPTIONS>
```
The admin partition is created according to the values specified in the options. You can specify the following options:
@ -171,12 +171,12 @@ The admin partition is created according to the values specified in the options.
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `-format` | Specifies how to format the output of the operation in the console. | none | Optional |
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
| `-show-meta` | Prints the description and raft indices to the console in the response. <br/> This option does not take a value. Include the option when issuing the command to enable. | Disabled | Optional |
The following example lists the admin partitions and their meta data in JSON format:
```shell-session
consul admin-partition list -format json -show-meta
consul partition list -format json -show-meta
[
{
@ -201,26 +201,26 @@ consul admin-partition list -format json -show-meta
### `delete`
The `delete` subcommand sends a request to the server to remove the specified partition.
The `delete` subcommand sends a request to the server to remove the specified partition.
```shell-session
consul admin-partition delete <PARTITION_NAME>
consul partition delete <PARTITION_NAME>
```
In the following example, the `webdev-bu` partition is deleted:
```shell-session
consul admin-partition delete webdev
consul partition delete webdev
```
## Admin Partition Definition
Admin partitions are managed exclusively through the HTTP API and the Consul CLI. The HTTP API accepts only JSON formatted definitions while the CLI will parse either JSON or HCL.
The following parameters are supported in admin partition defintion files:
The following parameters are supported in admin partition definition files:
| Option | Description | Default | Required |
| --- | --- | --- | --- |
| `Name` | String value that specifies the name of partiion you are creating or writing. <br/> The value must be valid DNS hostname value. | none | Required |
| `Name` | String value that specifies the name of partition you are creating or writing. <br/> The value must be valid DNS hostname value. | none | Required |
| `Description` | String value that specifies a description for the partition you are creating or writing. <br/> The value should provide human-readable information to help other users understand the purpose of the partition. | none | Optional |
### Example Definition File
@ -234,7 +234,7 @@ Description = "Partition for dev team"
## HTTP API Options
You can include the following options to interact with the HTTP API when using the `admin-partition` command.
You can include the following options to interact with the HTTP API when using the `partition` command.
| Option | Description | Default | Required |
| --- | --- | --- | --- |
@ -242,6 +242,6 @@ You can include the following options to interact with the HTTP API when using t
| `-ca-path` | Specifies the path to a client certificate file when TLS is enabled. <br/> You can also specify `CONSUL_CAPATH` as the value if the environment variable is configured. | none | Required if TLS is enabled |
| `-client-cert` | Specifies the path to a client certificate file when TLS and the `verify_incoming` option are enabled. <br/> You can also specify `CONSUL_CLIENT_CERT` as the value if the environment variable is configured. | none | Required if TLS and `verify_incoming` are enabled |
| `-client-key` | Specifies the path to a client key file when TLS and the `verify_incoming` option are enabled. <br/> You can also specify `CONSUL_CLIENT_KEY` as the value if the environment variable is configured. | none | Required if TLS and `verify_incoming` are enabled |
| `-datacenter` &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Specifies the name of the datacenter to query. | Datacenter of the queried agent | Optional |
| `-datacenter` | Specifies the name of the datacenter to query. <br/> Non-default admin partitions are only supported in the primary datacenter. | Datacenter of the queried agent | Required if the agent is in a non-primary datacenter. |
| `-http-addr` | Specifies the address and port number of the Consul HTTP agent. <br/>IP and DNS addresses are supported. The address must also include the port. <br/>You can also specify `CONSUL_HTTP_ADDR` if the environment variable is configured. <br/>To use an HTTPS address, set the `CONSUL_HTTP_SSL` environment variable to `true`. | `http://127.0.0.1:8500` | Optional |
| `-stale` | Boolean value that enables any Consul server (non-leader) to respond to the request. <br/>This switch can lower latency and increase throughput, but may result in stale data. This option has no effect on non-read operations. | `false` | Optional |

8
website/content/commands/config/delete.mdx
View File

@ -31,6 +31,14 @@ Usage: `consul config delete [options]`
`proxy-defaults` config entry must be `global`, and the name of the `mesh`
config entry must be `mesh`.
- `-cas` - Perform a Check-And-Set operation. Specifying this value also
requires the -modify-index flag to be set. The default value is false.
- `-modify-index=<int>` - Unsigned integer representing the ModifyIndex of the
config entry. This is used in combination with the -cas flag.
## Examples
$ consul config delete -kind service-defaults -name web
$ consul config delete -kind service-defaults -name web -cas -modify-index 26

6
website/content/commands/debug.mdx
View File

@ -8,13 +8,13 @@ page_title: 'Commands: Debug'
Command: `consul debug`
The `consul debug` command monitors a Consul agent for the specified period of
time, recording information about the agent, cluster, and environment to an archive
time, recording information about the agent, cluster membership, and environment to an archive
written to the current directory.
Providing support for complex issues encountered by Consul operators often
requires a large amount of debugging information to be retrieved. This command
aims to shortcut that coordination and provide a simple workflow for accessing
data about Consul agent, cluster, and environment to enable faster
data about Consul agent, cluster membership, and environment to enable faster
isolation and debugging of issues.
This command requires an `operator:read` ACL token in order to retrieve the
@ -75,7 +75,7 @@ information when `debug` is running. By default, it captures all information.
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `cluster` | A list of all the WAN and LAN members in the cluster. |
| `members` | 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. |
| `logs` | `DEBUG` level logs for the target agent, captured for the duration. |
| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/docs/agent/options#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. |

125
website/content/docs/agent/options.mdx
View File

@ -213,6 +213,9 @@ The options below are all specified on the command-line.
DNS queries in an alternate domain, in addition to the primary domain. If unset,
no alternate domain is used.
In Consul 1.10.4 and later, Consul DNS responses will use the same domain as in the query (`-domain` or `-alt-domain`) where applicable.
PTR query responses will always use `-domain`, since the desired domain cannot be included in the query.
- `-enable-script-checks` ((#\_enable_script_checks)) This controls whether
[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
@ -228,7 +231,7 @@ The options below are all specified on the command-line.
Like [`enable_script_checks`](#_enable_script_checks), but only enable them when
they are defined in the local configuration files. Script checks defined in HTTP
API registrations will still not be allowed.
- `-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
@ -600,8 +603,10 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
token cannot be read from the [`primary_datacenter`](#primary_datacenter) or
leader node, the down policy is applied. In "allow" mode, all actions are permitted,
"deny" restricts all operations, and "extend-cache" allows any cached objects
to be used, ignoring their TTL values. If a non-cached ACL is used, "extend-cache"
acts like "deny". The value "async-cache" acts the same way as "extend-cache"
to be used, ignoring the expiry time of the cached entry. If the request uses an
ACL that is not in the cache, "extend-cache" falls back to the behaviour of
`default_policy`.
The value "async-cache" acts the same way as "extend-cache"
but performs updates asynchronously when ACL is present but its TTL is expired,
thus, if latency is bad between the primary and secondary datacenters, latency
of operations is not impacted.
@ -637,19 +642,25 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `tokens` ((#acl_tokens)) - This object holds all of the configured
ACL tokens for the agents usage.
- `master` ((#acl_tokens_master)) - Only used for servers in the [`primary_datacenter`](#primary_datacenter).
This token will be created with management-level permissions if it does not
exist. It allows operators to bootstrap the ACL system with a token Secret
ID that is well-known.
- `initial_management` ((#acl_tokens_initial_management)) - This is available in
Consul 1.11 and later. In prior versions, use [`acl.tokens.master`](#acl_tokens_master).
The `master` token is only installed when a server acquires cluster
leadership. If you would like to install or change the `acl_master_token`,
set the new value for `master` in the configuration for all servers. Once
this is done, restart the current leader to force a leader election. If
the `master` token is not supplied, then the servers do not create a
master token. When you provide a value, it should be a UUID. To maintain
backwards compatibility and an upgrade path this restriction is not
currently enforced but will be in a future major Consul release.
Only used for servers in the [`primary_datacenter`](#primary_datacenter).
This token will be created with management-level permissions if it does not exist.
It allows operators to bootstrap the ACL system with a token Secret ID that is
well-known.
The `initial_management` token is only installed when a server acquires cluster
leadership. If you would like to install or change it, set the new value for
`initial_management` in the configuration for all servers. Once this is done,
restart the current leader to force a leader election. If the `initial_management`
token is not supplied, then the servers do not create an initial management token.
When you provide a value, it should be a UUID. To maintain backwards compatibility
and an upgrade path this restriction is not currently enforced but will be in a
future major Consul release.
- `master` ((#acl_tokens_master)) **Renamed in Consul 1.11 to
[`acl.tokens.initial_management`](#acl_tokens_initial_management).**
- `default` ((#acl_tokens_default)) - When provided, the agent will
use this token when making requests to the Consul servers. Clients can override
@ -665,8 +676,16 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
register as in order to set any of the node-level information in the
catalog such as metadata, or the node's tagged addresses.
- `agent_master` ((#acl_tokens_agent_master)) - Used to access [agent endpoints](/api/agent)
that require agent read or write privileges, or node read privileges, even if Consul servers aren't present to validate any tokens. This should only be used by operators during outages, regular ACL tokens should normally be used by applications.
- `agent_recovery` ((#acl_tokens_agent_recovery)) - This is available in Consul 1.11
and later. In prior versions, use [`acl.tokens.agent_master`](#acl_tokens_agent_master).
Used to access [agent endpoints](/api/agent) that require agent read or write privileges,
or node read privileges, even if Consul servers aren't present to validate any tokens.
This should only be used by operators during outages, regular ACL tokens should normally
be used by applications.
- `agent_master` ((#acl_tokens_agent_master)) **Renamed in Consul 1.11 to
[`acl.tokens.agent_recovery`](#acl_tokens_agent_recovery).**
- `replication` ((#acl_tokens_replication)) - The ACL token used to
authorize secondary datacenters with the primary datacenter for replication
@ -738,17 +757,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
by allowing policies to be in place before enforcement begins.
- `acl_master_token` ((#acl_master_token_legacy)) - **Deprecated in Consul
1.4.0. See the [`acl.tokens.master`](#acl_tokens_master) field instead.** Only
used for servers in the [`primary_datacenter`](#primary_datacenter). This token
will be created with management-level permissions if it does not exist. It allows
operators to bootstrap the ACL system with a token ID that is well-known.
The `acl_master_token` is only installed when a server acquires cluster leadership. If
you would like to install or change the `acl_master_token`, set the new value for `acl_master_token`
in the configuration for all servers. Once this is done, restart the current leader to force a
leader election. If the `acl_master_token` is not supplied, then the servers do not create a master
token. When you provide a value, it can be any string value. Using a UUID would ensure that it looks
the same as the other tokens, but isn't strictly necessary.
1.4.0. See the [`acl.tokens.master`](#acl_tokens_master) field instead.**
- `acl_replication_token` ((#acl_replication_token_legacy)) - **Deprecated
in Consul 1.4.0. See the [`acl.tokens.replication`](#acl_tokens_replication) field
@ -756,10 +765,10 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
running Consul 0.7 or later. When provided, this will enable [ACL replication](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters)
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
ACL replication using [`enable_acl_replication`](#enable_acl_replication) and then
ACL replication using [`acl.enable_token_replication`](#acl_enable_token_replication) and then
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
set [`enable_acl_replication`](#enable_acl_replication) to true for backward compatibility.
set [`acl.enable_token_replication`](#acl_enable_token_replication) to true for backward compatibility.
If there's a partition or other outage affecting the authoritative datacenter, and the
[`acl_down_policy`](/docs/agent/options#acl_down_policy) is set to "extend-cache", tokens not
@ -823,6 +832,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
removed from the cluster. This may only be set on client agents and if unset then other nodes will use the main
`reconnect_timeout` setting when determining when this node may be removed from the cluster.
- `alt_domain` Equivalent to the [`-alt-domain` command-line flag](#_alt_domain)
- `serf_lan` ((#serf_lan_bind)) Equivalent to the [`-serf-lan-bind` command-line flag](#_serf_lan_bind).
This is an IP address, not to be confused with [`ports.serf_lan`](#serf_lan_port).
@ -870,6 +881,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
the rules governing how audit events are written.
The following keys are valid:
- `best-effort` - Consul only supports `best-effort` event delivery.
- `mode` - The permissions to set on the audit log files.
- `rotate_duration` - Specifies the
interval by which the system rotates to a new log file. At least one of `rotate_duration` or `rotate_bytes`
must be configured to enable audit logging.
@ -1057,6 +1069,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
- `segment` <EnterpriseAlert inline /> - The network segment name the client is requesting.
- `partition` <EnterpriseAlert inline /> - The admin partition name the client is requesting.
- `auto_encrypt` This object allows setting options for the `auto_encrypt` feature.
The following sub-keys are available:
@ -1260,6 +1274,16 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
for more than twice the _current_ `leaf_cert_ttl`, it will be removed
from the trusted list.
- `root_cert_ttl` ((#ca_root_cert_ttl)) The time to live (TTL) for a root certificate.
Defaults to 10 years as `87600h`. This value, if provided, needs to be higher than the
intermediate certificate TTL.
This setting applies to all Consul CA providers.
For the Vault provider, this value is only used if the backend is not initialized at first.
This value is also applied on the `ca set-config` command.
- `private_key_type` ((#ca_private_key_type)) The type of key to generate
for this CA. This is only used when the provider is generating a new key. If
`private_key` is set for the Consul provider, or existing root or intermediate
@ -1366,6 +1390,11 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
then all services on that node will be excluded because they are also considered
critical.
- `recursor_strategy` - If set to `sequential`, Consul will query recursors in the
order listed in the [`recursors`](#recursors) option. If set to `random`,
Consul will query an upstream DNS resolvers in a random order. Defaults to
`sequential`.
- `recursor_timeout` - Timeout used by Consul when
recursively querying an upstream DNS server. See [`recursors`](#recursors) for more details. Default is 2s. This is available in Consul 0.7 and later.
@ -1437,7 +1466,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
- `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` **Deprecated in Consul 1.11. Use the [`acl.enable_token_replication`](#acl_enable_token_replication) field instead.**
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
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.
@ -1740,6 +1770,16 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
- `protocol` ((#protocol)) Equivalent to the [`-protocol` command-line
flag](#_protocol).
- `raft_boltdb` ((#raft_boltdb)) This is a nested object that allows configuring
options for Raft's BoltDB based log store.
- `NoFreelistSync` ((#NoFreelistSync)) Setting this to `true` will disable
syncing the BoltDB freelist to disk within the raft.db file. Not syncing
the freelist to disk will reduce disk IO required for write operations
at the expense of potentially increasing start up time due to needing
to scan the db to discover where the free space resides within the file.
- `raft_protocol` ((#raft_protocol)) Equivalent to the [`-raft-protocol`
command-line flag](#_raft_protocol).
@ -2167,6 +2207,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
- `{{Service.Name}}` - Replaced with the current service's name.
- `{{Service.Namespace}}` - Replaced with the current service's namespace or empty if namespaces are not enabled.
- `{{Service.Partition}}` - Replaced with the current service's admin
partition or empty if admin partitions are not enabled.
- `{{Datacenter}}` - Replaced with the current service's datacenter.
- `ui_dir` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.dir`](#ui_config_dir) field instead.**
@ -2266,12 +2308,15 @@ signed by the CA can be used to gain full access to Consul.
endpoint was created by the CA that the consul client was setup with. If the
UI is served, the same checks are performed.
- `verify_incoming_rpc` - If set to true, Consul
requires that all incoming RPC connections make use of TLS and that the client
- `verify_incoming_rpc` - When set to true, Consul
requires that all incoming RPC connections use TLS and that the client
provides a certificate signed by a Certificate Authority from the [`ca_file`](#ca_file)
or [`ca_path`](#ca_path). By default, this is false, and Consul will not enforce
the use of TLS or verify a client's authenticity.
~> **Security Note:** `verify_incoming_rpc` _must_ be set to true to prevent anyone
with access to the RPC port from gaining full access to the Consul cluster.
- `verify_incoming_https` - If set to true,
Consul requires that all incoming HTTPS connections make use of TLS and that the
client provides a certificate signed by a Certificate Authority from the [`ca_file`](#ca_file)
@ -2293,14 +2338,12 @@ signed by the CA can be used to gain full access to Consul.
server unencrypted is to also enable `verify_incoming` which requires client
certificates too.
- `verify_server_hostname` - If set to true,
Consul verifies for all outgoing TLS connections that the TLS certificate
presented by the servers matches `server.<datacenter>.<domain>`
hostname. By default, this is false, and Consul does not verify the hostname
of the certificate, only that it is signed by a trusted CA. This setting is
_critical_ to prevent a compromised client from being restarted as a server
and having all cluster state _including all ACL tokens and Connect CA root keys_
replicated to it. This is new in 0.5.1.
- `verify_server_hostname` - When set to true, Consul verifies the TLS certificate
presented by the servers match the hostname `server.<datacenter>.<domain>`.
By default this is false, and Consul does not verify the hostname
of the certificate, only that it is signed by a trusted CA. This setting _must_ be enabled
to prevent a compromised client from gaining full read and write access to all
cluster data _including all ACL tokens and Connect CA root keys_. This is new in 0.5.1.
~> **Security Note:** From versions 0.5.1 to 1.4.0, due to a bug, setting
this flag alone _does not_ imply `verify_outgoing` and leaves client to server

34
website/content/docs/agent/telemetry.mdx
View File

@ -313,6 +313,9 @@ This is a full list of metrics emitted by Consul.
| `consul.state.nodes` | Measures the current number of nodes registered with Consul. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge |
| `consul.state.services` | Measures the current number of unique services registered with Consul, based on service name. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge |
| `consul.state.service_instances` | Measures the current number of unique service instances registered with Consul. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge |
| `consul.state.kv_entries` | Measures the current number of unique KV entries written in Consul. It is only emitted by Consul servers. Added in v1.10.3. | number of objects | gauge |
| `consul.state.connect_instances` | Measures the current number of unique connect service instances registered with Consul labeled by Kind (e.g. connect-proxy, connect-native, etc). Added in v1.10.4 | number of objects | gauge |
| `consul.state.config_entries` | Measures the current number of configuration entries registered with Consul labeled by Kind (e.g. service-defaults, proxy-defaults, etc). See [Configuration Entries](/docs/connect/config-entries) for more information. Added in v1.10.4 | number of objects | gauge |
| `consul.members.clients` | Measures the current number of client agents registered with Consul. It is only emitted by Consul servers. Added in v1.9.6. | number of clients | gauge |
| `consul.members.servers` | Measures the current number of server agents registered with Consul. It is only emitted by Consul servers. Added in v1.9.6. | number of servers | gauge |
| `consul.dns.stale_queries` | Increments when an agent serves a query within the allowed stale threshold. | queries | counter |
@ -328,8 +331,6 @@ These metrics are used to monitor the health of the Consul servers.
| Metric | Description | Unit | Type |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| `consul.acl.apply` | Measures the time it takes to complete an update to the ACL store. | ms | timer |
| `consul.acl.resolveTokenLegacy` | Measures the time it takes to resolve an ACL token using the legacy ACL system. | ms | timer |
| `consul.acl.ResolveToken` | Measures the time it takes to resolve an ACL token. | ms | timer |
| `consul.acl.ResolveTokenToIdentity` | Measures the time it takes to resolve an ACL token to an Identity. | ms | timer |
| `consul.acl.token.cache_hit` | Increments if Consul is able to resolve a token's identity, or a legacy token, from the cache. | cache read op | counter |
@ -341,11 +342,34 @@ These metrics are used to monitor the health of the Consul servers.
| `consul.raft.applied_index` | Represents the raft applied index. | index | gauge |
| `consul.raft.apply` | Counts the number of Raft transactions occurring over the interval, which is a general indicator of the write load on the Consul servers. | raft transactions / interval | counter |
| `consul.raft.barrier` | Counts the number of times the agent has started the barrier i.e the number of times it has issued a blocking call, to ensure that the agent has all the pending operations that were queued, to be applied to the agent's FSM. | blocks / interval | counter |
| `consul.raft.boltdb.freelistBytes` | Represents the number of bytes necessary to encode the freelist metadata. When `raft_boltdb.NoFreelistSync` is set to `false` these metadata bytes must also be written to disk for each committed log. | bytes | gauge |
| `consul.raft.boltdb.freePageBytes` | Represents the number of bytes of free space within the raft.db file. | bytes | gauge |
| `consul.raft.boltdb.getLog` | Measures the amount of time spent reading logs from the db. | ms | timer |
| `consul.raft.boltdb.logBatchSize` | Measures the total size in bytes of logs being written to the db in a single batch. | bytes | sample |
| `consul.raft.boltdb.logsPerBatch` | Measures the number of logs being written per batch to the db. | logs | sample |
| `consul.raft.boltdb.logSize` | Measures the size of logs being written to the db. | bytes | sample |
| `consul.raft.boltdb.numFreePages` | Represents the number of free pages within the raft.db file. | pages | gauge |
| `consul.raft.boltdb.numPendingPages` | Represents the number of pending pages within the raft.db that will soon become free. | pages | gauge |
| `consul.raft.boltdb.openReadTxn` | Represents the number of open read transactions against the db | transactions | guage |
| `consul.raft.boltdb.totalReadTxn` | Represents the total number of started read transactions against the db | transactions | guage |
| `consul.raft.boltdb.storeLogs` | Measures the amount of time spent writing logs to the db. | ms | timer |
| `consul.raft.boltdb.txstats.cursorCount` | Counts the number of cursors created since Consul was started. | cursors | counter |
| `consul.raft.boltdb.txstats.nodeCount` | Counts the number of node allocations within the db since Consul was started. | allocations | counter |
| `consul.raft.boltdb.txstats.nodeDeref` | Counts the number of node dereferences in the db since Consul was started. | dereferences | counter |
| `consul.raft.boltdb.txstats.pageAlloc` | Represents the number of bytes allocated within the db since Consul was started. Note that this does not take into account space having been freed and reused. In that case, the value of this metric will still increase. | bytes | gauge |
| `consul.raft.boltdb.txstats.pageCount` | Represents the number of pages allocated since Consul was started. Note that this does not take into account space having been freed and reused. In that case, the value of this metric will still increase. | pages | gauge |
| `consul.raft.boltdb.txstats.rebalance` | Counts the number of node rebalances performed in the db since Consul was started. | rebalances | counter |
| `consul.raft.boltdb.txstats.rebalanceTime` | Measures the time spent rebalancing nodes in the db. | ms | timer |
| `consul.raft.boltdb.txstats.spill` | Counts the number of nodes spilled in the db since Consul was started. | spills | counter |
| `consul.raft.boltdb.txstats.spillTime` | Measures the time spent spilling nodes in the db. | ms | timer |
| `consul.raft.boltdb.txstats.split` | Counts the number of nodes split in the db since Consul was started. | splits | counter |
| `consul.raft.boltdb.txstats.write` | Counts the number of writes to the db since Consul was started. | writes | counter |
| `consul.raft.boltdb.txstats.writeTime` | Measures the amount of time spent performing writes to the db. | ms | timer |
| `consul.raft.commitNumLogs` | Measures the count of logs processed for application to the FSM in a single batch. | logs | gauge |
| `consul.raft.commitTime` | Measures the time it takes to commit a new entry to the Raft log on the leader. | ms | timer |
| `consul.raft.fsm.lastRestoreDuration` | Measures the time taken to restore the FSM from a snapshot on an agent restart or from the leader calling installSnapshot. This is a gauge that holds it's value since most servers only restore during restarts which are typically infrequent. | ms | gauge |
| `consul.raft.fsm.snapshot` | Measures the time taken by the FSM to record the current state for the snapshot. | ms | timer |
| `consul.raft.fsm.apply` | The number of logs committed since the last interval. | commit logs / interval | counter |
| `consul.raft.fsm.apply` | Measures the time to apply a log to the FSM. | ms | timer |
| `consul.raft.fsm.enqueue` | Measures the amount of time to enqueue a batch of logs for the FSM to apply. | ms | timer |
| `consul.raft.fsm.restore` | Measures the time taken by the FSM to restore its state from a snapshot. | ms | timer |
| `consul.raft.last_index` | Represents the raft applied index. | index | gauge |
@ -380,7 +404,6 @@ These metrics are used to monitor the health of the Consul servers.
| `consul.catalog.deregister` | Measures the time it takes to complete a catalog deregister operation. | ms | timer |
| `consul.fsm.register` | Measures the time it takes to apply a catalog register operation to the FSM. | ms | timer |
| `consul.fsm.deregister` | Measures the time it takes to apply a catalog deregister operation to the FSM. | ms | timer |
| `consul.fsm.acl.` | Measures the time it takes to apply the given ACL operation to the FSM. | ms | timer |
| `consul.fsm.session.` | Measures the time it takes to apply the given session operation to the FSM. | ms | timer |
| `consul.fsm.kvs.` | Measures the time it takes to apply the given KV operation to the FSM. | ms | timer |
| `consul.fsm.tombstone.` | Measures the time it takes to apply the given tombstone operation to the FSM. | ms | timer |
@ -478,6 +501,9 @@ These metrics give insight into the health of the cluster as a whole.
| `consul.catalog.connect.query-tag..` | Increments for each connect-based catalog query for the given service with the given tag. | queries | counter |
| `consul.catalog.connect.query-tags..` | Increments for each connect-based catalog query for the given service with the given tags. | queries | counter |
| `consul.catalog.connect.not-found.` | Increments for each connect-based catalog query where the given service could not be found. | queries | counter |
| `consul.mesh.active-root-ca.expiry` | The number of seconds until the root CA expires, updated every hour. | seconds | gauge |
| `consul.mesh.active-signing-ca.expiry` | The number of seconds until the signing CA expires, updated every hour. | seconds | gauge |
| `consul.agent.tls.cert.expiry` | The number of seconds until the Agent TLS certificate expires, updated every hour. | seconds | gauge |
## Connect Built-in Proxy Metrics

42
website/content/docs/connect/ca/vault.mdx
View File

@ -88,25 +88,53 @@ The configuration options are listed below.
- `Address` / `address` (`string: <required>`) - The address of the Vault
server.
- `Token` / `token` (`string: <required>`) - A token for accessing Vault.
- `Token` / `token` (`string: ""`) - A token for accessing Vault.
This is write-only and will not be exposed when reading the CA configuration.
This token must have [proper privileges](#vault-acl-policies) for the PKI
paths configured. In Consul 1.8.5 and later, if the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable)
flag set, Consul will attempt to renew its lease periodically after half the
duration has expired.
!> **Warning:** You must either provide a token or configure an auth method below.
- `AuthMethod` / `auth_method` (`map: nil`) - Vault auth method to use for logging in to Vault.
Please see [Vault Auth Methods](https://www.vaultproject.io/docs/auth) for more information
on how to configure individual auth methods. If auth method is provided, Consul will obtain a
a new token from Vault when the token can no longer be renewed.
- `Type`/ `type` (`string: ""`) - The type of Vault auth method.
- `MountPath`/ `mount_path` (`string: <AuthMethod.Type>`) - The mount path of the auth method.
If not provided the auth method type will be used as the mount path.
- `Params`/`params` (`map: nil`) - The parameters to configure the auth method. Please see
[Vault Auth Methods](https://www.vaultproject.io/docs/auth) for information on how to configure the
auth method you wish to use. If using the Kubernetes auth method,
Consul will read the service account token from the
default mount path `/var/run/secrets/kubernetes.io/serviceaccount/token` if the `jwt` parameter
is not provided.
- `RootPKIPath` / `root_pki_path` (`string: <required>`) - The path to
a PKI secrets engine for the root certificate. If the path does not
exist, Consul will mount a new PKI secrets engine at the specified path with
exist, Consul will mount a new PKI secrets engine at the specified path with the
`RootCertTTL` value as the root certificate's TTL. If the `RootCertTTL` is not set,
a [`max_lease_ttl`](https://www.vaultproject.io/api/system/mounts#max_lease_ttl)
of 8760 hours, or 1 year. This TTL value specifies the expiry period of the
root certificate and is currently not configurable.
of 87600 hours, or 10 years is applied by default as of Consul 1.11 and later. Prior to Consul 1.11,
the root certificate TTL was set to 8760 hour, or 1 year, and was not configurable.
The root certificate will expire at the end of the specified period.
When WAN Federation is enabled, each secondary datacenter must use the same Vault cluster and share the same `root_pki_path`
with the primary datacenter.
- `IntermediatePKIPath` / `intermediate_pki_path` (`string: <required>`) -
The path to a PKI secrets engine for the generated intermediate certificate.
This certificate will be signed by the configured root PKI path. If this
path does not exist, Consul will attempt to mount and configure this
automatically.
automatically.
When WAN Federation is enabled, every secondary
datacenter must specify a unique `intermediate_pki_path`.
- `CAFile` / `ca_file` (`string: ""`) - Specifies an optional path to the CA
certificate used for Vault communication. If unspecified, this will fallback
@ -131,6 +159,10 @@ The configuration options are listed below.
- `TLSSkipVerify` / `tls_skip_verify` (`bool: false`) - Specifies if SSL peer
validation should be enforced.
- `Namespace` / `namespace` (`string: <optional>`) - The Vault Namespace that
the `Token` and PKI Certificates are a part of. Vault Namespaces are a Vault
Enterprise feature. Added in Consul 1.11.0
@include 'http_api_connect_ca_common_options.mdx'
## Root and Intermediate PKI Paths

66
website/content/docs/connect/config-entries/ingress-gateway.mdx
View File

@ -397,9 +397,13 @@ spec:
<Tabs>
<Tab heading="Consul OSS">
Set up a HTTP listener on an ingress gateway named "us-east-ingress" to proxy
Set up an HTTP listener on an ingress gateway named "us-east-ingress" to proxy
traffic to a virtual service named "api".
Additionally, ensure internal-only debug headers are stripped before responding
to external clients, and that requests to internal services are labelled to
indicate which gateway they came through.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
```hcl
@ -413,6 +417,14 @@ Listeners = [
Services = [
{
Name = "api"
RequestHeaders {
Add {
"x-gateway" = "us-east-ingress"
}
}
ResponseHeaders {
Remove = ["x-debug"]
}
}
]
}
@ -430,6 +442,7 @@ spec:
protocol: http
services:
- name: api
# HTTP Header manipulation is not yet supported in Kubernetes CRD
```
```json
@ -442,7 +455,15 @@ spec:
"Protocol": "http",
"Services": [
{
"Name": "api"
"Name": "api",
"RequestHeaders": {
"Add": {
"x-gateway": "us-east-ingress"
}
},
"ResponseHeaders": {
"Remove": ["x-debug"]
}
}
]
}
@ -455,9 +476,13 @@ spec:
</Tab>
<Tab heading="Consul Enterprise">
Set up a HTTP listener on an ingress gateway named "us-east-ingress" in the
Set up an HTTP listener on an ingress gateway named "us-east-ingress" in the
default namespace to proxy traffic to a virtual service named "api".
Additionally, ensure internal-only debug headers are stripped before responding
to external clients, and that requests to internal services are labelled to
indicate which gateway they came through.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
```hcl
@ -473,6 +498,14 @@ Listeners = [
{
Name = "api"
Namespace = "frontend"
RequestHeaders {
Add {
"x-gateway" = "us-east-ingress"
}
}
ResponseHeaders {
Remove = ["x-debug"]
}
}
]
}
@ -492,6 +525,7 @@ spec:
services:
- name: api
namespace: frontend
# HTTP Header manipulation is not yet supported in Kubernetes CRD
```
```json
@ -506,7 +540,15 @@ spec:
"Services": [
{
"Name": "api",
"Namespace": "frontend"
"Namespace": "frontend",
"RequestHeaders": {
"Add": {
"x-gateway": "us-east-ingress"
}
},
"ResponseHeaders": {
"Remove": ["x-debug"]
}
}
]
}
@ -838,6 +880,22 @@ spec:
records. For example, \`*.example.com\` is valid, while \`example.*\` and
\`*-suffix.example.com\` are not.`,
},
{
yaml: false,
name: 'RequestHeaders',
type: 'HTTPHeaderModifiers: <optional>',
description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
that will be applied to requests routed to this service.
This cannot be used with a \`tcp\` listener.`,
},
{
yaml: false,
name: 'ResponseHeaders',
type: 'HTTPHeaderModifiers: <optional>',
description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
that will be applied to responses from this service.
This cannot be used with a \`tcp\` listener.`,
},
],
},
],

65
website/content/docs/connect/config-entries/service-router.mdx
View File

@ -574,6 +574,71 @@ spec:
description:
'A list of HTTP response status codes that are eligible for retry.',
},
{
yaml: false,
name: 'RequestHeaders',
type: 'HTTPHeaderModifiers: <optional>',
description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
that will be applied to requests routed to this service.
This cannot be used with a \`tcp\` listener.`,
},
{
yaml: false,
name: 'ResponseHeaders',
type: 'HTTPHeaderModifiers: <optional>',
description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
that will be applied to responses from this service.
This cannot be used with a \`tcp\` listener.`,
},
]}
/>
### `HTTPHeaderModifiers`
<ConfigEntryReference
topLevel={false}
yaml={false}
keys={[
{
hcl: false,
name: 'Unsupported',
type: '',
description: `HTTP Header modification is not yet supported in our Kubernetes CRDs.`,
},
{
yaml: false,
name: 'Add',
type: 'map<string|string>: optional',
description: `The set of key/value pairs that specify header values to add.
Use header names as keys. Header names are _not_ case-sensitive.
If header values with the same name already exist, the value set here will
be appended and both will be present.
If Envoy is used as the proxy, the value may contain
[variable placeholders](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#custom-request-response-headers) for example
\`%DOWNSTREAM_REMOTE_ADDRESS%\` to interpolate dynamic request
metadata into the value added.`,
},
{
yaml: false,
name: 'Set',
type: 'map<string|string>: optional',
description: `The set of key/value pairs that specify header values to add.
Use header names as keys. Header names are _not_ case-sensitive.
If header values with the same name already exist, the value set here will
_replace_ them.
If Envoy is used as the proxy, the value may contain
[variable placeholders](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#custom-request-response-headers) for example
\`%DOWNSTREAM_REMOTE_ADDRESS%\` to interpolate dynamic request
metadata into the value added.`,
},
{
yaml: false,
name: 'Remove',
type: 'array<string>: optional',
description: `The set of header names to remove. Only headers
whose names are a <i>case-insensitive</i> exact match will be removed`,
},
]}
/>

82
website/content/docs/connect/config-entries/service-splitter.mdx
View File

@ -109,7 +109,7 @@ Splits = [
# will default to service with same name as config entry ("web")
},
{
Weight = 10
Weight = 50
Service = "web-rewrite"
},
]
@ -124,7 +124,7 @@ spec:
splits:
- weight: 50
# will default to service with same name as config entry ("web")
- weight: 10
- weight: 50
service: web-rewrite
```
@ -146,6 +146,68 @@ spec:
</CodeTabs>
### Set HTTP Headers
Split traffic between two subsets with extra headers added so clients can tell
which version (not yet supported in Kubernetes CRD):
<CodeTabs tabs={[ "HCL", "JSON" ]}>
```hcl
Kind = "service-splitter"
Name = "web"
Splits = [
{
Weight = 90
ServiceSubset = "v1"
ResponseHeaders {
Set {
"X-Web-Version": "v1"
}
}
},
{
Weight = 10
ServiceSubset = "v2"
ResponseHeaders {
Set {
"X-Web-Version": "v2"
}
}
},
]
```
```json
{
"Kind": "service-splitter",
"Name": "web",
"Splits": [
{
"Weight": 90,
"ServiceSubset": "v1",
"ResponseHeaders": {
"Set": {
"X-Web-Version": "v1"
}
}
},
{
"Weight": 10,
"ServiceSubset": "v2",
"ResponseHeaders": {
"Set": {
"X-Web-Version": "v2"
}
}
}
]
}
```
</CodeTabs>
## Available Fields
<ConfigEntryReference
@ -231,6 +293,22 @@ spec:
description:
'The namespace to resolve the service from instead of the current namespace. If empty the current namespace is assumed.',
},
{
yaml: false,
name: 'RequestHeaders',
type: 'HTTPHeaderModifiers: <optional>',
description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
that will be applied to requests routed to this split.
This cannot be used with a \`tcp\` listener.`,
},
{
yaml: false,
name: 'ResponseHeaders',
type: 'HTTPHeaderModifiers: <optional>',
description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
that will be applied to responses from this split.
This cannot be used with a \`tcp\` listener.`,
},
],
},
]}

3
website/content/docs/connect/observability/ui-visualization.mdx
View File

@ -104,7 +104,8 @@ ui_config {
dashboard_url_templates {
service = "https://grafana.example.com/d/lDlaj-NGz/
service-overview?orgId=1&var-service={{Service.Name}}&
var-namespace={{Service.Namespace}}&var-dc={{Datacenter}}"
var-namespace={{Service.Namespace}}&
var-partition={{Service.Partition}}&var-dc={{Datacenter}}"
}
}
```

4
website/content/docs/connect/proxies/built-in.mdx
View File

@ -51,7 +51,7 @@ for the built-in proxy.
}
```
All fields are optional with a sane default.
All fields are optional with a reasonable default.
- `bind_address` - The address the proxy will bind its
_public_ mTLS listener to. It defaults to the same address the agent binds to.
@ -86,7 +86,7 @@ All fields are optional with a sane default.
## Proxy Upstream Config Key Reference
All fields are optional with a sane default.
All fields are optional with a reasonable default.
- `connect_timeout_ms` - The number of milliseconds
the proxy will wait to establish a TLS connection to the discovered upstream instance

2
website/content/docs/connect/proxies/envoy.mdx
View File

@ -35,7 +35,7 @@ compatible Envoy versions.
| Consul Version | Compatible Envoy Versions |
| ------------------- | ------------------------------------------------------ |
| 1.11.x | 1.19.1, 1.18.4, 1.17.4, 1.16.5 |
| 1.11.x | 1.20.0, 1.19.1, 1.18.4, 1.17.4 |
| 1.10.x | 1.18.4, 1.17.4, 1.16.5, 1.15.5 |
| 1.9.x | 1.16.5, 1.15.5, 1.14.7<sup>1</sup>, 1.13.7<sup>1</sup> |
| 1.8.x | 1.14.7, 1.13.7, 1.12.7, 1.11.2 |

2
website/content/docs/connect/proxies/integrate.mdx
View File

@ -218,4 +218,4 @@ ID for the name specified in `-sidecar-for` flag.
[`consul/connect/tls.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/tls.go#L232-L237
[discovery chain]: /docs/connect/l7-traffic/discovery-chain
[`usecache`]: https://github.com/hashicorp/consul/blob/v1.8.3/api/api.go#L99-L102
[protocol]: /docs/connect/config-entries/service-defaults#protocol
[protocol]: /docs/connect/config-entries/service-defaults#protocol

2
website/content/docs/connect/proxies/managed-deprecated.mdx
View File

@ -64,7 +64,7 @@ token is more restrictive than can be currently expressed manually in
an ACL policy.
The default managed proxy is a basic proxy built-in to Consul and written
in Go. Having a basic built-in proxy allows Consul to have a sane default
in Go. Having a basic built-in proxy allows Consul to have a reasonable default
with performance that is good enough for most workloads. In some basic
benchmarks, the service-to-service communication over the built-in proxy
could sustain 5 Gbps with sub-millisecond latency. Therefore,

2
website/content/docs/connect/registration/service-registration.mdx
View File

@ -559,4 +559,4 @@ There is no mode field since the service is expected to create the
socket it is listening on, not the Envoy proxy.
Again, the `socket_path` and `local_service_socket_path` fields conflict
with `address`/`port` and `local_service_address`/`local_service_port`
configuration options.
configuration options.

28
website/content/docs/discovery/checks.mdx
View File

@ -120,10 +120,11 @@ There are several different kinds of checks:
`tls_skip_verify` field to `true` in the check definition.
To check on a specific service instead of the whole gRPC server, add the service identifier after the `gRPC` check's endpoint in the following format `/:service_identifier`.
- `H2ping + Interval` - These checks test an endpoint that uses http2 with TLS
by connecting to the endpoint and sending a ping frame. If the ping is successful
- `H2ping + Interval` - These checks test an endpoint that uses http2
by connecting to the endpoint and sending a ping frame. TLS is assumed to be configured by default.
To disable TLS and use h2c, set `h2ping_use_tls` to `false`. If the ping is successful
within a specified timeout, then the check is updated as passing.
The timeout defaults to 10 seconds, but is configurable using the `timeout` field. A valid
The timeout defaults to 10 seconds, but is configurable using the `timeout` field. If TLS is enabled a valid
certificate is required, unless `tls_skip_verify` is set to `true`.
The check will be run on the interval specified by the `interval` field.
@ -164,7 +165,7 @@ A HTTP check:
"tls_server_name": "",
"tls_skip_verify": false,
"method": "POST",
"header": {"Content-Type": ["application/json"]},
"header": { "Content-Type": ["application/json"] },
"body": "{\"method\":\"health\"}",
"interval": "10s",
"timeout": "1s"
@ -251,6 +252,7 @@ A h2ping check:
"name": "h2ping",
"h2ping": "localhost:22222",
"interval": "10s",
"h2ping_use_tls": false
}
}
```
@ -413,12 +415,23 @@ key in your configuration file.
}
```
## Success/Failures before passing/critical
## Success/Failures before passing/warning/critical
In Consul 1.7.0 and later, a check may be configured to become passing/critical
only after a specified number of consecutive checks return passing/critical.
To prevent flapping health checks, and limit the load they cause on the cluster,
a health check may be configured to become passing/warning/critical only after a
specified number of consecutive checks return passing/critical.
The status will not transition states until the configured threshold is reached.
- `success_before_passing` - Number of consecutive successful results required
before check status transitions to passing. Defaults to `0`. Added in Consul 1.7.0.
- `failures_before_warning` - Number of consecutive unsuccessful results required
before check status transitions to warning. Defaults to the same value as that of
`failures_before_critical` to maintain the expected behavior of not changing the
status of serivce checks to `warning` before `critical` unless configured to do so.
Values higher than `failures_before_critical` are invalid. Added in Consul 1.11.0.
- `failures_before_critical` - Number of consecutive unsuccessful results required
before check status transitions to critical. Defaults to `0`. Added in Consul 1.7.0.
This feature is available for HTTP, TCP, gRPC, Docker & Monitor checks.
By default, both passing and critical thresholds will be set to 0 so the check
status will always reflect the last check result.
@ -432,6 +445,7 @@ status will always reflect the last check result.
"interval": "10s",
"timeout": "1s",
"success_before_passing": 3,
"failures_before_warning": 1,
"failures_before_critical": 3
}
]

6
website/content/docs/discovery/dns.mdx
View File

@ -21,9 +21,9 @@ are located in the `us-east-1` datacenter, and have no failing health checks.
It's that simple!
There are a number of configuration options that are important for the DNS interface,
specifically [`client_addr`](/docs/agent/options#client_addr),
[`ports.dns`](/docs/agent/options#dns_port), [`recursors`](/docs/agent/options#recursors),
[`domain`](/docs/agent/options#domain), and [`dns_config`](/docs/agent/options#dns_config).
specifically [`client_addr`](/docs/agent/options#client_addr),[`ports.dns`](/docs/agent/options#dns_port),
[`recursors`](/docs/agent/options#recursors),[`domain`](/docs/agent/options#domain),
[`alt_domain`](/docs/agent/options#alt_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.`
domain, without support for further DNS recursion. Please consult the
[documentation on configuration options](/docs/agent/options),

2
website/content/docs/dynamic-app-config/kv.mdx
View File

@ -7,7 +7,7 @@ description: Consul KV is a core feature of Consul and is installed with the Con
# Consul KV
Consul KV is a core feature of Consul and is installed with the Consul agent.
Once installed with the agent, it will have sane defaults. Consul KV allows
Once installed with the agent, it will have reasonable defaults. Consul KV allows
users to store indexed objects, though its main uses are storing configuration
parameters and metadata. Please note that it is a simple KV store and is not
intended to be a full featured datastore (such as DynamoDB) but has some

2
website/content/docs/enterprise/admin-partitions.mdx
View File

@ -241,4 +241,4 @@ You can use create and manage admin partitions through the CLI. Refer to the [ad
* Gossip between nodes in different admin partitions must be constrained. You can accomplish this with through the use of [network segments](network-segments).
* Cross-partition communication is not currently supported.
* Partitions can only be created in the primary datacenter.
* Partitions can only be created in the primary datacenter.

2
website/content/docs/k8s/crds/index.mdx
View File

@ -418,4 +418,4 @@ spec:
In addition, we support the field `spec.destination.namespace` to configure
the destination service's Consul namespace. If `spec.destination.namespace`
is empty, then the Consul namespace used will be the same as the other
config entries as outlined above.
config entries as outlined above.

5
website/content/docs/security/acl/acl-legacy.mdx
View File

@ -13,8 +13,9 @@ description: >-
-> **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**
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). For information on how to migrate to the new ACL System, please read the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/tutorials/consul/access-control-token-migration) tutorial.
The ACL system described here was Consul's original ACL implementation.
The legacy ACL system was deprecated in Consul 1.4.0 and removed in Consul 1.11.0.
The documentation for the new ACL system can be found [here](/docs/acl/acl-system). For information on how to migrate to the new ACL System, please read the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/tutorials/consul/access-control-token-migration) tutorial.
The legacy documentation has two sections.

2
website/content/docs/security/acl/acl-rules.mdx
View File

@ -493,7 +493,7 @@ with `bar`.
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
configured with [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) to allow
configured with [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) to allow
write access to these operations even if no ACL resolution capability is available.
### Event Rules

36
website/content/docs/security/acl/acl-system.mdx
View File

@ -202,16 +202,17 @@ the token itself.
#### Builtin Tokens
During cluster bootstrapping when ACLs are enabled both the special `anonymous` and the `master` token will be
During cluster bootstrapping when ACLs are enabled both the special `anonymous` and the `initial_management` token will be
injected.
- **Anonymous Token** - The anonymous token is used when a request is made to Consul without specifying a bearer token.
The anonymous token's description and policies may be updated but Consul will prevent this token's deletion. When created,
it will be assigned `00000000-0000-0000-0000-000000000002` for its Accessor ID and `anonymous` for its Secret ID.
- **Master Token** - When a master token is present within the Consul configuration, it is created and will be linked
With the builtin Global Management policy giving it unrestricted privileges. The master token is created with the Secret ID
set to the value of the configuration entry.
- **Initial Management Token** - When an initial management token is present within the Consul configuration, it is created
and will be linked with the builtin Global Management policy giving it unrestricted privileges. The initial management
token is created with the Secret ID set to the value of the configuration entry.
In Consul 1.4 - 1.10, this was called the `master` token. It was renamed to `initial_management` token in Consul 1.11.
#### Authorization
@ -291,18 +292,27 @@ as to whether they are set on servers, clients, or both.
A number of special tokens can also be configured which allow for bootstrapping the ACL
system, or accessing Consul in special situations:
| Special Token | Servers | Clients | Purpose |
| ------------------------------------------------------------------------ | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`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#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#acl_tokens_master) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, check the [Bootstrapping ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) tutorial for more details |
| [`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 |
| Special Token | Servers | Clients | Purpose |
| ------------------------------------------------------------------------------------ | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | `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 Recovery Token](#acl-agent-recovery-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.initial_management`](/docs/agent/options#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Special token used to bootstrap the ACL system, check the [Bootstrapping ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) tutorial for more details |
| [`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#update-acl-tokens).
All of these tokens except the `initial_management` token can all be introduced or updated via the [/v1/agent/token API](/api/agent#update-acl-tokens).
#### ACL Agent Master Token
In Consul 1.4 - 1.10, the following special tokens were known by different names:
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
| New Name (1.11+) | Old Name (1.4 - 1.10) |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) | [`acl.tokens.agent_master`](/docs/agent/options#acl_tokens_agent_master) |
| [`acl.tokens.initial_management`](/docs/agent/options#acl_tokens_initial_management) | [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) |
#### ACL Agent Recovery Token
Since the [`acl.tokens.agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery) 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
In Consul 1.4 - 1.10, this was called the `agent_master` token. It was renamed to `agent_recovery` token in Consul 1.11.
```hcl
agent "<node name of agent>" {

1
website/content/docs/upgrading/index.mdx
View File

@ -25,6 +25,7 @@ For upgrades we strive to ensure backwards compatibility. To support this,
nodes gossip their protocol version and builds. This enables clients and
servers to intelligently enable new features when available, or to gracefully
fallback to a backward compatible mode of operation otherwise.
Visit the [General Upgrade Process](https://www.consul.io/docs/upgrading/instructions/general-process) for a detailed upgrade guide.
For most upgrades, the process is simple. Assuming the current version of
Consul is A, and version B is released.

17
website/content/docs/upgrading/upgrade-specific.mdx
View File

@ -14,6 +14,20 @@ provided for their upgrades as a result of new features or changed behavior.
This page is used to document those details separately from the standard
upgrade flow.
## Consul 1.11.0
### Envoy xDS Protocol Upgrades
As noted in earlier upgrades, previous versions of Consul supported both v2 and v3
variants of the XDS Transport Protocol. In Consul 1.11, support for Envoy 1.16 is
removed and consequently v2 is no longer supported. What this means is that if
you have generated your Envoy bootstrap files using the Consul CLI that is newer
than 1.10, you must make sure that you upgrade Consul and Envoy per the
[Stairstep Upgrade Path](#stairstep-upgrade-path) before upgrading to Consul 1.11.
When upgrading to Consul 1.10, you must ensure that the Envoy sidecars are
restarted and bootstrapped using a version of the Consul CLI >= 1.10. This
ensures your sidecars are supported by Consul 1.11.
## Consul 1.10.0
### Licensing Changes <EnterpriseAlert inline />
@ -51,8 +65,7 @@ protocol variant as the preferred way of conversing with Envoy. Both protocol
variants are supported in this Consul version to facilitate upgrading Consul
and Envoy in a stairstep order to avoid downtime.
In a future version of Consul the v2 State of the World protocol support will
be removed.
In [Consul 1.11](#consul-1-11-0) the v2 State of the World protocol support will be removed.
| Protocol | Version | Compatible Envoy Versions | Compatible Consul Versions |
| ------------------ | ------- | ------------------------------ | -------------------------- |

8
website/content/partials/http_api_connect_ca_common_options.mdx
View File

@ -35,6 +35,14 @@ The following configuration options are supported by all CA providers:
for more than twice the _current_ `leaf_cert_ttl`, it will be removed
from the trusted list.
- `RootCertTTL` / `root_cert_ttl` (`duration: "87600h"`) The time to live (TTL) for a root certificate.
Defaults to 10 years as `87600h`. This value, if provided, needs to be higher than the
intermediate certificate TTL.
This setting applies to all Consul CA providers.
For the Vault provider, this value is only used if the backend is not initialized at first.
- `PrivateKeyType` / `private_key_type` (`string: "ec"`) - The type of key to generate
for this CA. This is only used when the provider is generating a new key. If
`private_key` is set for the Consul provider, or existing root or intermediate

2
website/package.json
View File

@ -74,7 +74,7 @@
"generate:component": "next-hashicorp generate component",
"generate:readme": "next-hashicorp markdown-blocks README.md",
"lint": "next-hashicorp lint",
"start": "next-remote-watch ./content/**/*.mdx",
"start": "next-remote-watch './content/**/*.mdx'",
"static": "npm run build && npm run export && cp _redirects out/.",
"linkcheck": "linkcheck https://consul.io"
},

2
website/pages/home/index.jsx
View File

@ -25,7 +25,7 @@ export default function HomePage({ serviceMeshIngressGatewayCode }) {
external: false,
title: 'Try HCP Consul',
url:
'https://portal.cloud.hashicorp.com/sign-up?utm_source=docs&utm_content=consul_hero',
'https://portal.cloud.hashicorp.com/sign-up?utm_source=consul_io&utm_content=consul_hero',
},
{
external: false,