status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: fix external links to agent config pages

This commit is contained in:
Natalie Smith 2022-01-10 13:13:13 -08:00 committed by Blake Covarrubias
parent 83f9879b2d
commit ddae7d18a2
82 changed files with 422 additions and 418 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/cluster-federation/network-areas/README.md
View File

@ -35,7 +35,7 @@ Every Consul Enterprise server maintains a reconciliation routine where every 30
Joining a network area pool involves: Joining a network area pool involves:
1. Setting memberlist and Serf configuration. 1. Setting memberlist and Serf configuration.
* Prior to Consul `v1.8.11` and `v1.9.5`, network areas were configured with memberlist's [DefaultWANConfig](https://github.com/hashicorp/memberlist/blob/838073fef1a4e1f6cb702a57a8075304098b1c31/config.go#L315). This was then updated to instead use the server's [gossip_wan](https://www.consul.io/docs/agent/options#gossip_wan) configuration, which falls back to the DefaultWANConfig if it was not specified. * Prior to Consul `v1.8.11` and `v1.9.5`, network areas were configured with memberlist's [DefaultWANConfig](https://github.com/hashicorp/memberlist/blob/838073fef1a4e1f6cb702a57a8075304098b1c31/config.go#L315). This was then updated to instead use the server's [gossip_wan](https://www.consul.io/docs/agent/config/agent-config-files#gossip_wan) configuration, which falls back to the DefaultWANConfig if it was not specified.
* As of Consul `v1.8.11`/`v1.9.5` it is not possible to tune gossip communication on a per-area basis. * As of Consul `v1.8.11`/`v1.9.5` it is not possible to tune gossip communication on a per-area basis.
2. Update the server's gossip network, which keeps track of network areas that the server is a part of. This gossip network is also used to dispatch incoming **gossip** connections to handlers for the appropriate area. 2. Update the server's gossip network, which keeps track of network areas that the server is a part of. This gossip network is also used to dispatch incoming **gossip** connections to handlers for the appropriate area.

6
docs/config/README.md
View File

@ -10,10 +10,10 @@ specified using command line flags, and some can be loaded with [Auto-Config].
See also the [checklist for adding a new field] to the configuration. See also the [checklist for adding a new field] to the configuration.
[hcl]: https://github.com/hashicorp/hcl/tree/hcl1 [hcl]: https://github.com/hashicorp/hcl/tree/hcl1
[Agent Configuration]: https://www.consul.io/docs/agent/options [Agent Configuration]: https://www.consul.io/docs/agent/config
[checklist for adding a new field]: ./checklist-adding-config-fields.md [checklist for adding a new field]: ./checklist-adding-config-fields.md
[Auto-Config]: #auto-config [Auto-Config]: #auto-config
[Config Entries]: https://www.consul.io/docs/agent/options#config_entries [Config Entries]: https://www.consul.io/docs/agent/config/agent-config-files#config_entries
[Services]: https://www.consul.io/docs/discovery/services [Services]: https://www.consul.io/docs/discovery/services
[Checks]: https://www.consul.io/docs/discovery/checks [Checks]: https://www.consul.io/docs/discovery/checks
@ -53,6 +53,6 @@ implemented in a couple packages.
* the server RPC endpoint is in [agent/consul/auto_config_endpoint.go] * the server RPC endpoint is in [agent/consul/auto_config_endpoint.go]
* the client that receives and applies the config is implemented in [agent/auto-config] * the client that receives and applies the config is implemented in [agent/auto-config]
[auto_config]: https://www.consul.io/docs/agent/options#auto_config [auto_config]: https://www.consul.io/docs/agent/config/agent-config-files#auto_config
[agent/consul/auto_config_endpoint.go]: https://github.com/hashicorp/consul/blob/main/agent/consul/auto_config_endpoint.go [agent/consul/auto_config_endpoint.go]: https://github.com/hashicorp/consul/blob/main/agent/consul/auto_config_endpoint.go
[agent/auto-config]: https://github.com/hashicorp/consul/tree/main/agent/auto-config [agent/auto-config]: https://github.com/hashicorp/consul/tree/main/agent/auto-config

4
docs/config/checklist-adding-config-fields.md
View File

@ -55,7 +55,7 @@ There are four specific cases covered with increasing complexity:
state for client agent's RPC client. state for client agent's RPC client.
- [ ] Add a test to `agent/agent_test.go` similar to others with prefix - [ ] Add a test to `agent/agent_test.go` similar to others with prefix
`TestAgent_reloadConfig*`. `TestAgent_reloadConfig*`.
- [ ] Add documentation to `website/content/docs/agent/options.mdx`. - [ ] Add documentation to `website/content/docs/agent/config/agent-config-files.mdx`.
Done! You can now use your new field in a client agent by accessing Done! You can now use your new field in a client agent by accessing
`s.agent.Config.<FieldName>`. `s.agent.Config.<FieldName>`.
@ -75,7 +75,7 @@ If the config field also needs a CLI flag, then follow these steps.
`TestLoad_IntegrationWithFlags` in `agent/config/runtime_test.go` to ensure setting the `TestLoad_IntegrationWithFlags` in `agent/config/runtime_test.go` to ensure setting the
flag works. flag works.
- [ ] Add flag (as well as config file) documentation to - [ ] Add flag (as well as config file) documentation to
`website/source/docs/agent/options.html.md`. `website/source/docs/agent/config/agent-config-files.mdx` and `website/source/docs/agent/config/agent-config-cli.mdx`.
## Adding a Simple Config Field for Servers ## Adding a Simple Config Field for Servers
Consul servers have a separate Config struct for reasons. Note that Consul Consul servers have a separate Config struct for reasons. Note that Consul

2
docs/rpc/README.md
View File

@ -22,7 +22,7 @@ The "RPC Server" accepts requests to the [server port] and routes the requests b
configuration of the Server and the the first byte in the request. The diagram below shows configuration of the Server and the the first byte in the request. The diagram below shows
all the possible routing flows. all the possible routing flows.
[server port]: https://www.consul.io/docs/agent/options#server_rpc_port [server port]: https://www.consul.io/docs/agent/config/agent-config-files#server_rpc_port
![RPC Routing](./routing.svg) ![RPC Routing](./routing.svg)

10
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 ## 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.initial_management`](/docs/agent/options#acl_tokens_initial_management) management token if the [`acl.tokens.initial_management`](/docs/agent/config/agent-config-files#acl_tokens_initial_management)
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.
@ -143,7 +143,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#primary_datacenter) configuration. [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter) configuration.
- `ReplicationType` - The type of replication that is currently in use. - `ReplicationType` - The type of replication that is currently in use.
@ -295,7 +295,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#acl_enable_token_replication) must be replication](/docs/agent/config/agent-config-files#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.
@ -425,7 +425,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#acl_enable_token_replication) must be replication](/docs/agent/config/agent-config-files#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.
@ -505,7 +505,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#acl_enable_token_replication) must be replication](/docs/agent/config/agent-config-files#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.

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

@ -360,7 +360,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#reloadable-configuration) [Reloadable Configuration](/docs/agent/config#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 |
@ -440,7 +440,7 @@ 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#telemetry-prometheus_retention_time). [`prometheus_retention_time`](/docs/agent/config/agent-config-files#telemetry-prometheus_retention_time).
Since Consul 1.7.2 this endpoint will also automatically switch output format if Since Consul 1.7.2 this endpoint will also automatically switch output format if
the request contains an `Accept` header with a compatible MIME type such as the request contains an `Accept` header with a compatible MIME type such as
@ -745,7 +745,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#acl_enable_token_persistence) only if the [`acl.enable_token_persistence`](/docs/agent/config/agent-config-files#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.
@ -757,9 +757,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#acl_tokens_default), [`agent`](/docs/agent/options#acl_tokens_agent), [`default`](/docs/agent/config/agent-config-files#acl_tokens_default), [`agent`](/docs/agent/config/agent-config-files#acl_tokens_agent),
[`agent_recovery`](/docs/agent/options#acl_tokens_agent_recovery), and [`agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery), and
[`replication`](/docs/agent/options#acl_tokens_replication). [`replication`](/docs/agent/config/agent-config-files#acl_tokens_replication).
-> **Deprecation Note:** The following paths were deprecated in version 1.11 -> **Deprecation Note:** The following paths were deprecated in version 1.11
@ -768,7 +768,7 @@ The paths above correspond to the token names as found in the agent configuratio
| `PUT` | `/agent/token/agent_master` | `application/json` | | `PUT` | `/agent/token/agent_master` | `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:
[`agent_master`](/docs/agent/options#acl_tokens_agent_master). [`agent_master`](/docs/agent/config/agent-config-files#acl_tokens_agent_master).
-> **Deprecation Note:** The following paths were deprecated in version 1.4.3 -> **Deprecation Note:** The following paths were deprecated in version 1.4.3
@ -780,9 +780,9 @@ 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#acl_token_legacy), [`acl_agent_token`](/docs/agent/options#acl_agent_token_legacy), [`acl_token`](/docs/agent/config/agent-config-files#acl_token_legacy), [`acl_agent_token`](/docs/agent/config/agent-config-files#acl_agent_token_legacy),
[`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy), and [`acl_agent_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token_legacy), and
[`acl_replication_token`](/docs/agent/options#acl_replication_token_legacy). [`acl_replication_token`](/docs/agent/config/agent-config-files#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-docs/features/blocking), [blocking queries](/api-docs/features/blocking),

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

@ -10,7 +10,7 @@ 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#enable_central_service_config) [agent configuration](/docs/agent/config/agent-config-files#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) 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.

2
website/content/api-docs/connect/intentions.mdx
View File

@ -96,7 +96,7 @@ The corresponding CLI command is [`consul intention create -replace`](/commands/
evaluation. As with L4 intentions, traffic that fails to match any of the evaluation. As with L4 intentions, traffic that fails to match any of the
provided permissions in this intention will be subject to the default provided permissions in this intention will be subject to the default
intention behavior is defined by the default [ACL intention behavior is defined by the default [ACL
policy](/docs/agent/options#acl_default_policy). policy](/docs/agent/config/agent-config-files#acl_default_policy).
This should be omitted for an L4 intention as it is mutually exclusive with This should be omitted for an L4 intention as it is mutually exclusive with
the `Action` field. the `Action` field.

2
website/content/api-docs/health.mdx
View File

@ -241,7 +241,7 @@ The table below shows this endpoint's support for
ascending order based on the estimated round trip time from that node. Passing ascending order based on the estimated round trip time from that node. Passing
`?near=_agent` will use the agent's node for the sort. This is specified as `?near=_agent` will use the agent's node for the sort. This is specified as
part of the URL as a query parameter. **Note** that using `near` will ignore part of the URL as a query parameter. **Note** that using `near` will ignore
[`use_streaming_backend`](/docs/agent/options#use_streaming_backend) and always [`use_streaming_backend`](/docs/agent/config/agent-config-files#use_streaming_backend) and always
use blocking queries, because the data required to sort the results is not available use blocking queries, because the data required to sort the results is not available
to the streaming backend. to the streaming backend.

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

@ -83,7 +83,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#translate_wan_addrs). In order [`translate_wan_addrs`](/docs/agent/config/agent-config-files#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
@ -94,7 +94,7 @@ will not be present.
All API responses for Consul versions after 1.9 will include an HTTP response All API responses for Consul versions after 1.9 will include an HTTP response
header `X-Consul-Default-ACL-Policy` set to either "allow" or "deny" which header `X-Consul-Default-ACL-Policy` set to either "allow" or "deny" which
mirrors the current value of the agent's mirrors the current value of the agent's
[`acl.default_policy`](/docs/agent/options#acl_default_policy) option. [`acl.default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) option.
This is also the default [intention](/docs/connect/intentions) enforcement This is also the default [intention](/docs/connect/intentions) enforcement
action if no intention matches. action if no intention matches.

2
website/content/api-docs/operator/autopilot.mdx
View File

@ -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#autopilot). [agent configuration section](/docs/agent/config/agent-config-files#autopilot).
## Update Configuration ## Update Configuration

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

@ -12,7 +12,7 @@ Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/token/:type](/api-docs/agent
This command updates the ACL tokens currently in use by the agent. It can be used to introduce This command 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 tokens that were initially loaded from ACL tokens to the agent for the first time, or to update tokens that were initially loaded from
the agent's configuration. Tokens are not persisted unless the agent's configuration. Tokens are not persisted unless
[`acl.enable_token_persistence`](/docs/agent/options#acl_enable_token_persistence) [`acl.enable_token_persistence`](/docs/agent/config/agent-config-files#acl_enable_token_persistence)
is `true`, so tokens will need to be updated again if that option is `false` and is `true`, so tokens will need to be updated again if that option is `false` and
the agent is restarted. the agent is restarted.

2
website/content/commands/config/index.mdx
View File

@ -10,7 +10,7 @@ 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#enable_central_service_config) [agent configuration](/docs/agent/config/agent-config-files#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) 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.

2
website/content/commands/connect/envoy.mdx
View File

@ -42,7 +42,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#addresses) that way. listen](/docs/agent/config/agent-config-files#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

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

@ -78,7 +78,7 @@ information when `debug` is running. By default, it captures all information.
| `members` | 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. | | `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. | | `logs` | `DEBUG` level logs for the target agent, captured for the duration. |
| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU profile is captured for `duration` in a single file, trace is captured for a single `interval`, 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. | | `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/config/agent-config-files#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. |
## Examples ## Examples

2
website/content/commands/index.mdx
View File

@ -235,7 +235,7 @@ 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) and must be [enabled integrating [Envoy proxy](/docs/connect/proxies/envoy) and must be [enabled
explicitly](/docs/agent/options#grpc_port) in agent configuration. explicitly](/docs/agent/config/agent-config-files#grpc_port) in agent configuration.
``` ```
CONSUL_GRPC_ADDR=127.0.0.1:8502 CONSUL_GRPC_ADDR=127.0.0.1:8502

4
website/content/commands/operator/autopilot.mdx
View File

@ -104,10 +104,10 @@ Usage: `consul operator autopilot set-config [options]`
- `-disable-upgrade-migration` <EnterpriseAlert inline /> - Controls whether Consul will avoid promoting - `-disable-upgrade-migration` <EnterpriseAlert inline /> - 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` <EnterpriseAlert inline /> - Controls the [`-node-meta`](/docs/agent/options#_node_meta) - `-redundancy-zone-tag` <EnterpriseAlert inline /> - Controls the [`-node-meta`](/docs/agent/config/agent-config-cli#_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` <EnterpriseAlert inline /> - Controls the [`-node-meta`](/docs/agent/options#_node_meta) - `-upgrade-version-tag` <EnterpriseAlert inline /> - Controls the [`-node-meta`](/docs/agent/config/agent-config-cli#_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.
### Command Output ### Command Output

2
website/content/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#reloadable-configuration) [Reloadable Configuration](/docs/agent/config#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.
The table below shows this command's [required ACLs](/api#authentication). Configuration of The table below shows this command's [required ACLs](/api#authentication). Configuration of

2
website/content/commands/validate.mdx
View File

@ -21,7 +21,7 @@ to be loaded by the agent. This command cannot operate on partial
configuration fragments since those won't pass the full agent validation. configuration fragments since those won't pass the full agent validation.
For more information on the format of Consul's configuration files, read the For more information on the format of Consul's configuration files, read the
consul agent [Configuration Files](/docs/agent/options#configuration-files) consul agent [Configuration Files](/docs/agent/config/agent-config-files)
section. section.
## Usage ## Usage

6
website/content/docs/agent/config-entries.mdx
View File

@ -57,8 +57,8 @@ See [Kubernetes Custom Resource Definitions](/docs/k8s/crds).
Configuration entries outside of Kubernetes should be managed with the Consul Configuration entries outside of Kubernetes should be managed with the Consul
[CLI](/commands/config) or [API](/api-docs/config). Additionally, as a [CLI](/commands/config) or [API](/api-docs/config). Additionally, as a
convenience for initial cluster bootstrapping, configuration entries can be convenience for initial cluster bootstrapping, configuration entries can be
specified in the Consul servers agent's specified in all of the Consul servers's
[configuration files](/docs/agent/options#config_entries_bootstrap) [configuration files](/docs/agent/config/agent-config-files#config_entries_bootstrap)
### Managing Configuration Entries with the CLI ### Managing Configuration Entries with the CLI
@ -162,7 +162,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#config_entries). When a server's configuration file](/docs/agent/config/agent-config-files#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

2
website/content/docs/agent/config/agent-config-files.mdx
View File

@ -905,7 +905,7 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
set [`acl.enable_token_replication`](#acl_enable_token_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 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 [`acl_down_policy`](/docs/agent/config/agent-config-files#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

18
website/content/docs/agent/config/index.mdx
View File

@ -57,22 +57,22 @@ Reloading configuration does not reload all configuration items. The
items which are reloaded include: items which are reloaded include:
- ACL Tokens - ACL Tokens
- [Configuration Entry Bootstrap](#config_entries_bootstrap) - [Configuration Entry Bootstrap](/docs/agent/config/agent-config-files#config_entries_bootstrap)
- Checks - Checks
- [Discard Check Output](#discard_check_output) - [Discard Check Output](/docs/agent/config/agent-config-files#discard_check_output)
- HTTP Client Address - HTTP Client Address
- Log level - Log level
- [Metric Prefix Filter](#telemetry-prefix_filter) - [Metric Prefix Filter](/docs/agent/config/agent-config-files#telemetry-prefix_filter)
- [Node Metadata](#node_meta) - [Node Metadata](/docs/agent/config/agent-config-files#node_meta)
- Some Raft options (since Consul 1.10.0) - Some Raft options (since Consul 1.10.0)
- [`raft_snapshot_threshold`](#_raft_snapshot_threshold) - [`raft_snapshot_threshold`](/docs/agent/config/agent-config-files#_raft_snapshot_threshold)
- [`raft_snapshot_interval`](#_raft_snapshot_interval) - [`raft_snapshot_interval`](/docs/agent/config/agent-config-files#_raft_snapshot_interval)
- [`raft_trailing_logs`](#_raft_trailing_logs) - [`raft_trailing_logs`](/docs/agent/config/agent-config-files#_raft_trailing_logs)
- These can be important in certain outage situations so being able to control - These can be important in certain outage situations so being able to control
them without a restart provides a recovery path that doesn't involve them without a restart provides a recovery path that doesn't involve
downtime. They generally shouldn't be changed otherwise. downtime. They generally shouldn't be changed otherwise.
- [RPC rate limiting](#limits) - [RPC rate limiting](/docs/agent/config/agent-config-files#limits)
- [HTTP Maximum Connections per Client](#http_max_conns_per_client) - [HTTP Maximum Connections per Client](/docs/agent/config/agent-config-files#http_max_conns_per_client)
- Services - Services
- TLS Configuration - TLS Configuration
- Please be aware that this is currently limited to reload a configuration that is already TLS enabled. You cannot enable or disable TLS only with reloading. - Please be aware that this is currently limited to reload a configuration that is already TLS enabled. You cannot enable or disable TLS only with reloading.

32
website/content/docs/agent/index.mdx
View File

@ -102,7 +102,7 @@ The following example starts an agent in dev mode and stores agent state data in
$ consul agent -data-dir=tmp/consul -dev $ consul agent -data-dir=tmp/consul -dev
``` ```
Agents are highly configurable, which enables you to deploy Consul to any infrastructure. Many of the default options for the `agent` command are suitable for becoming familiar with a local instance of Consul. In practice, however, several additional configuration options must be specified for Consul to function as expected. Refer to [Agent Configuration](/docs/agent/options) topic for a complete list of configuration options. Agents are highly configurable, which enables you to deploy Consul to any infrastructure. Many of the default options for the `agent` command are suitable for becoming familiar with a local instance of Consul. In practice, however, several additional configuration options must be specified for Consul to function as expected. Refer to [Agent Configuration](/docs/agent/config) topic for a complete list of configuration options.
### Understanding the Agent Startup Output ### Understanding the Agent Startup Output
@ -127,16 +127,16 @@ $ consul agent -data-dir=/tmp/consul
- **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#_node) flag. [`-node`](/docs/agent/config/agent-config-cli#_node) flag.
- **Datacenter**: This is the datacenter in which the agent is configured to - **Datacenter**: This is the datacenter in which the agent is configured to
run. For single-DC configurations, the agent will default to `dc1`, but you can configure which datacenter the agent reports to with the [`-datacenter`](/docs/agent/options#_datacenter) flag. run. For single-DC configurations, the agent will default to `dc1`, but you can configure which datacenter the agent reports to with the [`-datacenter`](/docs/agent/config/agent-config-cli#_datacenter) flag.
Consul has first-class support for multiple datacenters, but configuring each node to report its datacenter improves agent efficiency. Consul has first-class support for multiple datacenters, but configuring each node to report its datacenter improves agent efficiency.
- **Server**: This indicates whether the agent is running in server or client - **Server**: This indicates whether the agent is running in server or client
mode. mode.
Running an agent in server mode requires additional overhead. This is because they participate in the consensus quorum, store cluster state, and handle queries. A server may also be Running an agent in server mode requires additional overhead. This is because they participate in the consensus quorum, store cluster state, and handle queries. A server may also be
in ["bootstrap"](/docs/agent/options#_bootstrap_expect) mode, which enables the server to elect itself as the Raft leader. Multiple servers cannot be in bootstrap mode because it would put the cluster in an inconsistent state. in ["bootstrap"](/docs/agent/config/agent-config-cli#_bootstrap_expect) mode, which enables the server to elect itselft as the Raft leader. Multiple servers cannot be in bootstrap mode because it 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 This includes the ports for the HTTP and DNS interfaces. By default, this
@ -179,18 +179,18 @@ The following settings are commonly used in the configuration file (also called
| Parameter | Description | Default | | Parameter | Description | Default |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `node_name` | String value that specifies a name for the agent node. <br/>See [`-node-id`](/docs/agent/options#_node_id) for details. | Hostname of the machine | | `node_name` | String value that specifies a name for the agent node. <br/>See [`-node-id`](/docs/agent/config/agent-config-cli#_node_id) for details. | Hostname of the machine |
| `server` | Boolean value that determines if the agent runs in server mode. <br/>See [`-server`](/docs/agent/options#_server) for details. | `false` | | `server` | Boolean value that determines if the agent runs in server mode. <br/>See [`-server`](/docs/agent/config/agent-config-cli#_server) for details. | `false` |
| `datacenter` | String value that specifies which datacenter the agent runs in. <br/>See [-datacenter](/docs/agent/options#_datacenter) for details. | `dc1` | | `datacenter` | String value that specifies which datacenter the agent runs in. <br/>See [-datacenter](/docs/agent/config/agent-config-cli#_datacenter) for details. | `dc1` |
| `data_dir` | String value that specifies a directory for storing agent state data. <br/>See [`-data-dir`](/docs/agent/options#_data_dir) for details. | none | | `data_dir` | String value that specifies a directory for storing agent state data. <br/>See [`-data-dir`](/docs/agent/config/agent-config-cli#_data_dir) for details. | none |
| `log_level` | String value that specifies the level of logging the agent reports. <br/>See [`-log-level`](docs/agent/options#_log_level) for details. | `info` | | `log_level` | String value that specifies the level of logging the agent reports. <br/>See [`-log-level`](/docs/agent/config/agent-config-cli#_log_level) for details. | `info` |
| `retry_join` | Array of string values that specify one or more agent addresses to join after startup. The agent will continue trying to join the specified agents until it has successfully joined another member. <br/>See [`-retry-join`](/docs/agent/options#_retry_join) for details. | none | | `retry_join` | Array of string values that specify one or more agent addresses to join after startup. The agent will continue trying to join the specified agents until it has successfully joined another member. <br/>See [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) for details. | none |
| `addresses` | Block of nested objects that define addresses bound to the agent for internal cluster communication. | `"http": "0.0.0.0"` See the Agent Configuration page for [default address values](/docs/agent/options#addresses) | | `addresses` | Block of nested objects that define addresses bound to the agent for internal cluster communication. | `"http": "0.0.0.0"` See the Agent Configuration page for [default address values](/docs/agent/config/agent-config-files#addresses) |
| `ports` | Block of nested objects that define ports bound to agent addresses. <br/>See (link to addresses option) for details. | See the Agent Configuration page for [default port values](/docs/agent/options#ports) | | `ports` | Block of nested objects that define ports bound to agent addresses. <br/>See (link to addresses option) for details. | See the Agent Configuration page for [default port values](/docs/agent/config/agent-config-files#ports) |
### Server Node in a Service Mesh ### Server Node in a Service Mesh
The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/docs/agent/options#_bootstrap) and the Consul GUI is enabled. The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/docs/agent/config/agent-config-cli#_bootstrap) and the Consul GUI is enabled.
The reason this server agent is configured for a service mesh is that the `connect` configuration is enabled. Connect is Consul's service mesh component that provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh configuration to establish TLS connections for inbound and outbound connections without being aware of Connect at all. See [Connect](/docs/connect) for details. The reason this server agent is configured for a service mesh is that the `connect` configuration is enabled. Connect is Consul's service mesh component that provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh configuration to establish TLS connections for inbound and outbound connections without being aware of Connect at all. See [Connect](/docs/connect) for details.
<CodeTabs> <CodeTabs>
@ -389,7 +389,7 @@ log_level = "INFO"
bind_addr = "0.0.0.0" bind_addr = "0.0.0.0"
# Used for HTTP, HTTPS, DNS, and gRPC addresses. # Used for HTTP, HTTPS, DNS, and gRPC addresses.
# loopback is not included in GetPrivateInterfaces because it is not routable. # loopback is not included in GetPrivateInterfaces because it is not routable.
client_addr = "{{ GetPrivateInterfaces | exclude \"type\" \"ipv6\" | join \"address\" \" \" }} {{ GetAllInterfaces | include \"flags\" \"loopback\" | join \"address\" \" \" }}" client_addr = "{{ GetPrivateInterfaces | exclude \"type\" \"ipv6\" | join \"address\" \" \" }} {{ GetAllInterfaces | include \"flags\" \"loopback\" | join \"address\" \" \" }}"
# advertises gossip and RPC interface to other nodes # advertises gossip and RPC interface to other nodes
@ -448,8 +448,8 @@ may not be important for your use case. For example, for a web server and load
balancer setup, both result in the same outcome: the web node is removed balancer setup, both result in the same outcome: the web node is removed
from the load balancer pool. from the load balancer pool.
The [`skip_leave_on_interrupt`](/docs/agent/options#skip_leave_on_interrupt) and The [`skip_leave_on_interrupt`](/docs/agent/config/agent-config-files#skip_leave_on_interrupt) and
[`leave_on_terminate`](/docs/agent/options#leave_on_terminate) configuration [`leave_on_terminate`](/docs/agent/config/agent-config-files#leave_on_terminate) configuration
options allow you to adjust this behavior. options allow you to adjust this behavior.
<!-- list of reference-style links --> <!-- list of reference-style links -->

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

@ -29,7 +29,7 @@ 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 tutorial](https://learn.hashicorp.com/tutorials/consul/monitor-datacenter-health?utm_source=consul.io&utm_medium=docs) to learn how collect and interpret Consul data. Metrics tutorial](https://learn.hashicorp.com/tutorials/consul/monitor-datacenter-health?utm_source=consul.io&utm_medium=docs) to learn how collect and interpret Consul data.
Additionally, if the [`telemetry` configuration options](/docs/agent/options#telemetry) Additionally, if the [`telemetry` configuration options](/docs/agent/config/agent-config-files#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.
@ -140,7 +140,7 @@ you will need to apply a function such as InfluxDB's [`non_negative_difference()
| Metric Name | Description | Unit | Type | | Metric Name | Description | Unit | Type |
| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------ | | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------ |
| `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server | requests | counter | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server | requests | counter |
| `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. | requests | counter | | `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/config/agent-config-files#limits) configuration. | requests | counter |
| `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter |
**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.
@ -172,7 +172,7 @@ Under these conditions, a follower after a restart may be unable to catch up on
replication and become a voter again since it takes longer to restore from disk replication and become a voter again since it takes longer to restore from disk
or the leader than the leader takes to write a new snapshot and truncate its or the leader than the leader takes to write a new snapshot and truncate its
logs. Servers retain logs. Servers retain
[`raft_trailing_logs`](/docs/agent/options#_raft_trailing_logs) (default [`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) (default
`10240`) log entries even if their snapshot was more recent. On a leader `10240`) log entries even if their snapshot was more recent. On a leader
processing 500 commits/second, that is only about 20 seconds worth of logs. processing 500 commits/second, that is only about 20 seconds worth of logs.
Assuming the leader is able to write out a snapshot and truncate the logs in Assuming the leader is able to write out a snapshot and truncate the logs in
@ -197,7 +197,7 @@ repeatedly as well as reduce the fault tolerance and serving capacity of the
cluster. cluster.
Since Consul 1.5.3 Since Consul 1.5.3
[`raft_trailing_logs`](/docs/agent/options#_raft_trailing_logs) has been [`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) has been
configurable. Increasing it allows the leader to retain more logs and give configurable. Increasing it allows the leader to retain more logs and give
followers more time to restore and catch up. The tradeoff is potentially followers more time to restore and catch up. The tradeoff is potentially
slower appends which eventually might affect write throughput and latency slower appends which eventually might affect write throughput and latency
@ -208,7 +208,7 @@ mean loosing cluster availability and needing to recover the cluster from a loss
of quorum. of quorum.
Since Consul 1.10.0 Since Consul 1.10.0
[`raft_trailing_logs`](/docs/agent/options#_raft_trailing_logs) is now [`raft_trailing_logs`](/docs/agent/config/agent-config-files#raft_trailing_logs) is now
reloadable with `consul reload` or `SIGHUP` allowing operators to increase this reloadable with `consul reload` or `SIGHUP` allowing operators to increase this
without the leader restarting or loosing leadership allowing the cluster to be without the leader restarting or loosing leadership allowing the cluster to be
recovered gracefully. recovered gracefully.
@ -298,7 +298,7 @@ it took as well as how many logs were contained in the batch. Writing logs in th
a subsequent log storage operation can only be started after the previous one completed. The maximum number a subsequent log storage operation can only be started after the previous one completed. The maximum number
of log storage operations that can be performed each second is represented with the `consul.raft.boltdb.writeCapacity` of log storage operations that can be performed each second is represented with the `consul.raft.boltdb.writeCapacity`
metric. When log storage operations are becoming slower you may not see an immediate decrease in write capacity metric. When log storage operations are becoming slower you may not see an immediate decrease in write capacity
due to increased batch sizes of the each operation. However, the max batch size allowed is 64 logs. Therefore if due to increased batch sizes of the each operation. However, the max batch size allowed is 64 logs. Therefore if
the `logsPerBatch` metric is near 64 and the `storeLogs` metric is seeing increased time to write each batch to disk, the `logsPerBatch` metric is near 64 and the `storeLogs` metric is seeing increased time to write each batch to disk,
then it is likely that increased write latencies and other errors may occur. then it is likely that increased write latencies and other errors may occur.
@ -332,7 +332,7 @@ This is a full list of metrics emitted by Consul.
| `consul.acl.blocked.{check,node,service}.registration` | Increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL. | requests | counter | | `consul.acl.blocked.{check,node,service}.registration` | Increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL. | requests | counter |
| `consul.api.http` | Migrated from consul.http.. this samples how long it takes to service the given HTTP request for the given verb and path. Includes labels for `path` and `method`. `path` does not include details like service or key names, for these an underscore will be present as a placeholder (eg. path=`v1.kv._`) | ms | timer | | `consul.api.http` | Migrated from consul.http.. this samples how long it takes to service the given HTTP request for the given verb and path. Includes labels for `path` and `method`. `path` does not include details like service or key names, for these an underscore will be present as a placeholder (eg. path=`v1.kv._`) | ms | timer |
| `consul.client.rpc` | 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` | 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` | 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.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/config/agent-config-files#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` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | | `consul.client.rpc.failed` | 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.` | Increments whenever a Consul agent receives a catalog register request. | requests | counter | | `consul.client.api.catalog_register.` | Increments whenever a Consul agent receives a catalog register request. | requests | counter |
| `consul.client.api.success.catalog_register.` | Increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter | | `consul.client.api.success.catalog_register.` | Increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter |
@ -431,7 +431,7 @@ These metrics are used to monitor the health of the Consul servers.
| `consul.raft.last_index` | Represents the raft applied index. | index | gauge | | `consul.raft.last_index` | Represents the raft applied index. | index | gauge |
| `consul.raft.leader.dispatchLog` | Measures the time it takes for the leader to write log entries to disk. | ms | timer | | `consul.raft.leader.dispatchLog` | Measures the time it takes for the leader to write log entries to disk. | ms | timer |
| `consul.raft.leader.dispatchNumLogs` | Measures the number of logs committed to disk in a batch. | logs | gauge | | `consul.raft.leader.dispatchNumLogs` | Measures the number of logs committed to disk in a batch. | logs | gauge |
| `consul.raft.leader.lastContact` | 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.raft.leader.lastContact` | 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/config/agent-config-files#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.raft.leader.oldestLogAge` | The number of milliseconds since the _oldest_ log in the leader's log store was written. This can be important for replication health where write rate is high and the snapshot is large as followers may be unable to recover from a restart if restoring takes longer than the minimum value for the current leader. Compare this with `consul.raft.fsm.lastRestoreDuration` and `consul.raft.rpc.installSnapshot` to monitor. In normal usage this gauge value will grow linearly over time until a snapshot completes on the leader and the log is truncated. Note: this metric won't be emitted until the leader writes a snapshot. After an upgrade to Consul 1.10.0 it won't be emitted until the oldest log was written after the upgrade. | ms | gauge | | `consul.raft.leader.oldestLogAge` | The number of milliseconds since the _oldest_ log in the leader's log store was written. This can be important for replication health where write rate is high and the snapshot is large as followers may be unable to recover from a restart if restoring takes longer than the minimum value for the current leader. Compare this with `consul.raft.fsm.lastRestoreDuration` and `consul.raft.rpc.installSnapshot` to monitor. In normal usage this gauge value will grow linearly over time until a snapshot completes on the leader and the log is truncated. Note: this metric won't be emitted until the leader writes a snapshot. After an upgrade to Consul 1.10.0 it won't be emitted until the oldest log was written after the upgrade. | ms | gauge |
| `consul.raft.replication.heartbeat` | Measures the time taken to invoke appendEntries on a peer, so that it doesn’t timeout on a periodic basis. | ms | timer | | `consul.raft.replication.heartbeat` | Measures the time taken to invoke appendEntries on a peer, so that it doesn’t timeout on a periodic basis. | ms | timer |
| `consul.raft.replication.appendEntries` | Measures the time it takes to replicate log entries to followers. This is a general indicator of the load pressure on the Consul servers, as well as the performance of the communication between the servers. | ms | timer | | `consul.raft.replication.appendEntries` | Measures the time it takes to replicate log entries to followers. This is a general indicator of the load pressure on the Consul servers, as well as the performance of the communication between the servers. | ms | timer |
@ -575,7 +575,7 @@ These metrics give insight into the health of the cluster as a whole.
| `consul.memberlist.degraded.timeout` | 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` | 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` | Counts the number of times an agent has marked another agent to be a dead node. | messages / interval | counter | | `consul.memberlist.msg.dead` | Counts the number of times an agent has marked another agent to be a dead node. | messages / interval | counter |
| `consul.memberlist.health.score` | 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` | 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` | 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.msg.suspect` | 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/config/agent-config-files#ports). | suspect messages received / interval | counter |
| `consul.memberlist.tcp.accept` | Counts the number of times an agent has accepted an incoming TCP stream connection. | connections accepted / interval | counter | | `consul.memberlist.tcp.accept` | Counts the number of times an agent has accepted an incoming TCP stream connection. | connections accepted / interval | counter |
| `consul.memberlist.udp.sent/received` | 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` | 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` | 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` | Counts the number of times an agent has initiated a push/pull sync with an other agent. | push/pull initiated / interval | counter |
@ -586,14 +586,14 @@ These metrics give insight into the health of the cluster as a whole.
| `consul.memberlist.msg_suspect` | The number of suspect messages that the agent has processed so far, based on the message information given by the network layer. | messages / Interval | counter | | `consul.memberlist.msg_suspect` | The number of suspect messages that the agent has processed so far, based on the message information given by the network layer. | messages / Interval | counter |
| `consul.memberlist.probeNode` | Measures the time taken to perform a single round of failure detection on a select agent. | nodes / Interval | counter | | `consul.memberlist.probeNode` | Measures the time taken to perform a single round of failure detection on a select agent. | nodes / Interval | counter |
| `consul.memberlist.pushPullNode` | Measures the number of agents that have exchanged state with this agent. | nodes / Interval | counter | | `consul.memberlist.pushPullNode` | Measures the number of agents that have exchanged state with this agent. | nodes / Interval | counter |
| `consul.serf.member.failed` | 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.failed` | 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/config/agent-config-files#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#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/config/agent-config-files#ports). | flaps / interval | counter |
| `consul.serf.member.join` | 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` | 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` | Increments when an agent leaves the cluster. | leaves / interval | counter | | `consul.serf.member.left` | Increments when an agent leaves the cluster. | leaves / interval | counter |
| `consul.serf.events` | Increments when an agent processes an [event](/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.serf.events` | Increments when an agent processes an [event](/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.serf.msgs.sent` | This metric is sample of the number of bytes of messages broadcast to the cluster. In a given time interval, the sum of this metric is the total number of bytes sent and the count is the number of messages sent. | message bytes / interval | counter | | `consul.serf.msgs.sent` | This metric is sample of the number of bytes of messages broadcast to the cluster. In a given time interval, the sum of this metric is the total number of bytes sent and the count is the number of messages sent. | message bytes / interval | counter |
| `consul.autopilot.failure_tolerance` | Tracks the number of voting servers that the cluster can lose while continuing to function. | servers   | gauge | | `consul.autopilot.failure_tolerance` | Tracks the number of voting servers that the cluster can lose while continuing to function. | servers | gauge |
| `consul.autopilot.healthy` | 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` | 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` | Tracks the active number of sessions being tracked. | sessions | gauge | | `consul.session_ttl.active` | Tracks the active number of sessions being tracked. | sessions | gauge |
| `consul.catalog.service.query.` | Increments for each catalog query for the given service. | queries | counter | | `consul.catalog.service.query.` | Increments for each catalog query for the given service. | queries | counter |
| `consul.catalog.service.query-tag..` | Increments for each catalog query for the given service with the given tag. | queries | counter | | `consul.catalog.service.query-tag..` | Increments for each catalog query for the given service with the given tag. | queries | counter |

6
website/content/docs/connect/ca/aws.mdx
View File

@ -173,11 +173,11 @@ So monthly cost would be calculated as:
- 500 ⨉ 13.3 = 6,650 certificates issued in dc3 - 500 ⨉ 13.3 = 6,650 certificates issued in dc3
The number of certificates issued could be reduced by increasing The number of certificates issued could be reduced by increasing
[`leaf_cert_ttl`](/docs/agent/options#ca_leaf_cert_ttl) in the CA Provider [`leaf_cert_ttl`](/docs/agent/config/agent-config-files#ca_leaf_cert_ttl) in the CA Provider
configuration if the longer lived credentials are an acceptable risk tradeoff configuration if the longer lived credentials are an acceptable risk tradeoff
against the cost. against the cost.
<!-- Reference style links --> <!-- Reference style links -->
[`ca_config`]: /docs/agent/options#connect_ca_config [`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config
[`ca_provider`]: /docs/agent/options#connect_ca_provider [`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider
[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration [`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration

2
website/content/docs/connect/ca/consul.mdx
View File

@ -92,7 +92,7 @@ Connect is enabled - the PrivateKey and RootCert fields have not been set, so th
been generated (as seen above in the roots list). been generated (as seen above in the roots list).
There are two ways to have the Consul CA use a custom private key and root certificate: There are two ways to have the Consul CA use a custom private key and root certificate:
either through the `ca_config` section of the [Agent configuration](/docs/agent/options#connect_ca_config) (which can only be used during the cluster's either through the `ca_config` section of the [Agent configuration](/docs/agent/config/agent-config-files#connect_ca_config) (which can only be used during the cluster's
initial bootstrap) or through the [Update CA Configuration endpoint](/api-docs/connect/ca#update-ca-configuration). initial bootstrap) or through the [Update CA Configuration endpoint](/api-docs/connect/ca#update-ca-configuration).
Currently Consul requires that root certificates are valid [SPIFFE SVID Signing certificates](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded Currently Consul requires that root certificates are valid [SPIFFE SVID Signing certificates](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded

2
website/content/docs/connect/ca/index.mdx
View File

@ -47,7 +47,7 @@ will generate the initial root certificates and setup the internal Consul server
state. state.
For the initial bootstrap, the CA provider can be configured through the For the initial bootstrap, the CA provider can be configured through the
[Agent configuration](/docs/agent/options#connect_ca_config). After [Agent configuration](/docs/agent/config/agent-config-files#connect_ca_config). After
initialization, the CA can only be updated through the initialization, the CA can only be updated through the
[Update CA Configuration API endpoint](/api-docs/connect/ca#update-ca-configuration). [Update CA Configuration API endpoint](/api-docs/connect/ca#update-ca-configuration).
If a CA is already initialized, any changes to the CA configuration in the If a CA is already initialized, any changes to the CA configuration in the

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

@ -280,6 +280,6 @@ path "/connect_inter/*" {
</CodeBlockConfig> </CodeBlockConfig>
<!-- Reference style links --> <!-- Reference style links -->
[`ca_config`]: /docs/agent/options#connect_ca_config [`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config
[`ca_provider`]: /docs/agent/options#connect_ca_provider [`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider
[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration [`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration

2
website/content/docs/connect/config-entries/exported-services.mdx
View File

@ -28,7 +28,7 @@ You can configure the settings defined in the `exported-services` configuration
## Usage ## Usage
1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). 1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements).
1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/docs/agent/options#config_entries)) as described in [Configuration](#configuration). 1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/docs/agent/config/agent-config-files#config_entries)) as described in [Configuration](#configuration).
1. Apply the configuration using one of the following methods: 1. Apply the configuration using one of the following methods:
- Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. - Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details.
- Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. - Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details.

2
website/content/docs/connect/config-entries/index.mdx
View File

@ -49,7 +49,7 @@ See [Agent - Config Entries](/docs/agent/config-entries).
## Using Configuration Entries For Service Defaults ## Using Configuration Entries For Service Defaults
Outside of Kubernetes, when the agent is Outside of Kubernetes, when the agent is
[configured](/docs/agent/options#enable_central_service_config) to enable [configured](/docs/agent/config/agent-config-files#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

4
website/content/docs/connect/config-entries/proxy-defaults.mdx
View File

@ -390,8 +390,8 @@ spec:
type: 'bool: false', type: 'bool: false',
description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. description: `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#advertise). The port for these listeners are dynamically allocated from [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from
[expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port). [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#expose_max_port).
This flag is useful when a Consul client cannot reach registered services over localhost.`, This flag is useful when a Consul client cannot reach registered services over localhost.`,
}, },
{ {

4
website/content/docs/connect/config-entries/service-defaults.mdx
View File

@ -662,8 +662,8 @@ spec:
type: 'bool: false', type: 'bool: false',
description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. description: `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#advertise). The port for these listeners are dynamically allocated from [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from
[expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port). [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#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.`,
}, },

4
website/content/docs/connect/config-entries/service-intentions.mdx
View File

@ -488,7 +488,7 @@ spec:
first permission to match in the list is terminal and stops further first permission to match in the list is terminal and stops further
evaluation. As with L4 intentions, traffic that fails to match any of the evaluation. As with L4 intentions, traffic that fails to match any of the
provided permissions in this intention will be subject to the default provided permissions in this intention will be subject to the default
intention behavior is defined by the default [ACL policy](/docs/agent/options#acl_default_policy).<br><br> intention behavior is defined by the default [ACL policy](/docs/agent/config/agent-config-files#acl_default_policy).<br><br>
This should be omitted for an L4 intention as it is mutually exclusive with This should be omitted for an L4 intention as it is mutually exclusive with
the \`Action\` field.<br><br> the \`Action\` field.<br><br>
Setting \`Permissions\` is not valid if a wildcard is used for the \`Name\` or \`Namespace\` because they can only be Setting \`Permissions\` is not valid if a wildcard is used for the \`Name\` or \`Namespace\` because they can only be
@ -498,7 +498,7 @@ spec:
first permission to match in the list is terminal and stops further first permission to match in the list is terminal and stops further
evaluation. As with L4 intentions, traffic that fails to match any of the evaluation. As with L4 intentions, traffic that fails to match any of the
provided permissions in this intention will be subject to the default provided permissions in this intention will be subject to the default
intention behavior is defined by the default [ACL policy](/docs/agent/options#acl_default_policy).<br><br> intention behavior is defined by the default [ACL policy](/docs/agent/config/agent-config-files#acl_default_policy).<br><br>
This should be omitted for an L4 intention as it is mutually exclusive with This should be omitted for an L4 intention as it is mutually exclusive with
the \`action\` field.<br><br> the \`action\` field.<br><br>
Setting \`permissions\` is not valid if a wildcard is used for the \`spec.destination.name\` or \`spec.destination.namespace\` Setting \`permissions\` is not valid if a wildcard is used for the \`spec.destination.name\` or \`spec.destination.namespace\`

14
website/content/docs/connect/configuration.mdx
View File

@ -22,7 +22,7 @@ The first step to use Connect is to enable Connect for your Consul
cluster. By default, Connect is disabled. Enabling Connect requires changing cluster. By default, Connect is disabled. Enabling Connect requires changing
the configuration of only your Consul _servers_ (not client agents). To enable the configuration of only your Consul _servers_ (not client agents). To enable
Connect, add the following to a new or existing Connect, add the following to a new or existing
[server configuration file](/docs/agent/options). In an existing cluster, this configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability. In HCL: [server configuration file](/docs/agent/config/agent-config-files). In an existing cluster, this configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability. In HCL:
```hcl ```hcl
connect { connect {
@ -43,20 +43,20 @@ connection attempts to fail until Connect is enabled on the server agents.
Other optional Connect configurations that you can set in the server Other optional Connect configurations that you can set in the server
configuration file include: configuration file include:
- [certificate authority settings](/docs/agent/options#connect) - [certificate authority settings](/docs/agent/config/agent-config-files#connect)
- [token replication](/docs/agent/options#acl_tokens_replication) - [token replication](/docs/agent/config/agent-config-files#acl_tokens_replication)
- [dev mode](/docs/agent/options#_dev) - [dev mode](/docs/agent/config/agent-config-cli#_dev)
- [server host name verification](/docs/agent/options#tls_internal_rpc_verify_server_hostname) - [server host name verification](/docs/agent/config/agent-config-files#tls_internal_rpc_verify_server_hostname)
If you would like to use Envoy as your Connect proxy you will need to [enable If you would like to use Envoy as your Connect proxy you will need to [enable
gRPC](/docs/agent/options#grpc_port). gRPC](/docs/agent/config/agent-config-files#grpc_port).
Additionally if you plan on using the observability features of Connect, it can Additionally if you plan on using the observability features of Connect, it can
be convenient to configure your proxies and services using [configuration be convenient to configure your proxies and services using [configuration
entries](/docs/agent/config-entries) which you can interact with using the entries](/docs/agent/config-entries) which you can interact with using the
CLI or API, or by creating configuration entry files. You will want to enable CLI or API, or by creating configuration entry files. You will want to enable
[centralized service [centralized service
configuration](/docs/agent/options#enable_central_service_config) on configuration](/docs/agent/config/agent-config-files#enable_central_service_config) on
clients, which allows each service's proxy configuration to be managed centrally clients, which allows each service's proxy configuration to be managed centrally
via API. via API.

4
website/content/docs/connect/connect-internals.mdx
View File

@ -109,10 +109,10 @@ externally routable IPs at the service level.
## Intention Replication ## Intention Replication
Intention replication happens automatically but requires the Intention replication happens automatically but requires the
[`primary_datacenter`](/docs/agent/options#primary_datacenter) [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter)
configuration to be set to specify a datacenter that is authoritative configuration to be set to specify a datacenter that is authoritative
for intentions. In production setups with ACLs enabled, the for intentions. In production setups with ACLs enabled, the
[replication token](/docs/agent/options#acl_tokens_replication) must also [replication token](/docs/agent/config/agent-config-files#acl_tokens_replication) must also
be set in the secondary datacenter server's configuration. be set in the secondary datacenter server's configuration.
## Certificate Authority Federation ## Certificate Authority Federation

4
website/content/docs/connect/gateways/ingress-gateway.mdx
View File

@ -40,8 +40,8 @@ the [hosts](/docs/connect/config-entries/ingress-gateway#hosts) field.
Ingress gateways also require that your Consul datacenters are configured correctly: Ingress gateways also require that your Consul datacenters are configured correctly:
- You'll need to use Consul version 1.8.0 or newer. - You'll need to use Consul version 1.8.0 or newer.
- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers. - Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled on the datacenter's Consul servers.
- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents. - [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled on all client agents.
Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul. Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul.

26
website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters.mdx
View File

@ -10,13 +10,13 @@ description: >-
-> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer. -> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer.
Mesh gateways enable service mesh traffic to be routed between different Consul datacenters. Mesh gateways enable service mesh traffic to be routed between different Consul datacenters.
Datacenters can reside in different clouds or runtime environments where general interconnectivity between all services Datacenters can reside in different clouds or runtime environments where general interconnectivity between all services
in all datacenters isn't feasible. in all datacenters isn't feasible.
Mesh gateways operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested. The gateway does not decrypt the data within the mTLS session. Mesh gateways operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested. The gateway does not decrypt the data within the mTLS session.
The following diagram describes the architecture for using mesh gateways for cross-datacenter communication:<a name="mesh-architecture-diagram"/> The following diagram describes the architecture for using mesh gateways for cross-datacenter communication:<a name="mesh-architecture-diagram"/>
![Mesh Gateway Architecture](/img/mesh-gateways.png) ![Mesh Gateway Architecture](/img/mesh-gateways.png)
@ -30,12 +30,12 @@ Ensure that your Consul environment meets the following requirements.
* Consul version 1.6.0 or newer. * Consul version 1.6.0 or newer.
* A local Consul agent is required to manage its configuration. * A local Consul agent is required to manage its configuration.
* Consul [Connect](/docs/agent/options#connect) must be enabled in both datacenters. * Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled in both datacenters.
* Each [datacenter](/docs/agent/options#datacenter) must have a unique name. * Each [datacenter](/docs/agent/config/agent-config-files#datacenter) must have a unique name.
* Each datacenters must be [WAN joined](https://learn.hashicorp.com/tutorials/consul/federarion-gossip-wan). * Each datacenters must be [WAN joined](https://learn.hashicorp.com/tutorials/consul/federarion-gossip-wan).
* The [primary datacenter](/docs/agent/options#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other. * The [primary datacenter](/docs/agent/config/agent-config-files#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other.
* [gRPC](/docs/agent/options#grpc_port) must be enabled. * [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled.
* If you want to [enable gateways globally](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/options#enable_central_service_config). * If you want to [enable gateways globally](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/agent-config-files#enable_central_service_config).
### Network ### Network
@ -58,23 +58,23 @@ Sidecar proxies that do not send upstream traffic through a gateway are not affe
Configure the following settings to register the mesh gateway as a service in Consul. Configure the following settings to register the mesh gateway as a service in Consul.
* Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. * Specify `mesh-gateway` in the `kind` field to register the gateway with Consul.
* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. * Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace.
* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. * Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information.
* If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications. * If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications.
### Modes ### Modes
Each upstream associated with a service mesh proxy can be configured so that it is routed through a mesh gateway. Each upstream associated with a service mesh proxy can be configured so that it is routed through a mesh gateway.
Depending on your network, the proxy's connection to the gateway can operate in one of the following modes (refer to the [mesh-architecture-diagram](#mesh-architecture-diagram)): Depending on your network, the proxy's connection to the gateway can operate in one of the following modes (refer to the [mesh-architecture-diagram](#mesh-architecture-diagram)):
* `none` - (Default) No gateway is used and a service mesh connect proxy makes its outbound connections directly * `none` - (Default) No gateway is used and a service mesh connect proxy makes its outbound connections directly
to the destination services. to the destination services.
* `local` - The service mesh connect proxy makes an outbound connection to a gateway running in the * `local` - The service mesh connect proxy makes an outbound connection to a gateway running in the
same datacenter. That gateway is responsible for ensuring that the data is forwarded to gateways in the destination datacenter. same datacenter. That gateway is responsible for ensuring that the data is forwarded to gateways in the destination datacenter.
Refer to the flow labeled `local` in the [mesh-architecture-diagram](#mesh-architecture-diagram). Refer to the flow labeled `local` in the [mesh-architecture-diagram](#mesh-architecture-diagram).
* `remote` - The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter. * `remote` - The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter.
The gateway forwards the data to the final destination service. The gateway forwards the data to the final destination service.
Refer to the flow labeled `remote` in the [mesh-architecture-diagram](#mesh-architecture-diagram). Refer to the flow labeled `remote` in the [mesh-architecture-diagram](#mesh-architecture-diagram).

20
website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx
View File

@ -12,7 +12,7 @@ description: >-
Mesh gateways enable you to route service mesh traffic between different Consul [admin partitions](/docs/enterprise/admin-partitions). Mesh gateways enable you to route service mesh traffic between different Consul [admin partitions](/docs/enterprise/admin-partitions).
Partitions can reside in different clouds or runtime environments where general interconnectivity between all services Partitions can reside in different clouds or runtime environments where general interconnectivity between all services
in all partitions isn't feasible. in all partitions isn't feasible.
Mesh gateways operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested. The gateway does not decrypt the data within the mTLS session. Mesh gateways operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested. The gateway does not decrypt the data within the mTLS session.
@ -24,15 +24,15 @@ Ensure that your Consul environment meets the following requirements.
* Consul Enterprise version 1.11.0 or newer. * Consul Enterprise version 1.11.0 or newer.
* A local Consul agent is required to manage its configuration. * A local Consul agent is required to manage its configuration.
* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/options#connect) for details. * Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/config/agent-config-files#connect) for details.
* Each partition must have a unique name. Refer to the [admin partitions documentation](/docs/enterprise/admin-partitions) for details. * Each partition must have a unique name. Refer to the [admin partitions documentation](/docs/enterprise/admin-partitions) for details.
* If you want to [enable gateways globally](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/options#enable_central_service_config). * If you want to [enable gateways globally](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/agent-config-files#enable_central_service_config).
### Proxy ### Proxy
Envoy is the only proxy with mesh gateway capabilities in Consul. Envoy is the only proxy with mesh gateway capabilities in Consul.
Mesh gateway proxies receive their configuration through Consul, which automatically generates it based on the proxy's registration. Mesh gateway proxies receive their configuration through Consul, which automatically generates it based on the proxy's registration.
Consul can only translate mesh gateway registration information into Envoy configuration. Consul can only translate mesh gateway registration information into Envoy configuration.
Sidecar proxies that send traffic to an upstream service through a gateway need to know the location of that gateway. They discover the gateway based on their sidecar proxy registrations. Consul can only translate the gateway registration information into Envoy configuration. Sidecar proxies that send traffic to an upstream service through a gateway need to know the location of that gateway. They discover the gateway based on their sidecar proxy registrations. Consul can only translate the gateway registration information into Envoy configuration.
@ -44,22 +44,22 @@ Sidecar proxies that do not send upstream traffic through a gateway are not affe
Configure the following settings to register the mesh gateway as a service in Consul. Configure the following settings to register the mesh gateway as a service in Consul.
* Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. * Specify `mesh-gateway` in the `kind` field to register the gateway with Consul.
* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and partition. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_partition` must be configured to enable cross-partition traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. * Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and partition. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_partition` must be configured to enable cross-partition traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace.
* Configure the `exported-services` configuration entry to enable Consul to export services contained in an admin partition to one or more additional partitions. Refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services) for details. * Configure the `exported-services` configuration entry to enable Consul to export services contained in an admin partition to one or more additional partitions. Refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services) for details.
* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy, i.e., Envoy. For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. * Define the `Proxy.Config` settings using opaque parameters compatible with your proxy, i.e., Envoy. For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information.
* If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications. * If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications.
### Modes ### Modes
Each upstream associated with a service mesh proxy can be configured so that it is routed through a mesh gateway. Each upstream associated with a service mesh proxy can be configured so that it is routed through a mesh gateway.
Depending on your network, the proxy's connection to the gateway can operate in one of the following modes: Depending on your network, the proxy's connection to the gateway can operate in one of the following modes:
* `none` - (Default) No gateway is used and a service mesh connect proxy makes its outbound connections directly * `none` - (Default) No gateway is used and a service mesh connect proxy makes its outbound connections directly
to the destination services. to the destination services.
* `local` - The service mesh connect proxy makes an outbound connection to a gateway running in the same datacenter. The gateway at the outbound connection is responsible for ensuring that the data is forwarded to gateways in the destination partition. * `local` - The service mesh connect proxy makes an outbound connection to a gateway running in the same datacenter. The gateway at the outbound connection is responsible for ensuring that the data is forwarded to gateways in the destination partition.
* `remote` - The service mesh connect proxy makes an outbound connection to a gateway running in the destination datacenter. * `remote` - The service mesh connect proxy makes an outbound connection to a gateway running in the destination datacenter.
The gateway forwards the data to the final destination service. The gateway forwards the data to the final destination service.
### Connect Proxy Configuration ### Connect Proxy Configuration

5
website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx
View File

@ -126,7 +126,10 @@ connect {
} }
``` ```
The [`start_join_wan`](/docs/agent/options#start_join_wan) or [`retry_join_wan`](/docs/agent/options#retry_join_wan) are only used for the [traditional federation process](/docs/k8s/installation/multi-cluster#traditional-wan-federation). They must be omitted when federating Consul servers via gateways. The [`start_join_wan`](/docs/agent/config/agent-config-files#start_join_wan) or
[`retry_join_wan`](/docs/agent/config/agent-config-files#retry_join_wan) are
only used for the [traditional federation process](/docs/k8s/installation/multi-cluster#traditional-wan-federation).
They must be omitted when federating Consul servers via gateways.
-> The `primary_gateways` configuration can also use `go-discover` syntax just -> The `primary_gateways` configuration can also use `go-discover` syntax just
like `retry_join_wan`. like `retry_join_wan`.

4
website/content/docs/connect/gateways/terminating-gateway.mdx
View File

@ -59,8 +59,8 @@ Each terminating gateway needs:
Terminating gateways also require that your Consul datacenters are configured correctly: Terminating gateways also require that your Consul datacenters are configured correctly:
- You'll need to use Consul version 1.8.0 or newer. - You'll need to use Consul version 1.8.0 or newer.
- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers. - Consul [Connect](/docs/agent/config/agent-config-files#connect) must be enabled on the datacenter's Consul servers.
- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents. - [gRPC](/docs/agent/config/agent-config-files#grpc_port) must be enabled on all client agents.
Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with terminating gateway capabilities in Consul. Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with terminating gateway capabilities in Consul.

2
website/content/docs/connect/intentions-legacy.mdx
View File

@ -25,7 +25,7 @@ is allowed by testing the intentions. If authorize returns false the
connection must be terminated. connection must be terminated.
The default intention behavior is defined by the default [ACL The default intention behavior is defined by the default [ACL
policy](/docs/agent/options#acl_default_policy). If the default ACL policy is policy](/docs/agent/config/agent-config-files#acl_default_policy). If the default ACL policy is
"allow all", then all Connect connections are allowed by default. If the "allow all", then all Connect connections are allowed by default. If the
default ACL policy is "deny all", then all Connect connections are denied by default ACL policy is "deny all", then all Connect connections are denied by
default. default.

2
website/content/docs/connect/intentions.mdx
View File

@ -49,7 +49,7 @@ target destination. After verifying the TLS client certificate, the cached
intentions should be consulted for each incoming connection/request to intentions should be consulted for each incoming connection/request to
determine if it should be accepted or rejected. determine if it should be accepted or rejected.
The default intention behavior is defined by the [`default_policy`](/docs/agent/options#acl_default_policy) configuration. The default intention behavior is defined by the [`default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) configuration.
If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default.
If is set to `deny`, then all connections or requests will be denied by default. If is set to `deny`, then all connections or requests will be denied by default.

6
website/content/docs/connect/observability/index.mdx
View File

@ -18,10 +18,10 @@ to:
- Define the upstreams for each of your services. - Define the upstreams for each of your services.
If you are using Envoy as your sidecar proxy, you will need to [enable If you are using Envoy as your sidecar proxy, you will need to [enable
gRPC](/docs/agent/options#grpc_port) on your client agents. To define the gRPC](/docs/agent/config/agent-config-files#grpc_port) on your client agents. To define the
metrics destination and service protocol you may want to enable [configuration metrics destination and service protocol you may want to enable [configuration
entries](/docs/agent/options#config_entries) and [centralized service entries](/docs/agent/config/agent-config-files#config_entries) and [centralized service
configuration](/docs/agent/options#enable_central_service_config). configuration](/docs/agent/config/agent-config-files#enable_central_service_config).
### Kubernetes ### Kubernetes
If you are using Kubernetes, the Helm chart can simplify much of the configuration needed to enable observability. See If you are using Kubernetes, the Helm chart can simplify much of the configuration needed to enable observability. See

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

@ -47,11 +47,11 @@ UI. If there are multiple clients with the UI enabled in a datacenter for
redundancy these configurations must be added to all of them. redundancy these configurations must be added to all of them.
We assume that the UI is already enabled by setting We assume that the UI is already enabled by setting
[`ui_config.enabled`](/docs/agent/options#ui_config_enabled) to `true` in the [`ui_config.enabled`](/docs/agent/config/agent-config-files#ui_config_enabled) to `true` in the
agent's configuration file. agent's configuration file.
To use the built-in Prometheus provider To use the built-in Prometheus provider
[`ui_config.metrics_provider`](/docs/agent/options#ui_config_metrics_provider) [`ui_config.metrics_provider`](/docs/agent/config/agent-config-files#ui_config_metrics_provider)
must be set to `prometheus`. must be set to `prometheus`.
The UI must query the metrics provider through a proxy endpoint. This simplifies The UI must query the metrics provider through a proxy endpoint. This simplifies
@ -59,7 +59,7 @@ deployment where Prometheus is not exposed externally to UI user's browsers.
To set this up, provide the URL that the _Consul agent_ should use to reach the To set this up, provide the URL that the _Consul agent_ should use to reach the
Prometheus server in Prometheus server in
[`ui_config.metrics_proxy.base_url`](/docs/agent/options#ui_config_metrics_proxy_base_url). [`ui_config.metrics_proxy.base_url`](/docs/agent/config/agent-config-files#ui_config_metrics_proxy_base_url).
For example in Kubernetes, the Prometheus helm chart by default installs a For example in Kubernetes, the Prometheus helm chart by default installs a
service named `prometheus-server` so each Consul agent can reach it on service named `prometheus-server` so each Consul agent can reach it on
`http://prometheus-server` (using Kubernetes' DNS resolution). `http://prometheus-server` (using Kubernetes' DNS resolution).
@ -124,7 +124,7 @@ service-specific dashboard in an external tool like
[Grafana](https://grafana.com) or a hosted provider. [Grafana](https://grafana.com) or a hosted provider.
To configure this, you must provide a URL template in the [agent configuration To configure this, you must provide a URL template in the [agent configuration
file](/docs/agent/options#ui_config_dashboard_url_templates) for all agents that file](/docs/agent/config/agent-config-files#ui_config_dashboard_url_templates) for all agents that
have the UI enabled. The template is essentially the URL to the external have the UI enabled. The template is essentially the URL to the external
dashboard, but can have placeholder values which will be replaced with the dashboard, but can have placeholder values which will be replaced with the
service name, namespace and datacenter where appropriate to allow deep-linking service name, namespace and datacenter where appropriate to allow deep-linking
@ -659,12 +659,12 @@ ui_config {
</CodeTabs> </CodeTabs>
More than one JavaScript file may be specified in More than one JavaScript file may be specified in
[`metrics_provider_files`](/docs/agent/options#ui_config_metrics_provider_files), [`metrics_provider_files`](/docs/agent/config/agent-config-files#ui_config_metrics_provider_files)
and all will be served allowing flexibility if needed to include dependencies. and all will be served allowing flexibility if needed to include dependencies.
Only one metrics provider can be configured and used at one time. Only one metrics provider can be configured and used at one time.
The The
[`metrics_provider_options_json`](/docs/agent/options#ui_config_metrics_provider_options_json) [`metrics_provider_options_json`](/docs/agent/config/agent-config-files#ui_config_metrics_provider_options_json)
field is an optional literal JSON object which is passed to the provider's field is an optional literal JSON object which is passed to the provider's
`init` method at startup time. This allows configuring arbitrary parameters for `init` method at startup time. This allows configuring arbitrary parameters for
the provider in config rather than hard coding them into the provider itself to the provider in config rather than hard coding them into the provider itself to
@ -673,7 +673,7 @@ make providers more reusable.
The provider may fetch metrics directly from another source although in this The provider may fetch metrics directly from another source although in this
case the agent will probably need to serve the correct CORS headers to prevent case the agent will probably need to serve the correct CORS headers to prevent
browsers from blocking these requests. These may be configured with browsers from blocking these requests. These may be configured with
[`http_config.response_headers`](/docs/agent/options#response_headers). [`http_config.response_headers`](/docs/agent/config/agent-config-files#response_headers).
Alternatively, the provider may choose to use the [built-in metrics Alternatively, the provider may choose to use the [built-in metrics
proxy](#metrics-proxy) to avoid cross domain issues or to inject additional proxy](#metrics-proxy) to avoid cross domain issues or to inject additional

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

@ -53,8 +53,8 @@ All fields are optional with a reasonable default.
- `bind_port` - The port the proxy will bind its _public_ - `bind_port` - The port the proxy will bind its _public_
mTLS listener to. If not provided, the agent will assign a random port from its mTLS listener to. If not provided, the agent will assign a random port from its
configured proxy port range specified by [`sidecar_min_port`](/docs/agent/options#sidecar_min_port) configured proxy port range specified by [`sidecar_min_port`](/docs/agent/config/agent-config-files#sidecar_min_port)
and [`sidecar_max_port`](/docs/agent/options#sidecar_max_port). and [`sidecar_max_port`](/docs/agent/config/agent-config-files#sidecar_max_port).
- `local_service_address`- The `[address]:port` - `local_service_address`- The `[address]:port`
that the proxy should use to connect to the local application instance. By default that the proxy should use to connect to the local application instance. By default

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

@ -184,7 +184,7 @@ the upstream listeners of any downstream service.
One example is how users can define a service's protocol in a [`service-defaults` configuration One example is how users can define a service's protocol in a [`service-defaults` configuration
entry](/docs/connect/config-entries/service-defaults). Agents with entry](/docs/connect/config-entries/service-defaults). Agents with
[`enable_central_service_config`](/docs/agent/options#enable_central_service_config) [`enable_central_service_config`](/docs/agent/config/agent-config-files#enable_central_service_config)
set to true will automatically discover the protocol when configuring a proxy set to true will automatically discover the protocol when configuring a proxy
for a service. The proxy will discover the main protocol of the service it for a service. The proxy will discover the main protocol of the service it
represents and use this to configure its main public listener. It will also represents and use this to configure its main public listener. It will also

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

@ -24,7 +24,7 @@ Managed proxies have been deprecated since Consul 1.3 and have been fully remove
in Consul 1.6. Anyone using Managed Proxies should aim to change their workflow in Consul 1.6. Anyone using Managed Proxies should aim to change their workflow
as soon as possible to avoid issues with a later upgrade. as soon as possible to avoid issues with a later upgrade.
After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/docs/agent/options#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space. After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/docs/agent/config/agent-config-cli#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space.
**new and known issues will not be fixed**. **new and known issues will not be fixed**.
@ -79,7 +79,7 @@ via agent configuration files. They _cannot_ be registered via the HTTP API.
And 2.) Managed proxies are not started at all if Consul is running as root. And 2.) Managed proxies are not started at all if Consul is running as root.
Both of these default configurations help prevent arbitrary process Both of these default configurations help prevent arbitrary process
execution or privilege escalation. This behavior can be configured execution or privilege escalation. This behavior can be configured
[per-agent](/docs/agent/options). [per-agent](/docs/agent/config).
### Lifecycle ### Lifecycle
@ -275,6 +275,6 @@ level logs showing service discovery, certificate and authorization information.
~> **Note:** In `-dev` mode there is no `data_dir` unless one is explicitly ~> **Note:** In `-dev` mode there is no `data_dir` unless one is explicitly
configured so logging is disabled. You can access logs by providing the configured so logging is disabled. You can access logs by providing the
[`-data-dir`](/docs/agent/options#_data_dir) CLI option. If a data dir is [`-data-dir`](/docs/agent/config/agent-config-cli#_data_dir) CLI option. If a data dir is
configured, this will also cause proxy processes to stay running when the agent configured, this will also cause proxy processes to stay running when the agent
terminates as described in [Lifecycle](#lifecycle). terminates as described in [Lifecycle](#lifecycle).

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

@ -437,8 +437,8 @@ registrations](/docs/discovery/services#service-definition-parameter-case).
- `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#advertise). The port for these listeners are dynamically allocated from [advertise address](/docs/agent/config/agent-config-files#advertise). The port for these listeners are dynamically allocated from
[expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port). [expose_min_port](/docs/agent/config/agent-config-files#expose_min_port) to [expose_max_port](/docs/agent/config/agent-config-files#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.

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

@ -131,8 +131,8 @@ proxy.
- `tags` - Defaults to the tags of the parent service. - `tags` - Defaults to the tags of the parent service.
- `meta` - Defaults to the service metadata of the parent service. - `meta` - Defaults to the service metadata of the parent service.
- `port` - Defaults to being auto-assigned from a configurable - `port` - Defaults to being auto-assigned from a configurable
range specified by [`sidecar_min_port`](/docs/agent/options#sidecar_min_port) range specified by [`sidecar_min_port`](/docs/agent/config/agent-config-files#sidecar_min_port)
and [`sidecar_max_port`](/docs/agent/options#sidecar_max_port). and [`sidecar_max_port`](/docs/agent/config/agent-config-files#sidecar_max_port).
- `kind` - Defaults to `connect-proxy`. This can't be overridden currently. - `kind` - Defaults to `connect-proxy`. This can't be overridden currently.
- `check`, `checks` - By default we add a TCP check on the local address and - `check`, `checks` - By default we add a TCP check on the local address and
port for the proxy, and a [service alias port for the proxy, and a [service alias

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

@ -34,10 +34,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#_enable_local_script_checks): - [`enable_local_script_checks`](/docs/agent/config/agent-config-cli#_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#_enable_script_checks): enable - [`enable_script_checks`](/docs/agent/config/agent-config-cli#_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
@ -109,7 +109,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#_enable_script_checks) must be configured with [`enable_script_checks`](/docs/agent/config/agent-config-cli#_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
@ -467,7 +467,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#_enable_script_checks) set to `true` [`enable_script_checks`](/docs/agent/config/agent-config-cli#_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
@ -543,7 +543,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#enable_agent_tls_for_checks) The [enable_agent_tls_for_checks](/docs/agent/config/agent-config-files#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/content/docs/discovery/dns.mdx
View File

@ -21,18 +21,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#client_addr),[`ports.dns`](/docs/agent/options#dns_port), specifically [`client_addr`](/docs/agent/config/agent-config-files#client_addr),[`ports.dns`](/docs/agent/config/agent-config-files#dns_port),
[`recursors`](/docs/agent/options#recursors),[`domain`](/docs/agent/options#domain), [`recursors`](/docs/agent/config/agent-config-files#recursors),[`domain`](/docs/agent/config/agent-config-files#domain),
[`alt_domain`](/docs/agent/options#alt_domain), and [`dns_config`](/docs/agent/options#dns_config). [`alt_domain`](/docs/agent/config/agent-config-files#alt_domain), and [`dns_config`](/docs/agent/config/agent-config-files#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), [documentation on configuration options](/docs/agent/config),
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#recursors) configuration so that non-Consul queries [`recursors`](/docs/agent/config/agent-config-files#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 tutorial](https://learn.hashicorp.com/tutorials/consul/dns-forwarding?utm_source=consul.io&utm_medium=docs) for examples. [DNS Forwarding tutorial](https://learn.hashicorp.com/tutorials/consul/dns-forwarding?utm_source=consul.io&utm_medium=docs) for examples.
@ -412,15 +412,15 @@ are not truncated.
## Alternative Domain ## Alternative Domain
By default, Consul responds to DNS queries in the `consul` domain, By default, Consul responds to DNS queries in the `consul` domain,
but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/docs/agent/options#domain) parameter. but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/docs/agent/config/agent-config-files#domain) parameter.
In some instances, Consul may need to respond to queries in more than one domain, In some instances, Consul may need to respond to queries in more than one domain,
such as during a DNS migration or to distinguish between internal and external queries. such as during a DNS migration or to distinguish between internal and external queries.
Consul versions 1.5.2+ can be configured to respond to DNS queries on an alternative domain Consul versions 1.5.2+ can be configured to respond to DNS queries on an alternative domain
through the [`alt_domain`](/docs/agent/options#alt_domain) agent configuration through the [`alt_domain`](/docs/agent/config/agent-config-files#alt_domain) agent configuration
option. As of Consul versions 1.11.0+, Consul's DNS response will use the same domain as was used in the query; option. As of Consul versions 1.11.0+, Consul's DNS response will use the same domain as was used in the query;
in prior versions, the response may use the primary [`domain`](/docs/agent/options#domain) no matter which in prior versions, the response may use the primary [`domain`](/docs/agent/config/agent-config-files#domain) no matter which
domain was used in the query. domain was used in the query.
In the following example, the `alt_domain` parameter is set to `test-domain`: In the following example, the `alt_domain` parameter is set to `test-domain`:
@ -448,7 +448,7 @@ machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment="
``` ```
-> **PTR queries:** Responses to PTR queries (`<ip>.in-addr.arpa.`) will always use the -> **PTR queries:** Responses to PTR queries (`<ip>.in-addr.arpa.`) will always use the
[primary domain](/docs/agent/options#domain) (not the alternative domain), [primary domain](/docs/agent/config/agent-config-files#domain) (not the alternative domain),
as there is no way for the query to specify a domain. as there is no way for the query to specify a domain.
## Caching ## Caching
@ -463,8 +463,8 @@ for [DNS caching](https://learn.hashicorp.com/tutorials/consul/dns-caching).
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#_advertise-wan) and using the [`advertise-wan`](/docs/agent/config/agent-config-cli#_advertise-wan) and
[`translate_wan_addrs`](/docs/agent/options#translate_wan_addrs) configuration [`translate_wan_addrs`](/docs/agent/config/agent-config-files#translate_wan_addrs) configuration
options. options.
## Namespaced/Partitioned Services <EnterpriseAlert inline /> ## Namespaced/Partitioned Services <EnterpriseAlert inline />
@ -480,7 +480,7 @@ services from other namespaces or partitions the following form can be used:
This is the canonical name of a Consul Enterprise service. Currently all parts must be This is the canonical name of a Consul Enterprise service. Currently all parts must be
present - in a future version (once the present - in a future version (once the
[`prefer_namespace` configuration](/docs/agent/options#dns_prefer_namespace) has been [`prefer_namespace` configuration](/docs/agent/config/agent-config-files#dns_prefer_namespace) has been
deprecated), the namespace, partition and datacenter components will become optional deprecated), the namespace, partition and datacenter components will become optional
and may be individually omitted to default to the `default` namespace, local partition and may be individually omitted to default to the `default` namespace, local partition
or local datacenter respectively. or local datacenter respectively.
@ -494,7 +494,7 @@ are enabled, you must first create ACL tokens with the necessary policies.
Consul agents resolve DNS requests using one of the preconfigured tokens below, Consul agents resolve DNS requests using one of the preconfigured tokens below,
listed in order of precedence: listed in order of precedence:
1. The agent's [`default` token](/docs/agent/options#acl_tokens_default). 1. The agent's [`default` token](/docs/agent/config/agent-config-files#acl_tokens_default).
2. The built-in [`anonymous` token](/docs/security/acl/acl-system#builtin-tokens). 2. The built-in [`anonymous` token](/docs/security/acl/acl-system#builtin-tokens).
Because the anonymous token is used when any request is made to Consul without Because the anonymous token is used when any request is made to Consul without
explicitly specifying a token, production deployments should not apply policies explicitly specifying a token, production deployments should not apply policies

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

@ -39,7 +39,7 @@ 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#_data_dir). To ensure data is not lost in directory](/docs/agent/config/agent-config-cli#_data_dir). To ensure data is not lost in
the event of a complete outage, use the [`consul snapshot`](/commands/snapshot/restore) feature to backup the data. the event of a complete outage, use the [`consul snapshot`](/commands/snapshot/restore) feature to backup the data.
## Using Consul KV ## Using Consul KV
@ -48,7 +48,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/agent/options#kv_max_value_size) recommendations](/docs/agent/config/agent-config-files#kv_max_value_size)
are usually sufficient. 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.

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

@ -20,7 +20,7 @@ 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#watches), Watches can be configured as part of the [agent's configuration](/docs/agent/config/agent-config-files#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.

8
website/content/docs/enterprise/audit-logging.mdx
View File

@ -25,14 +25,14 @@ For more experience leveraging Consul's audit logging functionality, explore our
HashiCorp Learn tutorial [Capture Consul Events with Audit Logging](https://learn.hashicorp.com/tutorials/consul/audit-logging). HashiCorp Learn tutorial [Capture Consul Events with Audit Logging](https://learn.hashicorp.com/tutorials/consul/audit-logging).
For detailed configuration information on configuring the Consul Enterprise's audit For detailed configuration information on configuring the Consul Enterprise's audit
logging, review the Consul [Audit Log](/docs/agent/options#audit) logging, review the Consul [Audit Log](/docs/agent/config/agent-config-files#audit)
documentation. documentation.
## Example Configuration ## Example Configuration
Audit logging must be enabled on every agent in order to accurately capture all Audit logging must be enabled on every agent in order to accurately capture all
operations performed through the HTTP API. To enable logging, add operations performed through the HTTP API. To enable logging, add
the [`audit`](/docs/agent/options#audit) stanza to the agent's configuration. the [`audit`](/docs/agent/config/agent-config-files#audit) stanza to the agent's configuration.
-> **Note**: Consul only logs operations which are initiated via the HTTP API. -> **Note**: Consul only logs operations which are initiated via the HTTP API.
The audit log does not record operations that take place over the internal RPC The audit log does not record operations that take place over the internal RPC
@ -42,8 +42,8 @@ communication channel used for agent communication.
<Tab heading="Log to file"> <Tab heading="Log to file">
The following example configures a destination called "My Sink". Since rotation is enabled, The following example configures a destination called "My Sink". Since rotation is enabled,
audit events will be stored at files named: `/tmp/audit-<TIMESTAMP>.json`. The log file will audit events will be stored at files named: `/tmp/audit-<TIMESTAMP>.json`. The log file will
be rotated either every 24 hours, or when the log file size is greater than 25165824 bytes be rotated either every 24 hours, or when the log file size is greater than 25165824 bytes
(24 megabytes). (24 megabytes).
<CodeTabs> <CodeTabs>

8
website/content/docs/enterprise/license/overview.mdx
View File

@ -36,7 +36,7 @@ When using these binaries no further action is necessary to configure the licens
### Binaries Without Built In Licenses ### Binaries Without Built In Licenses
For Consul Enterprise 1.10.0 or greater, binaries that do not include built in licenses a license must be available at the time the agent starts. For Consul Enterprise 1.10.0 or greater, binaries that do not include built in licenses a license must be available at the time the agent starts.
For server agents this means that they must either have the [`license_path`](/docs/agent/options#license_path) For server agents this means that they must either have the [`license_path`](/docs/agent/config/agent-config-files#license_path)
configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or
`CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH` `CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH`
environment variable point to a file containing the license whereas the `CONSUL_LICENSE` environment environment variable point to a file containing the license whereas the `CONSUL_LICENSE` environment
@ -55,9 +55,9 @@ to retrieve the license automatically under specific circumstances.
When a client agent starts without a license in its configuration or environment, it will try to retrieve the When a client agent starts without a license in its configuration or environment, it will try to retrieve the
license from the servers via RPCs. That RPC always requires a valid non-anonymous ACL token to authorize the license from the servers via RPCs. That RPC always requires a valid non-anonymous ACL token to authorize the
request but the token doesn't need any particular permissions. As the license is required before the client request but the token doesn't need any particular permissions. As the license is required before the client
actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/options#start_join) actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/config/agent-config-files#start_join)
or [`retry_join`](/docs/agent/options#retry_join) configurations. If those are both unset or no or [`retry_join`](/docs/agent/config/agent-config-files#retry_join) configurations. If those are both unset or no
[`agent` token](/docs/agent/options#acl_tokens_agent) is set then the client agent will immediately shut itself down. [`agent` token](/docs/agent/config/agent-config-files#acl_tokens_agent) is set then the client agent will immediately shut itself down.
If all preliminary checks pass the client agent will attempt to reach out to any server on its RPC port to If all preliminary checks pass the client agent will attempt to reach out to any server on its RPC port to
request the license. These requests will be retried for up to 5 minutes and if it is unable to retrieve a request the license. These requests will be retried for up to 5 minutes and if it is unable to retrieve a

32
website/content/docs/enterprise/network-segments.mdx
View File

@ -15,7 +15,7 @@ description: |-
</EnterpriseAlert> </EnterpriseAlert>
Consul requires full connectivity between all agents (servers and clients) in a Consul requires full connectivity between all agents (servers and clients) in a
[datacenter](/docs/agent/options#_datacenter) within a given [datacenter](/docs/agent/config/agent-config-cli#_datacenter) within a given
LAN gossip pool. By default, all Consul agents will be a part of one shared Serf LAN LAN gossip pool. By default, all Consul agents will be a part of one shared Serf LAN
gossip pool known as the `<default>` network segment, thus requiring full mesh gossip pool known as the `<default>` network segment, thus requiring full mesh
connectivity within the datacenter. connectivity within the datacenter.
@ -46,7 +46,7 @@ Consul networking models and their capabilities.
**Cluster:** A set of Consul servers forming a Raft quorum along with a **Cluster:** A set of Consul servers forming a Raft quorum along with a
collection of Consul clients, all set to the same collection of Consul clients, all set to the same
[datacenter](/docs/agent/options#_datacenter), and joined together to form [datacenter](/docs/agent/config/agent-config-cli#_datacenter), and joined together to form
what we will call a "local cluster". Consul clients discover the Consul servers what we will call a "local cluster". Consul clients discover the Consul servers
in their local cluster through the gossip mechanism and make RPC requests to in their local cluster through the gossip mechanism and make RPC requests to
them. LAN Gossip (OSS) is an open intra-cluster networking model, and Network them. LAN Gossip (OSS) is an open intra-cluster networking model, and Network
@ -72,7 +72,7 @@ group of agents to only connect with the agents in its segment.
Server agents are members of all segments. The datacenter includes a `<default>` Server agents are members of all segments. The datacenter includes a `<default>`
segment, as well as additional segments defined in the segment, as well as additional segments defined in the
[`segments`](/docs/agent/options#segments) server agent configuration option. [`segments`](/docs/agent/config/agent-config-files#segments) server agent configuration option.
Each additional segment is defined by: Each additional segment is defined by:
- a non-empty name - a non-empty name
@ -129,19 +129,19 @@ segments = [
</CodeTabs> </CodeTabs>
The server [agent configuration](/docs/agent/options) options relevant to network The server [agent configuration](/docs/agent/config/agent-config-files) options relevant to network
segments are: segments are:
- [`ports.serf_lan`](/docs/agent/options#serf_lan_port): The Serf LAN port on this server - [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port): The Serf LAN port on this server
for the `<default>` network segment's gossip pool. for the `<default>` network segment's gossip pool.
- [`segments`](/docs/agent/options#segments): A list of user-defined network segments - [`segments`](/docs/agent/config/agent-config-files#segments): A list of user-defined network segments
on this server, including their names and Serf LAN ports. on this server, including their names and Serf LAN ports.
## Client Configuration ## Client Configuration
Each client agent can only be a member of one segment at a time. This will be the Each client agent can only be a member of one segment at a time. This will be the
`<default>` segment unless otherwise specified in the agent's `<default>` segment unless otherwise specified in the agent's
[`segment`](/docs/agent/options#_segment) agent configuration option. [`segment`](/docs/agent/config/agent-config-cli#segment) agent configuration option.
### Join a Client to a Segment ((#join_a_client_to_a_segment)) ### Join a Client to a Segment ((#join_a_client_to_a_segment))
@ -154,14 +154,14 @@ configured segment.
Clients A and B specify the same segment S. Client B is already joined to the segment S Clients A and B specify the same segment S. Client B is already joined to the segment S
LAN gossip pool. Client A wants to join via Client B. In order to do so, Client A LAN gossip pool. Client A wants to join via Client B. In order to do so, Client A
must connect to Client B's configured [Serf LAN port](/docs/agent/options#serf_lan_port). must connect to Client B's configured [Serf LAN port](/docs/agent/config/agent-config-files#serf_lan_port).
</Tab> </Tab>
<Tab heading="Join via a server"> <Tab heading="Join via a server">
Client A specifies segment S and wants to join the segment S gossip pool via Server 1. Client A specifies segment S and wants to join the segment S gossip pool via Server 1.
In order to do so, Client A must connect to Server 1's configured [Serf LAN port In order to do so, Client A must connect to Server 1's configured [Serf LAN port
for segment S](/docs/agent/options#segment_port). for segment S](/docs/agent/config/agent-config-files#segment_port).
</Tab> </Tab>
</Tabs> </Tabs>
@ -171,12 +171,12 @@ of precedence:
1. **Specify an explicit port in the join address**. This can be done at the CLI when starting 1. **Specify an explicit port in the join address**. This can be done at the CLI when starting
the agent (e.g., `consul agent -retry-join "client-b-address:8303"`), or in the agent's the agent (e.g., `consul agent -retry-join "client-b-address:8303"`), or in the agent's
configuration using the [retry-join option](/docs/agent/options#retry_join). This method configuration using the [retry-join option](/docs/agent/config/agent-config-files#retry_join). This method
is not compatible with [cloud auto-join](/docs/install/cloud-auto-join#auto-join-with-network-segments). is not compatible with [cloud auto-join](/docs/install/cloud-auto-join#auto-join-with-network-segments).
2. **Specify an alternate Serf LAN port for the agent**. This can be done at the CLI when starting 2. **Specify an alternate Serf LAN port for the agent**. This can be done at the CLI when starting
the agent (e.g., `consul agent -retry-join "client-b-address" -serf-lan-port 8303`), or in the agent (e.g., `consul agent -retry-join "client-b-address" -serf-lan-port 8303`), or in
the agent's configuration using the [serf_lan](/docs/agent/options#serf_lan_port) option. the agent's configuration using the [serf_lan](/docs/agent/config/agent-config-files#serf_lan_port) option.
When a Serf LAN port is not explicitly specified in the join address, the agent will attempt to When a Serf LAN port is not explicitly specified in the join address, the agent will attempt to
join the target host at the Serf LAN port specified in CLI or agent configuration. join the target host at the Serf LAN port specified in CLI or agent configuration.
@ -221,15 +221,15 @@ ports = {
</CodeTabs> </CodeTabs>
The client [agent configuration](/docs/agent/options) options relevant to network The client [agent configuration](/docs/agent/config/agent-config-files) options relevant to network
segments are: segments are:
- [`segment`](/docs/agent/options#segment-2): The name of the network segment this - [`segment`](/docs/agent/config/agent-config-files#segment-2): The name of the network segment this
client agent belongs to. client agent belongs to.
- [`ports.serf_lan`](/docs/agent/options#serf_lan_port): - [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port):
Serf LAN port for the above segment on this client. This is not required Serf LAN port for the above segment on this client. This is not required
to match the configured Serf LAN port for other agents on this segment. to match the configured Serf LAN port for other agents on this segment.
- [`retry_join`](/docs/agent/options#retry_join) or - [`retry_join`](/docs/agent/config/agent-config-files#retry_join) or
[`start_join`](/docs/agent/options#start_join): A list of agent addresses to join [`start_join`](/docs/agent/config/agent-config-files#start_join): A list of agent addresses to join
when starting. Ensure the correct Serf LAN port for this segment is used when joining when starting. Ensure the correct Serf LAN port for this segment is used when joining
the LAN gossip pool using one of the [available configuration methods](#join_a_client_to_a_segment). the LAN gossip pool using one of the [available configuration methods](#join_a_client_to_a_segment).

4
website/content/docs/enterprise/read-scale.mdx
View File

@ -19,6 +19,6 @@ to include voting servers and read replicas. Read replicas still receive data fr
however, they do not take part in quorum election operations. Expanding your Consul cluster in this way can scale however, they do not take part in quorum election operations. Expanding your Consul cluster in this way can scale
reads without impacting write latency. reads without impacting write latency.
For more details, review the [Consul server configuration](/docs/agent/options) For more details, review the [Consul server configuration](/docs/agent/config)
documentation and the [-read-replica](/docs/agent/options#_read_replica) documentation and the [-read-replica](/docs/agent/config/agent-config-cli#_read_replica)
configuration flag. configuration flag.

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

@ -16,5 +16,5 @@ and a link to our guides that walk you through common tasks. Note that the
guides are located on the HashiCorp Learn site. guides are located on the HashiCorp Learn site.
- Follow [the documentation](/docs/install) to install Consul either with a precompiled binary or from source. - Follow [the documentation](/docs/install) to install Consul either with a precompiled binary or from source.
- Read more about the [configuration options](/docs/agent/options) for Consul servers and clients. - Read more about the [configuration options](/docs/agent/config) for Consul servers and clients.
- Get started using Consul with our step-by-step guides at [HashiCorp Learn](https://learn.hashicorp.com/consul). - Get started using Consul with our step-by-step guides at [HashiCorp Learn](https://learn.hashicorp.com/consul).

14
website/content/docs/install/bootstrapping.mdx
View File

@ -30,16 +30,16 @@ as data loss is inevitable in a failure scenario. Please refer to the
Manual bootstrapping with `-bootstrap` is not recommended in Manual bootstrapping with `-bootstrap` is not recommended in
newer versions of Consul (0.5 and newer) as it is more error-prone. newer versions of Consul (0.5 and newer) as it is more error-prone.
Instead you should use automatic bootstrapping Instead you should use automatic bootstrapping
with [`-bootstrap-expect`](/docs/agent/options#_bootstrap_expect). with [`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect).
## Bootstrapping the Servers ## Bootstrapping the Servers
The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/options#_bootstrap_expect) The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect)
configuration option. This option informs Consul of the expected number of configuration option. This option informs Consul of the expected number of
server nodes and automatically bootstraps when that many servers are available. To prevent server nodes and automatically bootstraps when that many servers are available. To prevent
inconsistencies and split-brain (clusters where multiple servers consider inconsistencies and split-brain (clusters where multiple servers consider
themselves leader) situations, you should either specify the same value for themselves leader) situations, you should either specify the same value for
[`-bootstrap-expect`](/docs/agent/options#_bootstrap_expect) [`-bootstrap-expect`](/docs/agent/config/agent-config-cli#_bootstrap_expect)
or specify no value at all on all the servers. Only servers that specify a value will attempt to bootstrap the cluster. or specify no value at all on all the servers. Only servers that specify a value will attempt to bootstrap the cluster.
Suppose we are starting a three server cluster. We can start `Node A`, `Node B`, and `Node C` with each Suppose we are starting a three server cluster. We can start `Node A`, `Node B`, and `Node C` with each
@ -61,11 +61,11 @@ You can trigger leader election by joining the servers together, to create a clu
There are multiple options for joining the servers. Choose the method which best suits your environment and specific use case. There are multiple options for joining the servers. Choose the method which best suits your environment and specific use case.
- Specify a list of servers with - Specify a list of servers with
[-join](/docs/agent/options#_join) and [-join](/docs/agent/config/agent-config-cli#_join) and
[start_join](/docs/agent/options#start_join) [start_join](/docs/agent/config/agent-config-files#start_join)
options. options.
- Specify a list of servers with [-retry-join](/docs/agent/options#_retry_join) option. - Specify a list of servers with [-retry-join](/docs/agent/config/agent-config-cli#_retry_join) option.
- Use automatic joining by tag for supported cloud environments with the [-retry-join](/docs/agent/options#_retry_join) option. - Use automatic joining by tag for supported cloud environments with the [-retry-join](/docs/agent/config/agent-config-cli#_retry_join) option.
All three methods can be set in the agent configuration file or All three methods can be set in the agent configuration file or
the command line flag. the command line flag.

4
website/content/docs/install/cloud-auto-join.mdx
View File

@ -69,7 +69,7 @@ to use port `8303` as its Serf LAN port prior to attempting to join the cluster.
<Tab heading="Agent configuration"> <Tab heading="Agent configuration">
The following example configuration overrides the default Serf LAN port using the The following example configuration overrides the default Serf LAN port using the
[`ports.serf_lan`](/docs/agent/options#serf_lan_port) configuration option. [`ports.serf_lan`](/docs/agent/config/agent-config-files#serf_lan_port) configuration option.
<CodeBlockConfig filename="client-config.hcl"> <CodeBlockConfig filename="client-config.hcl">
@ -85,7 +85,7 @@ ports {
<Tab heading="Command-line flag"> <Tab heading="Command-line flag">
The following example overrides the default Serf LAN port using the The following example overrides the default Serf LAN port using the
[`-serf-lan-port`](/docs/agent/options#_serf_lan_port) command line flag. [`-serf-lan-port`](/docs/agent/config/agent-config-cli#_serf_lan_port) command line flag.
```shell ```shell
$ consul agent -serf-lan-port=8303 -retry-join "provider=..." $ consul agent -serf-lan-port=8303 -retry-join "provider=..."

2
website/content/docs/install/manual-bootstrap.mdx
View File

@ -23,7 +23,7 @@ storing the cluster state. The client nodes are mostly stateless and rely on the
server nodes, so they can be started easily. server nodes, so they can be started easily.
Manual bootstrapping requires that the first server that is deployed in a new Manual bootstrapping requires that the first server that is deployed in a new
datacenter provide the [`-bootstrap` configuration option](/docs/agent/options#_bootstrap). datacenter provide the [`-bootstrap` configuration option](/docs/agent/config/agent-config-cli#_bootstrap).
This option allows the server This option allows the server
to assert leadership of the cluster without agreement from any other server. to assert leadership of the cluster without agreement from any other server.
This is necessary because at this point, there are no other servers running in This is necessary because at this point, there are no other servers running in

20
website/content/docs/install/performance.mdx
View File

@ -18,7 +18,7 @@ reads work from a fully in-memory data store that is optimized for concurrent ac
## Minimum Server Requirements ((#minimum)) ## Minimum Server Requirements ((#minimum))
In Consul 0.7, the default server [performance parameters](/docs/agent/options#performance) In Consul 0.7, the default server [performance parameters](/docs/agent/config/agent-config-files#performance)
were tuned to allow Consul to run reliably (but relatively slowly) on a server cluster of three were tuned to allow Consul to run reliably (but relatively slowly) on a server cluster of three
[AWS t2.micro](https://aws.amazon.com/ec2/instance-types/) instances. These thresholds [AWS t2.micro](https://aws.amazon.com/ec2/instance-types/) instances. These thresholds
were determined empirically using a leader instance that was under sufficient read, write, were determined empirically using a leader instance that was under sufficient read, write,
@ -43,7 +43,7 @@ The default performance configuration is equivalent to this:
## Production Server Requirements ((#production)) ## Production Server Requirements ((#production))
When running Consul 0.7 and later in production, it is recommended to configure the server When running Consul 0.7 and later in production, it is recommended to configure the server
[performance parameters](/docs/agent/options#performance) back to Consul's original [performance parameters](/docs/agent/config/agent-config-files#performance) back to Consul's original
high-performance settings. This will let Consul servers detect a failed leader and complete high-performance settings. This will let Consul servers detect a failed leader and complete
leader elections much more quickly than the default configuration which extends key Raft leader elections much more quickly than the default configuration which extends key Raft
timeouts by a factor of 5, so it can be quite slow during these events. timeouts by a factor of 5, so it can be quite slow during these events.
@ -103,14 +103,14 @@ Here are some general recommendations:
issues between the servers or insufficient CPU resources. Users in cloud environments issues between the servers or insufficient CPU resources. Users in cloud environments
often bump their servers up to the next instance class with improved networking often bump their servers up to the next instance class with improved networking
and CPU until leader elections stabilize, and in Consul 0.7 or later the [performance and CPU until leader elections stabilize, and in Consul 0.7 or later the [performance
parameters](/docs/agent/options#performance) configuration now gives you tools parameters](/docs/agent/config/agent-config-files#performance) configuration now gives you tools
to trade off performance instead of upsizing servers. You can use the [`consul.raft.leader.lastContact` to trade off performance instead of upsizing servers. You can use the [`consul.raft.leader.lastContact`
telemetry](/docs/agent/telemetry#leadership-changes) to observe how the Raft timing is telemetry](/docs/agent/telemetry#leadership-changes) to observe how the Raft timing is
performing and guide the decision to de-tune Raft performance or add more powerful performing and guide the decision to de-tune Raft performance or add more powerful
servers. servers.
- For DNS-heavy workloads, configuring all Consul agents in a cluster with the - For DNS-heavy workloads, configuring all Consul agents in a cluster with the
[`allow_stale`](/docs/agent/options#allow_stale) configuration option will allow reads to [`allow_stale`](/docs/agent/config/agent-config-files#allow_stale) configuration option will allow reads to
scale across all Consul servers, not just the leader. Consul 0.7 and later enables stale reads scale across all Consul servers, not just the leader. Consul 0.7 and later enables stale reads
for DNS by default. See [Stale Reads](https://learn.hashicorp.com/tutorials/consul/dns-caching#stale-reads) in the for DNS by default. See [Stale Reads](https://learn.hashicorp.com/tutorials/consul/dns-caching#stale-reads) in the
[DNS Caching](https://learn.hashicorp.com/tutorials/consul/dns-caching) guide for more details. It's also good to set [DNS Caching](https://learn.hashicorp.com/tutorials/consul/dns-caching) guide for more details. It's also good to set
@ -121,7 +121,7 @@ Here are some general recommendations:
[stale consistency mode](/api-docs/features/consistency#stale) available to allow reads to scale [stale consistency mode](/api-docs/features/consistency#stale) available to allow reads to scale
across all the servers and not just be forwarded to the leader. across all the servers and not just be forwarded to the leader.
- In Consul 0.9.3 and later, a new [`limits`](/docs/agent/options#limits) configuration is - In Consul 0.9.3 and later, a new [`limits`](/docs/agent/config/agent-config-files#limits) configuration is
available on Consul clients to limit the RPC request rate they are allowed to make against the available on Consul clients to limit the RPC request rate they are allowed to make against the
Consul servers. After hitting the limit, requests will start to return rate limit errors until Consul servers. After hitting the limit, requests will start to return rate limit errors until
time has passed and more requests are allowed. Configuring this across the cluster can help with time has passed and more requests are allowed. Configuring this across the cluster can help with
@ -156,11 +156,11 @@ For **write-heavy** workloads, the total RAM available for overhead must approxi
RAM NEEDED = number of keys * average key size * 2-3x RAM NEEDED = number of keys * average key size * 2-3x
``` ```
Since writes must be synced to disk (persistent storage) on a quorum of servers before they are committed, deploying a disk with high write throughput (or an SSD) will enhance performance on the write side. ([Documentation](/docs/agent/options#_data_dir)) Since writes must be synced to disk (persistent storage) on a quorum of servers before they are committed, deploying a disk with high write throughput (or an SSD) will enhance performance on the write side. ([Documentation](/docs/agent/config/agent-config-cli#_data_dir))
For a **read-heavy** workload, configure all Consul server agents with the `allow_stale` DNS option, or query the API with the `stale` [consistency mode](/api-docs/features/consistency). By default, all queries made to the server are RPC forwarded to and serviced by the leader. By enabling stale reads, any server will respond to any query, thereby reducing overhead on the leader. Typically, the stale response is `100ms` or less from consistent mode but it drastically improves performance and reduces latency under high load. For a **read-heavy** workload, configure all Consul server agents with the `allow_stale` DNS option, or query the API with the `stale` [consistency mode](/api-docs/features/consistency). By default, all queries made to the server are RPC forwarded to and serviced by the leader. By enabling stale reads, any server will respond to any query, thereby reducing overhead on the leader. Typically, the stale response is `100ms` or less from consistent mode but it drastically improves performance and reduces latency under high load.
If the leader server is out of memory or the disk is full, the server eventually stops responding, loses its election and cannot move past its last commit time. However, by configuring `max_stale` and setting it to a large value, Consul will continue to respond to queries during such outage scenarios. ([max_stale documentation](/docs/agent/options#max_stale)). If the leader server is out of memory or the disk is full, the server eventually stops responding, loses its election and cannot move past its last commit time. However, by configuring `max_stale` and setting it to a large value, Consul will continue to respond to queries during such outage scenarios. ([max_stale documentation](/docs/agent/config/agent-config-files#max_stale)).
It should be noted that `stale` is not appropriate for coordination where strong consistency is important (i.e. locking or application leader election). For critical cases, the optional `consistent` API query mode is required for true linearizability; the trade off is that this turns a read into a full quorum write so requires more resources and takes longer. It should be noted that `stale` is not appropriate for coordination where strong consistency is important (i.e. locking or application leader election). For critical cases, the optional `consistent` API query mode is required for true linearizability; the trade off is that this turns a read into a full quorum write so requires more resources and takes longer.
@ -168,7 +168,7 @@ It should be noted that `stale` is not appropriate for coordination where strong
Consul’s agents use network sockets for communicating with the other nodes (gossip) and with the server agent. In addition, file descriptors are also opened for watch handlers, health checks, and log files. For a **write heavy** cluster, the `ulimit` size must be increased from the default value (`1024`) to prevent the leader from running out of file descriptors. Consul’s agents use network sockets for communicating with the other nodes (gossip) and with the server agent. In addition, file descriptors are also opened for watch handlers, health checks, and log files. For a **write heavy** cluster, the `ulimit` size must be increased from the default value (`1024`) to prevent the leader from running out of file descriptors.
To prevent any CPU spikes from a misconfigured client, RPC requests to the server should be [rate limited](/docs/agent/options#limits) To prevent any CPU spikes from a misconfigured client, RPC requests to the server should be [rate limited](/docs/agent/config/agent-config-files#limits)
~> **NOTE** Rate limiting is configured on the client agent only. ~> **NOTE** Rate limiting is configured on the client agent only.
@ -191,8 +191,8 @@ Smearing requests over 30s is sufficient to bring RPC load to a reasonable level
in all but the very largest clusters, but the extra CPU load from cryptographic in all but the very largest clusters, but the extra CPU load from cryptographic
operations could impact the server's normal work. To limit that, Consul since operations could impact the server's normal work. To limit that, Consul since
1.4.1 exposes two ways to limit the impact Certificate signing has on the leader 1.4.1 exposes two ways to limit the impact Certificate signing has on the leader
[`csr_max_per_second`](/docs/agent/options#ca_csr_max_per_second) and [`csr_max_per_second`](/docs/agent/config/agent-config-files#ca_csr_max_per_second) and
[`csr_max_concurrent`](/docs/agent/options#ca_csr_max_concurrent). [`csr_max_concurrent`](/docs/agent/config/agent-config-files#ca_csr_max_concurrent).
By default we set a limit of 50 per second which is reasonable on modest By default we set a limit of 50 per second which is reasonable on modest
hardware but may be too low and impact rotation times if more than 1500 service hardware but may be too low and impact rotation times if more than 1500 service

2
website/content/docs/install/ports.mdx
View File

@ -55,4 +55,4 @@ the Serf WAN port (TCP/UDP) to be listening on both WAN and LAN interfaces. See
**Server RPC** This is used by servers to handle incoming **Server RPC** This is used by servers to handle incoming
requests from other agents. requests from other agents.
Note, the default ports can be changed in the [agent configuration](/docs/agent/options#ports). Note, the default ports can be changed in the [agent configuration](/docs/agent/config/agent-config-files#ports).

4
website/content/docs/k8s/connect/connect-ca-provider.mdx
View File

@ -200,5 +200,5 @@ To update any settings under these keys, you must use Consul's [Update CA Config
To renew the Vault token, use the [`vault token renew`](https://www.vaultproject.io/docs/commands/token/renew) CLI command To renew the Vault token, use the [`vault token renew`](https://www.vaultproject.io/docs/commands/token/renew) CLI command
or API. or API.
[`ca_config`]: /docs/agent/options#connect_ca_config [`ca_config`]: /docs/agent/config/agent-config-files#connect_ca_config
[`ca_provider`]: /docs/agent/options#connect_ca_provider [`ca_provider`]: /docs/agent/config/agent-config-files#connect_ca_provider

16
website/content/docs/k8s/helm.mdx
View File

@ -58,7 +58,7 @@ Use these links to navigate to a particular top-level stanza.
the prefix will be `<helm release name>-consul`. the prefix will be `<helm release name>-consul`.
- `domain` ((#v-global-domain)) (`string: consul`) - The domain Consul will answer DNS queries for - `domain` ((#v-global-domain)) (`string: consul`) - The domain Consul will answer DNS queries for
(see `-domain` (https://consul.io/docs/agent/options#_domain)) and the domain services synced from (see `-domain` (https://consul.io/docs/agent/config/agent-config-cli#_domain)) and the domain services synced from
Consul into Kubernetes will have, e.g. `service-name.service.consul`. Consul into Kubernetes will have, e.g. `service-name.service.consul`.
- `adminPartitions` ((#v-global-adminpartitions)) - <EnterpriseAlert inline /> Enabling `adminPartitions` allows creation of Admin Partitions in Kubernetes clusters. - `adminPartitions` ((#v-global-adminpartitions)) - <EnterpriseAlert inline /> Enabling `adminPartitions` allows creation of Admin Partitions in Kubernetes clusters.
@ -261,7 +261,7 @@ Use these links to navigate to a particular top-level stanza.
``` ```
- `gossipEncryption` ((#v-global-gossipencryption)) - Configures Consul's gossip encryption key. - `gossipEncryption` ((#v-global-gossipencryption)) - Configures Consul's gossip encryption key.
(see `-encrypt` (https://consul.io/docs/agent/options#_encrypt)). (see `-encrypt` (https://consul.io/docs/agent/config/agent-config-cli#_encrypt)).
By default, gossip encryption is not enabled. The gossip encryption key may be set automatically or manually. By default, gossip encryption is not enabled. The gossip encryption key may be set automatically or manually.
The recommended method is to automatically generate the key. The recommended method is to automatically generate the key.
To automatically generate and set a gossip encryption key, set autoGenerate to true. To automatically generate and set a gossip encryption key, set autoGenerate to true.
@ -292,7 +292,7 @@ Use these links to navigate to a particular top-level stanza.
- `recursors` ((#v-global-recursors)) (`array<string>: []`) - A list of addresses of upstream DNS servers that are used to recursively resolve DNS queries. - `recursors` ((#v-global-recursors)) (`array<string>: []`) - A list of addresses of upstream DNS servers that are used to recursively resolve DNS queries.
These values are given as `-recursor` flags to Consul servers and clients. These values are given as `-recursor` flags to Consul servers and clients.
See https://www.consul.io/docs/agent/options#_recursor for more details. See https://www.consul.io/docs/agent/config/agent-config-cli#_recursor for more details.
If this is an empty array (the default), then Consul DNS will only resolve queries for the Consul top level domain (by default `.consul`). If this is an empty array (the default), then Consul DNS will only resolve queries for the Consul top level domain (by default `.consul`).
- `tls` ((#v-global-tls)) - Enables TLS (https://learn.hashicorp.com/tutorials/consul/tls-encryption-secure) - `tls` ((#v-global-tls)) - Enables TLS (https://learn.hashicorp.com/tutorials/consul/tls-encryption-secure)
@ -663,7 +663,7 @@ Use these links to navigate to a particular top-level stanza.
--set 'server.disruptionBudget.maxUnavailable=0'` flag to the helm chart installation --set 'server.disruptionBudget.maxUnavailable=0'` flag to the helm chart installation
command because of a limitation in the Helm templating language. command because of a limitation in the Helm templating language.
- `extraConfig` ((#v-server-extraconfig)) (`string: {}`) - A raw string of extra JSON configuration (https://consul.io/docs/agent/options) for Consul - `extraConfig` ((#v-server-extraconfig)) (`string: {}`) - A raw string of extra JSON configuration (https://consul.io/docs/agent/config) for Consul
servers. This will be saved as-is into a ConfigMap that is read by the Consul servers. This will be saved as-is into a ConfigMap that is read by the Consul
server agents. This can be used to add additional configuration that server agents. This can be used to add additional configuration that
isn't directly exposed by the chart. isn't directly exposed by the chart.
@ -864,7 +864,7 @@ Use these links to navigate to a particular top-level stanza.
- `image` ((#v-client-image)) (`string: null`) - The name of the Docker image (including any tag) for the containers - `image` ((#v-client-image)) (`string: null`) - The name of the Docker image (including any tag) for the containers
running Consul client agents. running Consul client agents.
- `join` ((#v-client-join)) (`array<string>: null`) - A list of valid `-retry-join` values (https://consul.io/docs/agent/options#retry-join). - `join` ((#v-client-join)) (`array<string>: null`) - A list of valid `-retry-join` values (https://consul.io/docs/agent/config/agent-config-files#retry-join).
If this is `null` (default), then the clients will attempt to automatically If this is `null` (default), then the clients will attempt to automatically
join the server cluster running within Kubernetes. join the server cluster running within Kubernetes.
This means that with `server.enabled` set to true, clients will automatically This means that with `server.enabled` set to true, clients will automatically
@ -885,7 +885,7 @@ Use these links to navigate to a particular top-level stanza.
required for Connect. required for Connect.
- `nodeMeta` ((#v-client-nodemeta)) - nodeMeta specifies an arbitrary metadata key/value pair to associate with the node - `nodeMeta` ((#v-client-nodemeta)) - nodeMeta specifies an arbitrary metadata key/value pair to associate with the node
(see https://www.consul.io/docs/agent/options.html#_node_meta) (see https://www.consul.io/docs/agent/config/agent-config-cli#_node_meta)
- `pod-name` ((#v-client-nodemeta-pod-name)) (`string: ${HOSTNAME}`) - `pod-name` ((#v-client-nodemeta-pod-name)) (`string: ${HOSTNAME}`)
@ -929,7 +929,7 @@ Use these links to navigate to a particular top-level stanza.
- `tlsInit` ((#v-client-containersecuritycontext-tlsinit)) (`map`) - The tls-init initContainer - `tlsInit` ((#v-client-containersecuritycontext-tlsinit)) (`map`) - The tls-init initContainer
- `extraConfig` ((#v-client-extraconfig)) (`string: {}`) - A raw string of extra JSON configuration (https://consul.io/docs/agent/options) for Consul - `extraConfig` ((#v-client-extraconfig)) (`string: {}`) - A raw string of extra JSON configuration (https://consul.io/docs/agent/config) for Consul
clients. This will be saved as-is into a ConfigMap that is read by the Consul clients. This will be saved as-is into a ConfigMap that is read by the Consul
client agents. This can be used to add additional configuration that client agents. This can be used to add additional configuration that
isn't directly exposed by the chart. isn't directly exposed by the chart.
@ -1238,7 +1238,7 @@ Use these links to navigate to a particular top-level stanza.
will inherit from `global.metrics.enabled` value. will inherit from `global.metrics.enabled` value.
- `provider` ((#v-ui-metrics-provider)) (`string: prometheus`) - Provider for metrics. See - `provider` ((#v-ui-metrics-provider)) (`string: prometheus`) - Provider for metrics. See
https://www.consul.io/docs/agent/options#ui_config_metrics_provider https://www.consul.io/docs/agent/config/agent-config-files#ui_config_metrics_provider
This value is only used if `ui.enabled` is set to true. This value is only used if `ui.enabled` is set to true.
- `baseURL` ((#v-ui-metrics-baseurl)) (`string: http://prometheus-server`) - baseURL is the URL of the prometheus server, usually the service URL. - `baseURL` ((#v-ui-metrics-baseurl)) (`string: http://prometheus-server`) - baseURL is the URL of the prometheus server, usually the service URL.

4
website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx
View File

@ -22,8 +22,8 @@ you want the clients to be exposed on the Kubernetes internal node IPs (`true`)
their pod IPs (`false`). their pod IPs (`false`).
Finally, `client.join` is set to an array of valid Finally, `client.join` is set to an array of valid
[`-retry-join` values](/docs/agent/options#retry-join). In the [`-retry-join` values](/docs/agent/config/agent-config-cli#retry-join). In the
example above, a fake [cloud auto-join](/docs/install/cloud-auto-join) example above, a fake [cloud auto-join](/docs/agent/cloud-auto-join)
value is specified. This should be set to resolve to the proper addresses of value is specified. This should be set to resolve to the proper addresses of
your existing Consul cluster. your existing Consul cluster.

4
website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx
View File

@ -271,8 +271,8 @@ The automatically generated federation secret contains:
- **Consul server config** - This is a JSON snippet that must be used as part of the server config for secondary datacenters. - **Consul server config** - This is a JSON snippet that must be used as part of the server config for secondary datacenters.
It sets: It sets:
- [`primary_datacenter`](/docs/agent/options#primary_datacenter) to the name of the primary datacenter. - [`primary_datacenter`](/docs/agent/config/agent-config-files#primary_datacenter) to the name of the primary datacenter.
- [`primary_gateways`](/docs/agent/options#primary_gateways) to an array of IPs or hostnames - [`primary_gateways`](/docs/agent/config/agent-config-files#primary_gateways) to an array of IPs or hostnames
for the mesh gateways in the primary datacenter. These are the addresses that for the mesh gateways in the primary datacenter. These are the addresses that
Consul servers in secondary clusters will use to communicate with the primary Consul servers in secondary clusters will use to communicate with the primary
datacenter. datacenter.

2
website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx
View File

@ -95,7 +95,7 @@ The following sections detail how to export this data.
==> Saved dc1-client-consul-0-key.pem ==> Saved dc1-client-consul-0-key.pem
``` ```
Or use the [auto_encrypt](/docs/agent/options#auto_encrypt) feature. Or use the [auto_encrypt](/docs/agent/config/agent-config-files#auto_encrypt) feature.
### Mesh Gateway Addresses ### Mesh Gateway Addresses

6
website/content/docs/nia/configuration.mdx
View File

@ -61,7 +61,7 @@ tls {
The `consul` block is used to configure CTS connection with a Consul agent to perform queries to the Consul Catalog and Consul KV pertaining to task execution. The `consul` block is used to configure CTS connection with a Consul agent to perform queries to the Consul Catalog and Consul KV pertaining to task execution.
-> **Note:** Use HTTP/2 to improve CTS performance when communicating with the local Consul process. [TLS/HTTPS](/docs/agent/options) must be configured for the local Consul with the [cert_file](/docs/agent/options#cert_file) and [key_file](/docs/agent/options#key_file) parameters set. For the CTS configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false` or add the certificate to `ca_cert` or `ca_path`. -> **Note:** Use HTTP/2 to improve Consul-Terraform-Sync performance when communicating with the local Consul process. [TLS/HTTPS](/docs/agent/config/agent-config-files) must be configured for the local Consul with the [cert_file](/docs/agent/config/agent-config-filess#cert_file) and [key_file](/docs/agent/config/agent-config-files#key_file) parameters set. For the Consul-Terraform-Sync configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false` or add the certificate to `ca_cert` or `ca_path`.
To read more on suggestions for configuring the Consul agent, see [run an agent](/docs/nia/installation/requirements#run-an-agent). To read more on suggestions for configuring the Consul agent, see [run an agent](/docs/nia/installation/requirements#run-an-agent).
@ -80,7 +80,7 @@ consul {
- `enabled` - (bool) - `enabled` - (bool)
- `username` - (string) - `username` - (string)
- `password` - (string) - `password` - (string)
- `tls` - Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for CTS when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/options#verify_incoming). - `tls` - Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/config/agent-config-files#verify_incoming).
- `enabled` - (bool) Enable TLS. Providing a value for any of the TLS options will enable this parameter implicitly. - `enabled` - (bool) Enable TLS. Providing a value for any of the TLS options will enable this parameter implicitly.
- `verify` - (bool: true) Enables TLS peer verification. The default is enabled, which will check the global certificate authority (CA) chain to make sure the certificates returned by Consul are valid. - `verify` - (bool: true) Enables TLS peer verification. The default is enabled, which will check the global certificate authority (CA) chain to make sure the certificates returned by Consul are valid.
- If Consul is using a self-signed certificate that you have not added to the global CA chain, you can set this certificate with `ca_cert` or `ca_path`. Alternatively, you can disable SSL verification by setting `verify` to false. However, disabling verification is a potential security vulnerability. - If Consul is using a self-signed certificate that you have not added to the global CA chain, you can set this certificate with `ca_cert` or `ca_path`. Alternatively, you can disable SSL verification by setting `verify` to false. However, disabling verification is a potential security vulnerability.
@ -98,7 +98,7 @@ consul {
- `max_idle_conns` - (int: 0) The maximum number of total idle connections across all hosts. The limit is disabled by default. - `max_idle_conns` - (int: 0) The maximum number of total idle connections across all hosts. The limit is disabled by default.
- `max_idle_conns_per_host` - (int: 100) The maximum number of idle connections per remote host. The majority of connections are established with one host, the Consul agent. - `max_idle_conns_per_host` - (int: 100) The maximum number of idle connections per remote host. The majority of connections are established with one host, the Consul agent.
- To achieve the shortest latency between a Consul service update to a task execution, configure `max_idle_conns_per_host` equal to or greater than the number of services in automation across all tasks. - To achieve the shortest latency between a Consul service update to a task execution, configure `max_idle_conns_per_host` equal to or greater than the number of services in automation across all tasks.
- This value should be lower than the configured [`http_max_conns_per_client`](/docs/agent/options#http_max_conns_per_client) for the Consul agent. If `max_idle_conns_per_host` and the number of services in automation is greater than the Consul agent limit, CTS may error due to connection limits (status code 429). You may increase the agent limit with caution. _Note: requests to the Consul agent made by Terraform subprocesses or any other process on the same host as CTS will contribute to the Consul agent connection limit._ - This value should be lower than the configured [`http_max_conns_per_client`](/docs/agent/config/agent-config-files#http_max_conns_per_client) for the Consul agent. If `max_idle_conns_per_host` and the number of services in automation is greater than the Consul agent limit, Consul-Terraform-Sync may error due to connection limits (status code 429). You may increase the agent limit with caution. _Note: requests to the Consul agent made by Terraform subprocesses or any other process on the same host as Consul-Terraform-Sync will contribute to the Consul agent connection limit._
- `tls_handshake_timeout` - (string: "10s") amount of time to wait to complete the TLS handshake. - `tls_handshake_timeout` - (string: "10s") amount of time to wait to complete the TLS handshake.
## Service ## Service

2
website/content/docs/nia/installation/requirements.mdx
View File

@ -35,7 +35,7 @@ The Consul agent must be running in order to dynamically update network devices.
When running a Consul agent with CTS in production, we suggest to keep a few considerations in mind. CTS uses [blocking queries](/api-docs/features/blocking) to monitor task dependencies, like changes to registered services. This results in multiple long running TCP connections between CTS and the agent to poll changes for each dependency. Monitoring a high number of services may quickly hit the default Consul agent connection limits. When running a Consul agent with CTS in production, we suggest to keep a few considerations in mind. CTS uses [blocking queries](/api-docs/features/blocking) to monitor task dependencies, like changes to registered services. This results in multiple long running TCP connections between CTS and the agent to poll changes for each dependency. Monitoring a high number of services may quickly hit the default Consul agent connection limits.
There are 2 ways to fix this issue. The first and recommended fix is to use HTTP/2 (requires HTTPS) to communicate between CTS and the Consul agent. When using HTTP/2 only a single connection is made and reused for all communications. See the [Consul Configuration section](/docs/nia/configuration#consul) for more. The other option is to configure [`limits.http_max_conns_per_client`](/docs/agent/options#http_max_conns_per_client) for the agent to a reasonable value proportional to the number of services monitored by CTS. There are 2 ways to fix this issue. The first and recommended fix is to use HTTP/2 (requires HTTPS) to communicate between Consul-Terraform-Sync and the Consul agent. When using HTTP/2 only a single connection is made and reused for all communications. See the [Consul Configuration section](/docs/nia/configuration#consul) for more. The other option is to configure [`limits.http_max_conns_per_client`](/docs/agent/config/agent-config-files#http_max_conns_per_client) for the agent to a reasonable value proportional to the number of services monitored by Consul-Terraform-Sync.
### Register Services ### Register Services

2
website/content/docs/releases/release-notes/v1_9_0.mdx
View File

@ -21,7 +21,7 @@ page_title: 1.9.0
- **Active Health Checks for Consul on Kubernetes:** Consul service mesh now integrates with Kubernetes Readiness probes. This provides the ability to natively detect health status from Kubernetes via Readiness probe, and is then used for directing service mesh traffic. - **Active Health Checks for Consul on Kubernetes:** Consul service mesh now integrates with Kubernetes Readiness probes. This provides the ability to natively detect health status from Kubernetes via Readiness probe, and is then used for directing service mesh traffic.
- **Streaming:** This feature introduces a major architectural enhancement in how update notifications for blocking queries are delivered within the cluster. Streaming results in very significant reduction of CPU and network bandwidth usage on Consul servers in large-scale deployments. Streaming is particularly helpful in scaling blocking queries in Consul clusters that have rapid changes in service state. - **Streaming:** This feature introduces a major architectural enhancement in how update notifications for blocking queries are delivered within the cluster. Streaming results in very significant reduction of CPU and network bandwidth usage on Consul servers in large-scale deployments. Streaming is particularly helpful in scaling blocking queries in Consul clusters that have rapid changes in service state.
- Streaming is now available for the service health HTTP endpoint, and can be enabled through the [`use_streaming_backend`](/docs/agent/options#use_streaming_backend) client configuration option, and [`rpc.enable_streaming`](/docs/agent/options#rpc_enable_streaming) option on the servers. We will continue to enable streaming in more endpoints in subsequent releases. - Streaming is now available for the service health HTTP endpoint, and can be enabled through the [`use_streaming_backend`](/docs/agent/config/agent-config-files#use_streaming_backend) client configuration option, and [`rpc.enable_streaming`](/docs/agent/config/agent-config-files#rpc_enable_streaming) option on the servers. We will continue to enable streaming in more endpoints in subsequent releases.
## What's Changed ## What's Changed

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

@ -89,7 +89,7 @@ and [Policies](/api-docs/acl/policies).
~> **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`](/docs/agent/options#primary_datacenter). parameter has been updated to [`primary_datacenter`](/docs/agent/config/agent-config-files#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
@ -129,7 +129,7 @@ token are automatically applied. The anonymous token is managed using the
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 an allowlist or denylist mode has access to. Policies can be defined in either an allowlist or denylist mode
depending on the configuration of depending on the configuration of
[`acl_default_policy`](/docs/agent/options#acl_default_policy). If the default [`acl_default_policy`](/docs/agent/config/agent-config-files#acl_default_policy). If the default
policy is to "deny" all actions, then token rules can be set to allowlist specific policy is to "deny" all actions, then token rules can be set to allowlist specific
actions. In the inverse, the "allow" all default behavior is a denylist where rules actions. In the inverse, the "allow" all default behavior is a denylist 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.
@ -169,7 +169,7 @@ 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#acl_datacenter) which enables ACL [`acl_datacenter`](/docs/agent/config/agent-config-files#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/architecture) to support multi-datacenter [RPC forwarding](/docs/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,
@ -179,14 +179,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#acl_ttl). The implication of caching is that [`acl_ttl`](/docs/agent/config/agent-config-files#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#acl_down_policy) is set accordingly. [`acl_down_policy`](/docs/agent/config/agent-config-files#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,10 +198,10 @@ 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#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | | [`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs |
| [`acl_default_policy`](/docs/agent/options#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | | [`acl_default_policy`](/docs/agent/config/agent-config-files#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode |
| [`acl_down_policy`](/docs/agent/options#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | | [`acl_down_policy`](/docs/agent/config/agent-config-files#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline |
| [`acl_ttl`](/docs/agent/options#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | | [`acl_ttl`](/docs/agent/config/agent-config-files#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
@ -210,19 +210,19 @@ below.
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_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api-docs/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_master_token`](/docs/agent/config/agent-config-files#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api-docs/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#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/config/agent-config-files#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#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/config/agent-config-files#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#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/config/agent-config-files#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-docs/agent#update-acl-tokens). [/v1/agent/token API](/api-docs/agent#update-acl-tokens).
#### ACL Agent Master Token #### ACL Agent Master Token
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): Since the [`acl_agent_master_token`](/docs/agent/config/agent-config-files#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>" {
@ -238,7 +238,7 @@ In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via
#### ACL Agent Token #### ACL Agent Token
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: The [`acl_agent_token`](/docs/agent/config/agent-config-files#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/config/agent-config-files#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-docs/catalog), including updating its node metadata, tagged addresses, and network coordinates 1. Updating the agent's node entry using the [Catalog API](/api-docs/catalog), including updating its node metadata, tagged addresses, and network coordinates
2. Performing [anti-entropy](/docs/architecture/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog 2. Performing [anti-entropy](/docs/architecture/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog
@ -258,7 +258,7 @@ 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#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/config/agent-config-files#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-docs/agent#update-acl-tokens). [/v1/agent/token API](/api-docs/agent#update-acl-tokens).
@ -294,12 +294,12 @@ 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#acl_master_token) will be created The [`acl_master_token`](/docs/agent/config/agent-config-files#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#acl_master_token) is only installed when [`acl_master_token`](/docs/agent/config/agent-config-files#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#acl_master_token), set the new value for [`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token), set the new value for
[`acl_master_token`](/docs/agent/options#acl_master_token) in the configuration [`acl_master_token`](/docs/agent/config/agent-config-files#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-docs/acl#bootstrap-acls) In Consul 0.9.1 and later, you can use the [/v1/acl/bootstrap API](/api-docs/acl#bootstrap-acls)
@ -332,7 +332,7 @@ 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#acl_agent_token) that it can use for its [`acl_agent_token`](/docs/agent/config/agent-config-files#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/architecture/anti-entropy) syncing. We can create a token using the [anti-entropy](/docs/architecture/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:
@ -550,9 +550,9 @@ 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#acl_token) An alternative to the anonymous token is the [`acl_token`](/docs/agent/config/agent-config-files#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#acl_token) will be used for the token, supplied, the [`acl_token`](/docs/agent/config/agent-config-files#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
@ -563,7 +563,7 @@ agent, if desired. For example, this allows more fine grained control of what DN
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#acl_token), then it's likely the anonymous If using [`acl_token`](/docs/agent/config/agent-config-files#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)
@ -727,7 +727,7 @@ starts with "bar".
Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to Since [Agent API](/api-docs/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#acl_agent_master_token) to allow configured with [`acl_agent_master_token`](/docs/agent/config/agent-config-files#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
@ -753,7 +753,7 @@ starts with "deploy".
The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during The [`consul exec`](/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#disable_remote_exec) to `false`. [`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) to `false`.
#### Key/Value Rules #### Key/Value Rules
@ -861,13 +861,13 @@ 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#acl_agent_token) Agents need to be configured with an [`acl_agent_token`](/docs/agent/config/agent-config-files#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#acl_token) used by the agent does not have "read" access to a [`acl_token`](/docs/agent/config/agent-config-files#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
@ -880,7 +880,7 @@ periodic [anti-entropy](/docs/architecture/anti-entropy) syncs, which may requir
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#acl_token) configuration 1. Using the [acl_token](/docs/agent/config/agent-config-files#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
@ -891,7 +891,7 @@ to use for registration events:
[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#_enable_script_checks) set to `true` in order to enable [`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) set to `true` in order to enable
script checks. script checks.
#### Operator Rules #### Operator Rules
@ -1025,7 +1025,7 @@ 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#acl_token) used by the agent does not have "read" access to a [`acl_token`](/docs/agent/config/agent-config-files#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
@ -1037,7 +1037,7 @@ performs periodic [anti-entropy](/docs/architecture/anti-entropy) syncs, which m
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#acl_token) configuration 1. Using the [acl_token](/docs/agent/config/agent-config-files#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
@ -1048,12 +1048,12 @@ to use for registration events:
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#acl_token) for notes on securing documentation](/docs/agent/config/agent-config-files#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#_enable_script_checks) or [`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) or
[`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks) [`enable_local_script_checks`](/docs/agent/config/agent-config-files#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
@ -1084,20 +1084,20 @@ 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#acl_datacenter) or networking of the [`acl_datacenter`](/docs/agent/config/agent-config-files#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#acl_down_policy) a number of configurable [`acl_down_policy`](/docs/agent/config/agent-config-files#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#acl_replication_token) in the [`acl_replication_token`](/docs/agent/config/agent-config-files#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#enable_acl_replication) and [`enable_acl_replication`](/docs/agent/config/agent-config-files#enable_acl_replication) and
then set the token later using the then set the token later using the
[agent token API](/api-docs/agent#update-acl-tokens) on each server. This can [agent token API](/api-docs/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.
@ -1113,7 +1113,7 @@ 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#acl_down_policy) and the [`acl_down_policy`](/docs/agent/config/agent-config-files#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-docs/acl#check-acl-replication) replicated set of ACLs. An [ACL replication status](/api-docs/acl#check-acl-replication)
endpoint is available to monitor the health of the replication process. endpoint is available to monitor the health of the replication process.
@ -1123,7 +1123,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#acl_ttl) Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/config/agent-config-files#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.
@ -1149,7 +1149,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#acl_enforce_version_8) configuration [`acl_enforce_version_8`](/docs/agent/config/agent-config-files#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:
@ -1172,31 +1172,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#acl_agent_master_token) is used as - [`acl_agent_master_token`](/docs/agent/config/agent-config-files#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#acl_agent_token) is used internally by - [`acl_agent_token`](/docs/agent/config/agent-config-files#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#acl_down_policy) Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/config/agent-config-files#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#acl_datacenter) configured Consul clients must have [`acl_datacenter`](/docs/agent/config/agent-config-files#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#acl_agent_master_token) to need to use the [`acl_agent_master_token`](/docs/agent/config/agent-config-files#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#acl_down_policy) on the to the cluster), unless the [`acl_down_policy`](/docs/agent/config/agent-config-files#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#acl_master_token) configured; it is not [`acl_master_token`](/docs/agent/config/agent-config-files#acl_master_token) configured; it is not
used by agents in any way. used by agents in any way.

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

@ -100,7 +100,7 @@ partition_prefix "ex-" {
<CodeBlockConfig> <CodeBlockConfig>
```json ```json
({ {
"partition": [ "partition": [
{ {
"example": [ "example": [
@ -171,7 +171,7 @@ partition_prefix "ex-" {
] ]
} }
] ]
}) }
``` ```
</CodeBlockConfig> </CodeBlockConfig>
@ -227,7 +227,7 @@ with `bar`.
Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to Since [Agent API](/api-docs/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_recovery`](/docs/agent/options#acl_tokens_agent_recovery) to allow configured with [`acl.tokens.agent_recovery`](/docs/agent/config/agent-config-files#acl_tokens_agent_recovery) 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
@ -272,7 +272,7 @@ read-only access to any event, and firing of the "deploy" event.
The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during The [`consul exec`](/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#disable_remote_exec) to `false`. [`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) to `false`.
## Key/Value Rules ## Key/Value Rules
@ -640,18 +640,18 @@ node "admin" {
Agents must be configured with `write` privileges for their own node name so that the agent can register their node metadata, tagged addresses, and other information in the catalog. Agents must be configured with `write` privileges for their own node name so that the agent can register their node metadata, tagged addresses, and other information in the catalog.
If configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog. If configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog.
Configure `write` access in the [`acl.tokens.agent`](/docs/agent/options#acl_tokens_agent) parameter. Configure `write` access in the [`acl.tokens.agent`](/docs/agent/config/agent-config-files#acl_tokens_agent) parameter.
The [`acl.token.default`](/docs/agent/options#acl_tokens_default) used by the agent should have `read` access to a given node so that the DNS interface can be queried. The [`acl.token.default`](/docs/agent/config/agent-config-files#acl_tokens_default) used by the agent should have `read` access to a given node so that the DNS interface can be queried.
Node rules are used to filter query results when reading from the catalog or retrieving information from the health endpoints. This allows for configurations where a token has access to a given service name, but only on an allowed subset of node names. Node rules are used to filter query results when reading from the catalog or retrieving information from the health endpoints. This allows for configurations where a token has access to a given service name, but only on an allowed subset of node names.
Consul agents check tokens locally when health checks are registered and when Consul performs periodic [anti-entropy](/docs/architecture/anti-entropy) syncs. Consul agents check tokens locally when health checks are registered and when Consul performs periodic [anti-entropy](/docs/architecture/anti-entropy) syncs.
These actions may required an ACL token to complete. Use the following methods to configure ACL tokens for registration events: These actions may required an ACL token to complete. Use the following methods to configure ACL tokens for registration events:
- Configure a global token in the [acl.tokens.default](/docs/agent/options#acl_tokens_default) parameter. * Configure a global token in the [acl.tokens.default](/docs/agent/config/agent-config-files#acl_tokens_default) parameter.
This allows a single token to be used during all check registration operations. This allows a single token to be used during all check registration operations.
- Provide an ACL token with `service` and `check` definitions at registration time. * Provide an ACL token with `service` and `check` definitions at registration time.
This allows for greater flexibility and enables the use of multiple tokens on the same agent. This allows for greater flexibility and enables the use of multiple tokens on the same agent.
Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples. Refer to the [services](/docs/agent/services) and [checks](/docs/agent/checks) documentation for examples.
Tokens may also be passed to the [HTTP API](/api) for operations that require them. Tokens may also be passed to the [HTTP API](/api) for operations that require them.
@ -835,7 +835,7 @@ service "admin" {
</CodeTabs> </CodeTabs>
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#acl_tokens_default) used by the agent does not have `read` access to a [`acl.tokens.default`](/docs/agent/config/agent-config-files#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
@ -847,7 +847,7 @@ performs periodic [anti-entropy](/docs/architecture/anti-entropy) syncs, which m
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#acl_tokens_default) configuration 1. Using the [acl.tokens.default](/docs/agent/config/agent-config-files#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
@ -858,12 +858,12 @@ to use for registration events:
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#acl_token) for notes on securing documentation](/docs/agent/config/agent-config-files#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#_enable_script_checks) or [`enable_script_checks`](/docs/agent/config/agent-config-files#enable_script_checks) or
[`enable_local_script_checks`](/docs/agent/options#_enable_local_script_checks) [`enable_local_script_checks`](/docs/agent/config/agent-config-files#enable_local_script_checks)
set to `true` in order to enable script checks. set to `true` in order to enable script checks.
Service rules are also used to grant read or write access to intentions. The Service rules are also used to grant read or write access to intentions. The

2
website/content/docs/security/acl/auth-methods/index.mdx
View File

@ -60,7 +60,7 @@ using the API or command line before they can be used by applications.
endpoints](/api-docs/acl/binding-rules). endpoints](/api-docs/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#acl_enable_token_replication) [ACL token replication](/docs/agent/config/agent-config-files#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.

22
website/content/docs/security/encryption.mdx
View File

@ -75,17 +75,17 @@ CA then signs keys for each of the agents, as in
~> Certificates need to be created with x509v3 extendedKeyUsage attributes for both clientAuth and serverAuth since Consul uses a single cert/key pair for both server and client communications. ~> Certificates need to be created with x509v3 extendedKeyUsage attributes for both clientAuth and serverAuth since Consul uses a single cert/key pair for both server and client communications.
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#tls_internal_rpc_verify_outgoing), These modes are controlled by the [`verify_outgoing`](/docs/agent/config/agent-config-files#tls_internal_rpc_verify_outgoing),
[`verify_server_hostname`](/docs/agent/options#tls_internal_rpc_verify_server_hostname), [`verify_server_hostname`](/docs/agent/config/agent-config-files#tls_internal_rpc_verify_server_hostname),
and [`verify_incoming`](/docs/agent/options#tls_internal_rpc_verify_incoming) options, respectively. and [`verify_incoming`](/docs/agent/config/agent-config-files#tls_internal_rpc_verify_incoming) options, respectively.
If [`verify_outgoing`](/docs/agent/options#tls_internal_rpc_verify_outgoing) is set, agents verify the If [`verify_outgoing`](/docs/agent/config/agent-config-files#tls_internal_rpc_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#tls_internal_rpc_ca_file) and [`ca_path`](/docs/agent/options#tls_internal_rpc_ca_path) [`ca_file`](/docs/agent/config/agent-config-files#tls_internal_rpc_ca_file) and [`ca_path`](/docs/agent/config/agent-config-files#tls_internal_rpc_ca_path)
options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/options#tls_internal_rpc_cert_file) and [`key_file`](/docs/agent/options#tls_internal_rpc_key_file). options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/config/agent-config-files#tls_internal_rpc_cert_file) and [`key_file`](/docs/agent/config/agent-config-files#tls_internal_rpc_key_file).
If [`verify_server_hostname`](/docs/agent/options#tls_internal_rpc_verify_server_hostname) is set, then If [`verify_server_hostname`](/docs/agent/config/agent-config-files#tls_internal_rpc_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#tls_internal_rpc_verify_incoming) is set, the servers verify the If [`verify_incoming`](/docs/agent/config/agent-config-files#tls_internal_rpc_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#tls_internal_rpc_cert_file) and [`cert_file`](/docs/agent/config/agent-config-files#tls_internal_rpc_cert_file) and
[`key_file`](/docs/agent/options#tls_internal_rpc_key_file). Servers will [`key_file`](/docs/agent/config/agent-config-files#tls_internal_rpc_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#tls_internal_rpc_verify_outgoing) must also be set. [`verify_outgoing`](/docs/agent/config/agent-config-files#tls_internal_rpc_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.

54
website/content/docs/security/security-models/core.mdx
View File

@ -72,32 +72,32 @@ environment and adapt these configurations accordingly.
- **mTLS** - Mutual authentication of both the TLS server and client x509 certificates prevents internal abuse through - **mTLS** - Mutual authentication of both the TLS server and client x509 certificates prevents internal abuse through
unauthorized access to Consul agents within the cluster. unauthorized access to Consul agents within the cluster.
- [`tls.defaults.verify_incoming`](/docs/agent/options#tls_defaults_verify_incoming) - By default this is false, and - [`tls.defaults.verify_incoming`](/docs/agent/config/agent-config-files#tls_defaults_verify_incoming) - By default this is false, and
should almost always be set to true to require TLS verification for incoming client connections. This applies to the should almost always be set to true to require TLS verification for incoming client connections. This applies to the
internal RPC, HTTPS and gRPC APIs. internal RPC, HTTPS and gRPC APIs.
- [`tls.https.verify_incoming`](/docs/agent/options#tls_https_verify_incoming) - By default this is false, and should - [`tls.https.verify_incoming`](/docs/agent/config/agent-config-files#tls_https_verify_incoming) - By default this is false, and should
be set to true to require clients to provide a valid TLS certificate when the Consul HTTPS API is enabled. TLS for be set to true to require clients to provide a valid TLS certificate when the Consul HTTPS API is enabled. TLS for
the API may be not be necessary if it is exclusively served over a loopback interface such as `localhost`. the API may be not be necessary if it is exclusively served over a loopback interface such as `localhost`.
- [`tls.internal_rpc.verify_incoming`](/docs/agent/options#tls_internal_rpc_verify_incoming) - By default this is false, - [`tls.internal_rpc.verify_incoming`](/docs/agent/config/agent-config-files#tls_internal_rpc_verify_incoming) - By default this is false,
and should almost always be set to true to require clients to provide a valid TLS certificate for Consul agent RPCs. and should almost always be set to true to require clients to provide a valid TLS certificate for Consul agent RPCs.
- [`tls.grpc.verify_incoming`](/docs/agent/options#tls_grpc_verify_incoming) - By default this is false, and should - [`tls.grpc.verify_incoming`](/docs/agent/options#tls_grpc_verify_incoming) - By default this is false, and should
be set to true to require clients to provide a valid TLS certificate when the Consul gRPC API is enabled. TLS for be set to true to require clients to provide a valid TLS certificate when the Consul gRPC API is enabled. TLS for
the API may be not be necessary if it is exclusively served over a loopback interface such as `localhost`. the API may be not be necessary if it is exclusively served over a loopback interface such as `localhost`.
- [`tls.internal_rpc.verify_outgoing`](/docs/agent/options#tls_internal_rpc_verify_outgoing) - By default this is false, - [`tls.internal_rpc.verify_outgoing`](/docs/agent/config/agent-config-files#tls_internal_rpc_verify_outgoing) - By default this is false,
and should be set to true to require TLS for outgoing connections from server or client agents. Servers that specify and should be set to true to require TLS for outgoing connections from server or client agents. Servers that specify
`verify_outgoing = true` will always talk to other servers over TLS, but they still accept non-TLS connections to allow `verify_outgoing = true` will always talk to other servers over TLS, but they still accept non-TLS connections to allow
for a transition of all clients to TLS. Currently the only way to enforce that no client can communicate with a server for a transition of all clients to TLS. Currently the only way to enforce that no client can communicate with a server
unencrypted is to also enable `verify_incoming` which requires client certificates too. unencrypted is to also enable `verify_incoming` which requires client certificates too.
- [`enable_agent_tls_for_checks`](/docs/agent/options#enable_agent_tls_for_checks) - By default this is false, and - [`enable_agent_tls_for_checks`](/docs/agent/config/agent-config-files#enable_agent_tls_for_checks) - By default this is false, and
should almost always be set to true to require mTLS to set up the client for HTTP or gRPC health checks. This was should almost always be set to true to require mTLS to set up the client for HTTP or gRPC health checks. This was
added in Consul 1.0.1. added in Consul 1.0.1.
- [`tls.internal_rpc.verify_server_hostname`](/docs/agent/options#tls_internal_rpc_verify_server_hostname) - By default - [`tls.internal_rpc.verify_server_hostname`](/docs/agent/config/agent-config-files#tls_internal_rpc_verify_server_hostname) - By default
this is false, and should be set to true to require that the TLS certificate presented by the servers matches this is false, and should be set to true to require that the TLS certificate presented by the servers matches
`server.<datacenter>.<domain>` hostname for outgoing TLS connections. The default configuration does not verify the `server.<datacenter>.<domain>` hostname for outgoing TLS connections. The default configuration does not verify the
hostname of the certificate, only that it is signed by a trusted CA. This setting is critical to prevent a hostname of the certificate, only that it is signed by a trusted CA. This setting is critical to prevent a
@ -108,14 +108,14 @@ environment and adapt these configurations accordingly.
[CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653) for more details. This is fixed [CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653) for more details. This is fixed
in 1.4.1. in 1.4.1.
- [`auto_encrypt`](/docs/agent/options#auto_encrypt) - Enables automated TLS certificate distribution for client - [`auto_encrypt`](/docs/agent/config/agent-config-files#auto_encrypt) - Enables automated TLS certificate distribution for client
agent RPC communication using the Connect CA. Using this configuration a [`ca_file`](/docs/agent/options#tls_defaults_ca_file) agent RPC communication using the Connect CA. Using this configuration a [`ca_file`](/docs/agent/config/agent-config-files#tls_defaults_ca_file)
and ACL token would still need to be distributed to client agents. and ACL token would still need to be distributed to client agents.
- [`allow_tls`](/docs/agent/options#allow_tls) - By default this is false, and should be set to true on server - [`allow_tls`](/docs/agent/config/agent-config-files#allow_tls) - By default this is false, and should be set to true on server
agents to allow certificates to be automatically generated and distributed from the Connect CA to client agents. agents to allow certificates to be automatically generated and distributed from the Connect CA to client agents.
- [`tls`](/docs/agent/options#tls) - By default this is false, and should be set to true on client agents to - [`tls`](/docs/agent/config/agent-config-files#tls) - By default this is false, and should be set to true on client agents to
automatically request a client TLS certificate from the server's Connect CA. automatically request a client TLS certificate from the server's Connect CA.
**Example Server Agent TLS Configuration** **Example Server Agent TLS Configuration**
@ -161,7 +161,7 @@ environment and adapt these configurations accordingly.
} }
``` ```
-> The client agent TLS configuration from above sets [`verify_incoming`](/docs/agent/options#tls_defaults_verify_incoming) -> The client agent TLS configuration from above sets [`verify_incoming`](/docs/agent/config/agent-config-files#tls_defaults_verify_incoming)
to false which assumes all incoming traffic is restricted to `localhost`. The primary benefit for this configuration to false which assumes all incoming traffic is restricted to `localhost`. The primary benefit for this configuration
would be to avoid provisioning client TLS certificates (in addition to ACL tokens) for all tools or applications would be to avoid provisioning client TLS certificates (in addition to ACL tokens) for all tools or applications
using the local Consul agent. In this case ACLs should be enabled to provide authorization and only ACL tokens would using the local Consul agent. In this case ACLs should be enabled to provide authorization and only ACL tokens would
@ -169,7 +169,7 @@ environment and adapt these configurations accordingly.
- **ACLs** - The access control list (ACL) system provides a security mechanism for Consul administrators to grant - **ACLs** - The access control list (ACL) system provides a security mechanism for Consul administrators to grant
capabilities tied to an individual human, or machine operator identity. To ultimately secure the ACL system, capabilities tied to an individual human, or machine operator identity. To ultimately secure the ACL system,
administrators should configure the [`default_policy`](/docs/agent/options#acl_default_policy) to "deny". administrators should configure the [`default_policy`](/docs/agent/config/agent-config-files#acl_default_policy) to "deny".
The [system](/docs/security/acl/acl-system) is comprised of five major components: The [system](/docs/security/acl/acl-system) is comprised of five major components:
@ -196,10 +196,10 @@ environment and adapt these configurations accordingly.
Two optional gossip encryption options enable Consul servers without gossip encryption to safely upgrade. After Two optional gossip encryption options enable Consul servers without gossip encryption to safely upgrade. After
upgrading, the verification options should be enabled, or removed to set them to their default state: upgrading, the verification options should be enabled, or removed to set them to their default state:
- [`encrypt_verify_incoming`](/docs/agent/options#encrypt_verify_incoming) - By default this is true to enforce - [`encrypt_verify_incoming`](/docs/agent/config/agent-config-files#encrypt_verify_incoming) - By default this is true to enforce
encryption on _incoming_ gossip communications. encryption on _incoming_ gossip communications.
- [`encrypt_verify_outgoing`](/docs/agent/options#encrypt_verify_outgoing) - By default this is true to enforce - [`encrypt_verify_outgoing`](/docs/agent/config/agent-config-files#encrypt_verify_outgoing) - By default this is true to enforce
encryption on _outgoing_ gossip communications. encryption on _outgoing_ gossip communications.
- **Namespaces** <EnterpriseAlert inline /> - Read and write operations should be scoped to logical namespaces to - **Namespaces** <EnterpriseAlert inline /> - Read and write operations should be scoped to logical namespaces to
@ -240,16 +240,16 @@ environment and adapt these configurations accordingly.
- **Linux Security Modules** - Use of security modules that can be directly integrated into operating systems such as - **Linux Security Modules** - Use of security modules that can be directly integrated into operating systems such as
AppArmor, SElinux, and Seccomp on Consul agent hosts. AppArmor, SElinux, and Seccomp on Consul agent hosts.
- **Customize TLS Settings** - TLS settings such as the [available cipher suites](/docs/agent/options#tls_defaults_tls_cipher_suites), - **Customize TLS Settings** - TLS settings such as the [available cipher suites](/docs/agent/config/agent-config-files#tls_defaults_tls_cipher_suites),
should be tuned to fit the needs of your environment. should be tuned to fit the needs of your environment.
- [`tls_min_version`](/docs/agent/options#tls_defaults_tls_min_version) - Used to specify the minimum TLS version to use. - [`tls_min_version`](/docs/agent/config/agent-config-files#tls_defaults_tls_min_version) - Used to specify the minimum TLS version to use.
- [`tls_cipher_suites`](/docs/agent/options#tls_defaults_tls_cipher_suites) - Used to specify which TLS cipher suites are allowed. - [`tls_cipher_suites`](/docs/agent/config/agent-config-files#tls_defaults_tls_cipher_suites) - Used to specify which TLS cipher suites are allowed.
- **Customize HTTP Response Headers** - Additional security headers, such as - **Customize HTTP Response Headers** - Additional security headers, such as
[`X-XSS-Protection`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection), can be [`X-XSS-Protection`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection), can be
[configured](/docs/agent/options#response_headers) for HTTP API responses. [configured](/docs/agent/config/agent-config-files#response_headers) for HTTP API responses.
```hcl ```hcl
http_config { http_config {
@ -262,28 +262,28 @@ environment and adapt these configurations accordingly.
- **Customize Default Limits** - Consul has a number of builtin features with default connection limits that should be - **Customize Default Limits** - Consul has a number of builtin features with default connection limits that should be
tuned to fit your environment. tuned to fit your environment.
- [`http_max_conns_per_client`](/docs/agent/options#http_max_conns_per_client) - Used to limit concurrent access from - [`http_max_conns_per_client`](/docs/agent/config/agent-config-files#http_max_conns_per_client) - Used to limit concurrent access from
a single client to the HTTP(S) endpoint on Consul agents. a single client to the HTTP(S) endpoint on Consul agents.
- [`https_handshake_timeout`](/docs/agent/options#https_handshake_timeout) - Used to timeout TLS connection for the - [`https_handshake_timeout`](/docs/agent/config/agent-config-files#https_handshake_timeout) - Used to timeout TLS connection for the
HTTP(S) endpoint for Consul agents. HTTP(S) endpoint for Consul agents.
- [`rpc_handshake_timeout`](/docs/agent/options#rpc_handshake_timeout) - Used to timeout TLS connections for the RPC - [`rpc_handshake_timeout`](/docs/agent/config/agent-config-files#rpc_handshake_timeout) - Used to timeout TLS connections for the RPC
endpoint for Consul agents. endpoint for Consul agents.
- [`rpc_max_conns_per_client`](/docs/agent/options#rpc_max_conns_per_client) - Used to limit concurrent access from a - [`rpc_max_conns_per_client`](/docs/agent/config/agent-config-files#rpc_max_conns_per_client) - Used to limit concurrent access from a
single client to the RPC endpoint on Consul agents. single client to the RPC endpoint on Consul agents.
- [`rpc_rate`](/docs/agent/options#rpc_rate) - Disabled by default, this is used to limit (requests/second) for client - [`rpc_rate`](/docs/agent/config/agent-config-files#rpc_rate) - Disabled by default, this is used to limit (requests/second) for client
agents making RPC calls to server agents. agents making RPC calls to server agents.
- [`rpc_max_burst`](/docs/agent/options#rpc_max_burst) - Used as the token bucket size for client agents making RPC - [`rpc_max_burst`](/docs/agent/config/agent-config-files#rpc_max_burst) - Used as the token bucket size for client agents making RPC
calls to server agents. calls to server agents.
- [`kv_max_value_size`](/docs/agent/options#kv_max_value_size) - Used to configure the max number of bytes in a - [`kv_max_value_size`](/docs/agent/config/agent-config-files#kv_max_value_size) - Used to configure the max number of bytes in a
key-value API request. key-value API request.
- [`txn_max_req_len`](/docs/agent/options#txn_max_req_len) - Used to configure the max number of bytes in a - [`txn_max_req_len`](/docs/agent/config/agent-config-files#txn_max_req_len) - Used to configure the max number of bytes in a
transaction API request. transaction API request.
- **Secure UI Access** - Access to Consul’s builtin UI can be secured in various ways: - **Secure UI Access** - Access to Consul’s builtin UI can be secured in various ways:
@ -303,7 +303,7 @@ environment and adapt these configurations accordingly.
[Securing Consul with Access Control Lists (ACLs)](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production), [Securing Consul with Access Control Lists (ACLs)](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production),
which includes a section on [creating ACL tokens that provide a desired level UI access](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#consul-ui-token). which includes a section on [creating ACL tokens that provide a desired level UI access](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#consul-ui-token).
- **Restrict HTTP Writes** - Using the [`allow_write_http_from`](/docs/agent/options#allow_write_http_from) - **Restrict HTTP Writes** - Using the [`allow_write_http_from`](/docs/agent/config/agent-config-files#allow_write_http_from)
configuration option to restrict write access for agent endpoints to hosts on the specified list of CIDRs. configuration option to restrict write access for agent endpoints to hosts on the specified list of CIDRs.
**Example Agent Configuration** **Example Agent Configuration**

6
website/content/docs/troubleshoot/common-errors.mdx
View File

@ -198,14 +198,14 @@ We recommend raising an issue with the CNI you're using to add support for `host
and switching back to `hostPort` eventually. and switching back to `hostPort` eventually.
[troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting [troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting
[node_name]: /docs/agent/options#node_name [node_name]: /docs/agent/config/agent-config-files#node_name
[retry_join]: /docs/agent/options#retry-join [retry_join]: /docs/agent/config/agent-config-cli#retry-join
[license]: /commands/license [license]: /commands/license
[releases]: https://releases.hashicorp.com/consul/ [releases]: https://releases.hashicorp.com/consul/
[files]: https://easyengine.io/tutorials/linux/increase-open-files-limit [files]: https://easyengine.io/tutorials/linux/increase-open-files-limit
[certificates]: https://learn.hashicorp.com/consul/advanced/day-1-operations/certificates [certificates]: https://learn.hashicorp.com/consul/advanced/day-1-operations/certificates
[systemd]: https://learn.hashicorp.com/consul/advanced/day-1-operations/deployment-guide#configure-systemd [systemd]: https://learn.hashicorp.com/consul/advanced/day-1-operations/deployment-guide#configure-systemd
[monitoring]: https://learn.hashicorp.com/consul/advanced/day-1-operations/monitoring [monitoring]: https://learn.hashicorp.com/consul/advanced/day-1-operations/monitoring
[bind]: /docs/agent/options#_bind [bind]: /docs/agent/config/agent-config-cli#_bind
[jq]: https://stedolan.github.io/jq/ [jq]: https://stedolan.github.io/jq/
[go-sockaddr]: https://godoc.org/github.com/hashicorp/go-sockaddr/template [go-sockaddr]: https://godoc.org/github.com/hashicorp/go-sockaddr/template

8
website/content/docs/troubleshoot/faq.mdx
View File

@ -62,8 +62,8 @@ messages.
This anonymous ID can be disabled. In fact, using the Checkpoint service is This anonymous ID can be disabled. In fact, using the Checkpoint service is
optional and can be disabled. optional and can be disabled.
See [`disable_anonymous_signature`](/docs/agent/options#disable_anonymous_signature) See [`disable_anonymous_signature`](/docs/agent/config/agent-config-files#disable_anonymous_signature)
and [`disable_update_check`](/docs/agent/options#disable_update_check). and [`disable_update_check`](/docs/agent/config/agent-config-files#disable_update_check).
### Q: Does Consul rely on UDP Broadcast or Multicast? ### Q: Does Consul rely on UDP Broadcast or Multicast?
@ -116,7 +116,7 @@ as well as race conditions between data updates and watch registrations.
### Q: What network ports does Consul use? ### Q: What network ports does Consul use?
The [Ports Used](/docs/agent/options#ports) section of the Configuration The [Ports Used](/docs/agent/config/agent-config-files#ports) section of the Configuration
documentation lists all ports that Consul uses. documentation lists all ports that Consul uses.
### Q: Does Consul require certain user process resource limits? ### Q: Does Consul require certain user process resource limits?
@ -143,7 +143,7 @@ of any excessive resource utilization before arbitrarily increasing the limits.
The default recommended limit on a key's value size is 512KB. This is strictly The default recommended limit on a key's value size is 512KB. This is strictly
enforced and an HTTP 413 status will be returned to any client that attempts to enforced and an HTTP 413 status will be returned to any client that attempts to
store more than that limit in a value. The limit can be increased by using the store more than that limit in a value. The limit can be increased by using the
[`kv_max_value_size`](/docs/agent/options#kv_max_value_size) configuration option. [`kv_max_value_size`](/docs/agent/config/agent-config-files#kv_max_value_size) configuration option.
It should be noted that the Consul key/value store is not designed to be used as It should be noted that the Consul key/value store is not designed to be used as
a general purpose database. See a general purpose database. See

4
website/content/docs/upgrading/instructions/general-process.mdx
View File

@ -74,7 +74,7 @@ this snapshot somewhere safe. More documentation on snapshot usage is available
- [consul.io/commands/snapshot](/commands/snapshot) - [consul.io/commands/snapshot](/commands/snapshot)
- <https://learn.hashicorp.com/tutorials/consul/backup-and-restore> - <https://learn.hashicorp.com/tutorials/consul/backup-and-restore>
**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/options#_log_level) **2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/config/agent-config-cli#_log_level)
is set to `debug`. After doing this, issue the following command on your servers to is set to `debug`. After doing this, issue the following command on your servers to
reload the configuration: reload the configuration:
@ -183,7 +183,7 @@ then the following options for further assistance are available:
When contacting Hashicorp Support, please include the following information in your ticket: When contacting Hashicorp Support, please include the following information in your ticket:
- Consul version you were upgrading FROM and TO. - Consul version you were upgrading FROM and TO.
- [Debug level logs](/docs/agent/options#_log_level) from all servers in the cluster - [Debug level logs](/docs/agent/config/agent-config-cli#_log_level) from all servers in the cluster
that you are having trouble with. These should include logs from prior to the upgrade attempt that you are having trouble with. These should include logs from prior to the upgrade attempt
up through the current time. If your logs were not set at debug level prior to the up through the current time. If your logs were not set at debug level prior to the
upgrade, please include those logs as well. Also, update your config to use debug logs, upgrade, please include those logs as well. Also, update your config to use debug logs,

8
website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx
View File

@ -20,7 +20,7 @@ Here is some documentation that may prove useful for reference during this upgra
- [ACL System in Legacy Mode](/docs/security/acl/acl-legacy) - You can find - [ACL System in Legacy Mode](/docs/security/acl/acl-legacy) - You can find
information about legacy configuration options and differences between modes here. information about legacy configuration options and differences between modes here.
- [Configuration](/docs/agent/options) - You can find more details - [Configuration](/docs/agent/config) - You can find more details
around legacy ACL and new ACL configuration options here. Legacy ACL config options around legacy ACL and new ACL configuration options here. Legacy ACL config options
will be listed as deprecates as of 1.4.0. will be listed as deprecates as of 1.4.0.
@ -51,7 +51,7 @@ Looking through these changes prior to upgrading is highly recommended.
Two very notable items are: Two very notable items are:
- 1.6.2 introduced more strict JSON decoding. Invalid JSON that was previously ignored might result in errors now (e.g., `Connect: null` in service definitions). See [[GH#6680](https://github.com/hashicorp/consul/pull/6680)]. - 1.6.2 introduced more strict JSON decoding. Invalid JSON that was previously ignored might result in errors now (e.g., `Connect: null` in service definitions). See [[GH#6680](https://github.com/hashicorp/consul/pull/6680)].
- 1.6.3 introduced the [http_max_conns_per_client](/docs/agent/options#http_max_conns_per_client) limit. This defaults to 200. Prior to this, connections per client were unbounded. [[GH#7159](https://github.com/hashicorp/consul/issues/7159)] - 1.6.3 introduced the [http_max_conns_per_client](/docs/agent/config/agent-config-files#http_max_conns_per_client) limit. This defaults to 200. Prior to this, connections per client were unbounded. [[GH#7159](https://github.com/hashicorp/consul/issues/7159)]
## Procedure ## Procedure
@ -202,8 +202,8 @@ update those now to avoid issues when moving to newer versions.
These are the changes you will need to make: These are the changes you will need to make:
- `acl_datacenter` is now named `primary_datacenter` (review our [docs](/docs/agent/options#primary_datacenter) for more info) - `acl_datacenter` is now named `primary_datacenter` (review our [docs](/docs/agent/config/agent-config-files#primary_datacenter) for more info)
- `acl_default_policy`, `acl_down_policy`, `acl_ttl`, `acl_*_token` and `enable_acl_replication` options are now specified like this (review our [docs](/docs/agent/options#acl) for more info): - `acl_default_policy`, `acl_down_policy`, `acl_ttl`, `acl_*_token` and `enable_acl_replication` options are now specified like this (review our [docs](/docs/agent/config/agent-config-files#acl) for more info):
```hcl ```hcl
acl { acl {
enabled = true/false enabled = true/false

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

@ -54,7 +54,7 @@ Due to this rename the following endpoint is also deprecated:
These config keys are now deprecated: These config keys are now deprecated:
- `audit.sink[].name` - `audit.sink[].name`
- [`dns_config.dns_prefer_namespace`](/docs/agent/options#dns_prefer_namespace) - [`dns_config.dns_prefer_namespace`](/docs/agent/config/agent-config-files#dns_prefer_namespace)
### Deprecated CLI Subcommands ### Deprecated CLI Subcommands
@ -119,8 +119,8 @@ have a license loaded from a configuration file or from their environment the sa
agents must have the license specified. Both agents can still perform automatic retrieval of their agents must have the license specified. Both agents can still perform automatic retrieval of their
license but with a few extra stipulations. First, license auto-retrieval now requires that ACLs license but with a few extra stipulations. First, license auto-retrieval now requires that ACLs
are on and that the client or snapshot agent is configured with a valid ACL token. Secondly, client are on and that the client or snapshot agent is configured with a valid ACL token. Secondly, client
agents require that either the [`start_join`](/docs/agent/options#start_join) or agents require that either the [`start_join`](/docs/agent/config/agent-config-files#start_join) or
[`retry_join`](/docs/agent/options#retry_join) configurations are set and that they resolve to server [`retry_join`](/docs/agent/config/agent-config-files#retry_join) configurations are set and that they resolve to server
agents. If those stipulations are not met, attempting to start the client or snapshot agent will agents. If those stipulations are not met, attempting to start the client or snapshot agent will
result in it immediately shutting down. result in it immediately shutting down.
@ -214,7 +214,7 @@ to Consul 1.9.0.
### Changes to Configuration Defaults ### Changes to Configuration Defaults
The [`enable_central_service_config`](/docs/agent/options#enable_central_service_config) The [`enable_central_service_config`](/docs/agent/config/agent-config-files#enable_central_service_config)
configuration now defaults to `true`. configuration now defaults to `true`.
### Changes to Intentions ### Changes to Intentions
@ -283,7 +283,7 @@ behavior:
#### Removal of Deprecated Features #### Removal of Deprecated Features
The [`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8) The [`acl_enforce_version_8`](/docs/agent/config/agent-config-files#acl_enforce_version_8)
configuration has been removed (with version 8 ACL support by being on by configuration has been removed (with version 8 ACL support by being on by
default). default).
@ -326,7 +326,7 @@ to more precisely capture the view of _active_ blocking queries.
### Vault: default `http_max_conns_per_client` too low to run Vault properly ### Vault: default `http_max_conns_per_client` too low to run Vault properly
Consul 1.7.0 introduced [limiting of connections per client](/docs/agent/options#http_max_conns_per_client). The default value Consul 1.7.0 introduced [limiting of connections per client](/docs/agent/config/agent-config-files#http_max_conns_per_client). The default value
was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.7.0, you should change the value to 200. was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.7.0, you should change the value to 200.
Starting with Consul 1.7.1 this is the new default. Starting with Consul 1.7.1 this is the new default.
@ -334,7 +334,7 @@ Starting with Consul 1.7.1 this is the new default.
### Vault: default `http_max_conns_per_client` too low to run Vault properly ### Vault: default `http_max_conns_per_client` too low to run Vault properly
Consul 1.6.3 introduced [limiting of connections per client](/docs/agent/options#http_max_conns_per_client). The default value Consul 1.6.3 introduced [limiting of connections per client](/docs/agent/config/agent-config-files#http_max_conns_per_client). The default value
was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.6.3 through 1.7.0, you should change the value to 200. was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.6.3 through 1.7.0, you should change the value to 200.
Starting with Consul 1.7.1 this is the new default. Starting with Consul 1.7.1 this is the new default.
@ -373,7 +373,7 @@ datacenter". All configuration is backwards compatible and shouldn't need to
change prior to upgrade although it's strongly recommended to migrate ACL change prior to upgrade although it's strongly recommended to migrate ACL
configuration to the new syntax soon after upgrade. This includes moving to configuration to the new syntax soon after upgrade. This includes moving to
`primary_datacenter` rather than `acl_datacenter` and `acl_*` to the new [ACL `primary_datacenter` rather than `acl_datacenter` and `acl_*` to the new [ACL
block](/docs/agent/options#acl). block](/docs/agent/config/agent-config-files#acl).
Datacenters can be upgraded in any order although secondaries will remain in Datacenters can be upgraded in any order although secondaries will remain in
[Legacy ACL mode](#legacy-acl-mode) until the primary datacenter is fully [Legacy ACL mode](#legacy-acl-mode) until the primary datacenter is fully
@ -500,11 +500,11 @@ The following previously deprecated fields and config options have been removed:
Consul 1.0.1 (and earlier versions of Consul) checked for raft snapshots every Consul 1.0.1 (and earlier versions of Consul) checked for raft snapshots every
5 seconds, and created new snapshots for every 8192 writes. These defaults cause 5 seconds, and created new snapshots for every 8192 writes. These defaults cause
constant disk IO in large busy clusters. Consul 1.1.0 increases these to larger values, constant disk IO in large busy clusters. Consul 1.1.0 increases these to larger values,
and makes them tunable via the [raft_snapshot_interval](/docs/agent/options#_raft_snapshot_interval) and and makes them tunable via the [raft_snapshot_interval](/docs/agent/config/agent-config-files#_raft_snapshot_interval) and
[raft_snapshot_threshold](/docs/agent/options#_raft_snapshot_threshold) parameters. We recommend [raft_snapshot_threshold](/docs/agent/config/agent-config-files#_raft_snapshot_threshold) parameters. We recommend
keeping the new defaults. However, operators can go back to the old defaults by changing their keeping the new defaults. However, operators can go back to the old defaults by changing their
config if they prefer more frequent snapshots. See the documentation for [raft_snapshot_interval](/docs/agent/options#_raft_snapshot_interval) config if they prefer more frequent snapshots. See the documentation for [raft_snapshot_interval](/docs/agent/config/agent-config-files#_raft_snapshot_interval)
and [raft_snapshot_threshold](/docs/agent/options#_raft_snapshot_threshold) to understand the trade-offs and [raft_snapshot_threshold](/docs/agent/config/agent-config-files#_raft_snapshot_threshold) to understand the trade-offs
when tuning these. when tuning these.
## Consul 1.0.7 ## Consul 1.0.7
@ -532,7 +532,7 @@ before proceeding.
#### Carefully Check and Remove Stale Servers During Rolling Upgrades #### Carefully Check and Remove Stale Servers During Rolling Upgrades
Consul 1.0 (and earlier versions of Consul when running with [Raft protocol Consul 1.0 (and earlier versions of Consul when running with [Raft protocol
3](/docs/agent/options#_raft_protocol) had an issue where performing 3](/docs/agent/config/agent-config-files#_raft_protocol) had an issue where performing
rolling updates of Consul servers could result in an outage from old servers rolling updates of Consul servers could result in an outage from old servers
remaining in the cluster. remaining in the cluster.
[Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) [Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations)
@ -553,7 +553,7 @@ Please be sure to read over all the details here before upgrading.
#### Raft Protocol Now Defaults to 3 #### Raft Protocol Now Defaults to 3
The [`-raft-protocol`](/docs/agent/options#_raft_protocol) default has The [`-raft-protocol`](/docs/agent/config/agent-config-cli#_raft_protocol) default has
been changed from 2 to 3, enabling all been changed from 2 to 3, enabling all
[Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) [Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations)
features by default. features by default.
@ -582,7 +582,7 @@ servers, and then slowly stand down each of the older servers in a similar
fashion. fashion.
When using Raft protocol version 3, servers are identified by their When using Raft protocol version 3, servers are identified by their
[`-node-id`](/docs/agent/options#_node_id) instead of their IP address [`-node-id`](/docs/agent/config/agent-config-cli#_node_id) instead of their IP address
when Consul makes changes to its internal Raft quorum configuration. This means when Consul makes changes to its internal Raft quorum configuration. This means
that once a cluster has been upgraded with servers all running Raft protocol that once a cluster has been upgraded with servers all running Raft protocol
version 3, it will no longer allow servers running any older Raft protocol version 3, it will no longer allow servers running any older Raft protocol
@ -597,7 +597,7 @@ to map the server to its node ID in the Raft quorum configuration.
As part of supporting the [HCL](https://github.com/hashicorp/hcl#syntax) format As part of supporting the [HCL](https://github.com/hashicorp/hcl#syntax) format
for Consul's config files, an `.hcl` or `.json` extension is required for all for Consul's config files, an `.hcl` or `.json` extension is required for all
config files loaded by Consul, even when using the config files loaded by Consul, even when using the
[`-config-file`](/docs/agent/options#_config_file) argument to specify a [`-config-file`](/docs/agent/config/agent-config-cli#_config_file) argument to specify a
file directly. file directly.
#### Service Definition Parameter Case changed #### Service Definition Parameter Case changed
@ -614,40 +614,41 @@ upgrading. Here's the complete list of removed options and their equivalents:
| Removed Option | Equivalent | | Removed Option | Equivalent |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-dc` | [`-datacenter`](/docs/agent/options#_datacenter) | | `-dc` | [`-datacenter`](/docs/agent/config/agent-config-cli#_datacenter) |
| `-retry-join-azure-tag-name` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-azure-tag-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `-retry-join-azure-tag-value` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-azure-tag-value` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `-retry-join-ec2-region` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-ec2-region` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `-retry-join-ec2-tag-key` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-ec2-tag-key` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `-retry-join-ec2-tag-value` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-ec2-tag-value` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `-retry-join-gce-credentials-file` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-gce-credentials-file` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `-retry-join-gce-project-name` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-gce-project-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `-retry-join-gce-tag-name` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-gce-tag-name` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `-retry-join-gce-zone-pattern` | [`-retry-join`](/docs/agent/options#_retry_join) | | `-retry-join-gce-zone-pattern` | [`-retry-join`](/docs/agent/config/agent-config-cli#_retry_join) |
| `addresses.rpc` | None, the RPC server for CLI commands is no longer supported. | | `addresses.rpc` | None, the RPC server for CLI commands is no longer supported. |
| `advertise_addrs` | [`ports`](/docs/agent/options#ports) with [`advertise_addr`](/docs/agent/options#advertise_addr) and/or [`advertise_addr_wan`](/docs/agent/options#advertise_addr_wan) | | `advertise_addrs` | [`ports`](/docs/agent/config/agent-config-files#ports) with [`advertise_addr`](/docs/agent/config/agent-config-files#advertise_addr) and/or [`advertise_addr_wan`](/docs/agent/config/agent-config-files#advertise_addr_wan) |
| `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](/docs/agent/options#telemetry-dogstatsd_addr) | | `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](/docs/agent/config/agent-config-files#telemetry-dogstatsd_addr) |
| `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](/docs/agent/options#telemetry-dogstatsd_tags) | | `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](/docs/agent/config/agent-config-files#telemetry-dogstatsd_tags) |
| `http_api_response_headers` | [`http_config.response_headers`](/docs/agent/options#response_headers) | | `http_api_response_headers` | [`http_config.response_headers`](/docs/agent/config/agent-config-files#response_headers) |
| `ports.rpc` | None, the RPC server for CLI commands is no longer supported. | | `ports.rpc` | None, the RPC server for CLI commands is no longer supported. |
| `recursor` | [`recursors`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/options.mdx#recursors) |
| `retry_join_azure` | [`-retry-join`](/docs/agent/options#_retry_join) | | `recursor` | [`recursors`](/docs/agent/config/agent-config-files#recursors) |
| `retry_join_ec2` | [`-retry-join`](/docs/agent/options#_retry_join) | | `retry_join_azure` | [`retry-join`](/docs/agent/config/agent-config-files#retry_join) |
| `retry_join_gce` | [`-retry-join`](/docs/agent/options#_retry_join) | | `retry_join_ec2` | [`retry-join`](/docs/agent/config/agent-config-files#retry_join) |
| `statsd_addr` | [`telemetry.statsd_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/options.mdx#telemetry-statsd_address) | | `retry_join_gce` | [`retry-join`](/docs/agent/config/agent-config-files#retry_join) |
| `statsite_addr` | [`telemetry.statsite_address`](https://github.com/hashicorp/consul/blob/main/website/pages/docs/agent/options.mdx#telemetry-statsite_address) | | `statsd_addr` | [`telemetry.statsd_address`](/docs/agent/config/agent-config-files#telemetry-statsd_address) |
| `statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/options#telemetry-metrics_prefix) | | `statsite_addr` | [`telemetry.statsite_address`](/docs/agent/config/agent-config-files#telemetry-statsite_address) |
| `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/options#telemetry-metrics_prefix) | | `statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix) |
| (service definitions) `serviceid` | [`service_id`](/docs/discovery/services) | | `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix) |
| (service definitions) `dockercontainerid` | [`docker_container_id`](/docs/discovery/services) | | (service definitions) `serviceid` | [`id`](/api-docs/agent/service#id) |
| (service definitions) `tlsskipverify` | [`tls_skip_verify`](/docs/discovery/services) | | (service definitions) `dockercontainerid` | [`docker_container_id`](/api-docs/agent/check#dockercontainerid) |
| (service definitions) `deregistercriticalserviceafter` | [`deregister_critical_service_after`](/docs/discovery/services) | | (service definitions) `tlsskipverify` | [`tls_skip_verify`](/api-docs/agent/check#tlsskipverify) |
| (service definitions) `deregistercriticalserviceafter` | [`deregister_critical_service_after`](/api-docs/agent/check#deregistercriticalserviceafter) |
#### `statsite_prefix` Renamed to `metrics_prefix` #### `statsite_prefix` Renamed to `metrics_prefix`
Since the `statsite_prefix` configuration option applied to all telemetry Since the `statsite_prefix` configuration option applied to all telemetry
providers, `statsite_prefix` was renamed to providers, `statsite_prefix` was renamed to
[`metrics_prefix`](/docs/agent/options#telemetry-metrics_prefix). [`metrics_prefix`](/docs/agent/config/agent-config-files#telemetry-metrics_prefix).
Configuration files will need to be updated when upgrading to this version of Configuration files will need to be updated when upgrading to this version of
Consul. Consul.
@ -659,8 +660,8 @@ wrongly stated that you could configure both host and port.
#### Escaping Behavior Changed for go-discover Configs #### Escaping Behavior Changed for go-discover Configs
The format for [`-retry-join`](/docs/agent/options#retry-join) and The format for [`-retry-join`](/docs/agent/config/agent-config-cli#retry-join) and
[`-retry-join-wan`](/docs/agent/options#retry-join-wan) values that use [`-retry-join-wan`](/docs/agent/config/agent-config-cli#retry-join-wan) values that use
[go-discover](https://github.com/hashicorp/go-discover) cloud auto joining has [go-discover](https://github.com/hashicorp/go-discover) cloud auto joining has
changed. Values in `key=val` sequences must no longer be URL encoded and can be changed. Values in `key=val` sequences must no longer be URL encoded and can be
provided as literals as long as they do not contain spaces, backslashes `\` or provided as literals as long as they do not contain spaces, backslashes `\` or
@ -778,7 +779,7 @@ invalid health checks would get skipped.
#### Script Checks Are Now Opt-In #### Script Checks Are Now Opt-In
A new [`enable_script_checks`](/docs/agent/options#_enable_script_checks) A new [`enable_script_checks`](/docs/agent/config/agent-config-cli#_enable_script_checks)
configuration option was added, and defaults to `false`, meaning that in order configuration option was added, and defaults to `false`, meaning that in order
to allow an agent to run health checks that execute scripts, this will need to to allow an agent to run health checks that execute scripts, this will need to
be configured and set to `true`. This provides a safer out-of-the-box be configured and set to `true`. This provides a safer out-of-the-box
@ -800,10 +801,10 @@ for more information.
Consul releases will no longer include a `web_ui.zip` file with the compiled Consul releases will no longer include a `web_ui.zip` file with the compiled
web assets. These have been built in to the Consul binary since the 0.7.x web assets. These have been built in to the Consul binary since the 0.7.x
series and can be enabled with the [`-ui`](/docs/agent/options#_ui) series and can be enabled with the [`-ui`](/docs/agent/config/agent-config-cli#_ui)
configuration option. These built-in web assets have always been identical to configuration option. These built-in web assets have always been identical to
the contents of the `web_ui.zip` file for each release. The the contents of the `web_ui.zip` file for each release. The
[`-ui-dir`](/docs/agent/options#_ui_dir) option is still available for [`-ui-dir`](/docs/agent/config/agent-config-cli#_ui_dir) option is still available for
hosting customized versions of the web assets, but the vast majority of Consul hosting customized versions of the web assets, but the vast majority of Consul
users can just use the built in web assets. users can just use the built in web assets.
@ -835,12 +836,12 @@ to the following commands:
#### Version 8 ACLs Are Now Opt-Out #### Version 8 ACLs Are Now Opt-Out
The [`acl_enforce_version_8`](/docs/agent/options#acl_enforce_version_8) The [`acl_enforce_version_8`](/docs/agent/config/agent-config-files#acl_enforce_version_8)
configuration now defaults to `true` to enable full version 8 ACL support by configuration now defaults to `true` to enable full version 8 ACL support by
default. If you are upgrading an existing cluster with ACLs enabled, you will default. If you are upgrading an existing cluster with ACLs enabled, you will
need to set this to `false` during the upgrade on **both Consul agents and need to set this to `false` during the upgrade on **both Consul agents and
Consul servers**. Version 8 ACLs were also changed so that Consul servers**. Version 8 ACLs were also changed so that
[`acl_datacenter`](/docs/agent/options#acl_datacenter) must be set on [`acl_datacenter`](/docs/agent/config/agent-config-files#acl_datacenter) must be set on
agents in order to enable the agent-side enforcement of ACLs. This makes for a agents in order to enable the agent-side enforcement of ACLs. This makes for a
smoother experience in clusters where ACLs aren't enabled at all, but where the smoother experience in clusters where ACLs aren't enabled at all, but where the
agents would have to wait to contact a Consul server before learning that. agents would have to wait to contact a Consul server before learning that.
@ -848,14 +849,14 @@ agents would have to wait to contact a Consul server before learning that.
#### Remote Exec Is Now Opt-In #### Remote Exec Is Now Opt-In
The default for The default for
[`disable_remote_exec`](/docs/agent/options#disable_remote_exec) was [`disable_remote_exec`](/docs/agent/config/agent-config-files#disable_remote_exec) was
changed to "true", so now operators need to opt-in to having agents support changed to "true", so now operators need to opt-in to having agents support
running commands remotely via [`consul exec`](/commands/exec). running commands remotely via [`consul exec`](/commands/exec).
#### Raft Protocol Version Compatibility #### Raft Protocol Version Compatibility
When upgrading to Consul 0.8.0 from a version lower than 0.7.0, users will need When upgrading to Consul 0.8.0 from a version lower than 0.7.0, users will need
to set the [`-raft-protocol`](/docs/agent/options#_raft_protocol) option to set the [`-raft-protocol`](/docs/agent/config/agent-config-cli#_raft_protocol) option
to 1 in order to maintain backwards compatibility with the old servers during to 1 in order to maintain backwards compatibility with the old servers during
the upgrade. After the servers have been migrated to version 0.8.0, the upgrade. After the servers have been migrated to version 0.8.0,
`-raft-protocol` can be moved up to 2 and the servers restarted to match the `-raft-protocol` can be moved up to 2 and the servers restarted to match the
@ -890,7 +891,7 @@ process to reap child processes.
#### DNS Resiliency Defaults #### DNS Resiliency Defaults
The default for [`max_stale`](/docs/agent/options#max_stale) has been The default for [`max_stale`](/docs/agent/config/agent-config-files#max_stale) has been
increased from 5 seconds to a near-indefinite threshold (10 years) to allow DNS increased from 5 seconds to a near-indefinite threshold (10 years) to allow DNS
queries to continue to be served in the event of a long outage with no leader. queries to continue to be served in the event of a long outage with no leader.
A new telemetry counter was added at `consul.dns.stale_queries` to track when A new telemetry counter was added at `consul.dns.stale_queries` to track when
@ -904,7 +905,7 @@ to be aware of during an upgrade are categorized below.
#### Performance Timing Defaults and Tuning #### Performance Timing Defaults and Tuning
Consul 0.7 now defaults the DNS configuration to allow for stale queries by Consul 0.7 now defaults the DNS configuration to allow for stale queries by
defaulting [`allow_stale`](/docs/agent/options#allow_stale) to true for defaulting [`allow_stale`](/docs/agent/config/agent-config-files#allow_stale) to true for
better utilization of available servers. If you want to retain the previous better utilization of available servers. If you want to retain the previous
behavior, set the following configuration: behavior, set the following configuration:
@ -917,7 +918,7 @@ behavior, set the following configuration:
``` ```
Consul also 0.7 introduced support for tuning Raft performance using a new Consul also 0.7 introduced support for tuning Raft performance using a new
[performance configuration block](/docs/agent/options#performance). Also, [performance configuration block](/docs/agent/config/agent-config-files#performance). Also,
the default Raft timing is set to a lower-performance mode suitable for the default Raft timing is set to a lower-performance mode suitable for
[minimal Consul servers](/docs/install/performance#minimum). [minimal Consul servers](/docs/install/performance#minimum).
@ -937,8 +938,8 @@ See the [Server Performance](/docs/install/performance) guide for more details.
#### Leave-Related Configuration Defaults #### Leave-Related Configuration Defaults
The default behavior of [`leave_on_terminate`](/docs/agent/options#leave_on_terminate) The default behavior of [`leave_on_terminate`](/docs/agent/config/agent-config-files#leave_on_terminate)
and [`skip_leave_on_interrupt`](/docs/agent/options#skip_leave_on_interrupt) and [`skip_leave_on_interrupt`](/docs/agent/config/agent-config-files#skip_leave_on_interrupt)
are now dependent on whether or not the agent is acting as a server or client: are now dependent on whether or not the agent is acting as a server or client:
- For servers, `leave_on_terminate` defaults to "false" and `skip_leave_on_interrupt` - For servers, `leave_on_terminate` defaults to "false" and `skip_leave_on_interrupt`
@ -977,7 +978,7 @@ using this feature.
#### WAN Address Translation in HTTP Endpoints #### WAN Address Translation in HTTP Endpoints
Consul version 0.7 added support for translating WAN addresses in certain Consul version 0.7 added support for translating WAN addresses in certain
[HTTP endpoints](/docs/agent/options#translate_wan_addrs). The servers [HTTP endpoints](/docs/agent/config/agent-config-files#translate_wan_addrs). The servers
and the agents need to be running version 0.7 or later in order to use this and the agents need to be running version 0.7 or later in order to use this
feature. feature.
@ -1059,7 +1060,7 @@ which require it:
} }
When the DNS interface is queried, the agent's When the DNS interface is queried, the agent's
[`acl_token`](/docs/agent/options#acl_token) is used, so be sure [`acl_token`](/docs/agent/config/agent-config-files#acl_token) is used, so be sure
that token has sufficient privileges to return the DNS records you that token has sufficient privileges to return the DNS records you
expect to retrieve from it. expect to retrieve from it.

2
website/content/partials/http_api_options_client.mdx
View File

@ -20,7 +20,7 @@
used instead. The scheme can also be set to HTTPS by setting the environment 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 using variable `CONSUL_HTTP_SSL=true`. This may be a unix domain socket using
`unix:///path/to/socket` if the [agent is configured to `unix:///path/to/socket` if the [agent is configured to
listen](/docs/agent/options#addresses) that way. listen](/docs/agent/config/agent-config-files#addresses) that way.
- `-tls-server-name=<value>` - The server name to use as the SNI host when - `-tls-server-name=<value>` - The server name to use as the SNI host when
connecting via TLS. This can also be specified via the `CONSUL_TLS_SERVER_NAME` connecting via TLS. This can also be specified via the `CONSUL_TLS_SERVER_NAME`