diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index 59705542ae..9206db9557 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -24,9 +24,9 @@ Consul can configure Envoy sidecars to proxy traffic over the following protocol On Consul 1.5.0 and older, Envoy proxies can only proxy TCP traffic at L4. -Some [L7 features](/docs/connect/l7-traffic) can be configured using [configuration entries](/docs/agent/config-entries). You can add [custom Envoy configurations](#advanced-configuration) to the [proxy service definition](/docs/connect/registration/service-registration) to use Envoy features that are not currently exposed through configuration entries. Adding custom Envoy configurations to the service definition is an interim solution that enables you to use the more powerful features of Envoy. +Some [L7 features](/consul/docs/connect/l7-traffic) can be configured using [configuration entries](/consul/docs/agent/config-entries). You can add [custom Envoy configurations](#advanced-configuration) to the [proxy service definition](/consul/docs/connect/registration/service-registration) to use Envoy features that are not currently exposed through configuration entries. Adding custom Envoy configurations to the service definition is an interim solution that enables you to use the more powerful features of Envoy. -~> **Note:** When using Envoy with Consul and not using the [`consul connect envoy` command](/commands/connect/envoy) +~> **Note:** When using Envoy with Consul and not using the [`consul connect envoy` command](/consul/commands/connect/envoy) Envoy must be run with the `--max-obj-name-len` option set to `256` or greater for Envoy versions prior to 1.11.0. ## Supported Versions @@ -78,7 +78,7 @@ The dynamic configuration Consul Connect provides to each Envoy instance include - Service-discovery results for upstreams to enable each sidecar proxy to load-balance outgoing connections. - L7 configuration including timeouts and protocol-specific options. -- Configuration to [expose specific HTTP paths](/docs/connect/registration/service-registration#expose-paths-configuration-reference). +- Configuration to [expose specific HTTP paths](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference). For more information on the parts of the Envoy proxy runtime configuration that are currently controllable via Consul Connect see [Dynamic @@ -104,17 +104,17 @@ per-connection (L4) using an `ext_authz` network filter. ## Fetching Certificates -Envoy will use the [`CONSUL_HTTP_TOKEN`](/commands#consul_http_token) and [`CONSUL_HTTP_ADDR`](/commands#consul_http_addr) environment variables to contact Consul to fetch certificates if the following conditions are met: +Envoy will use the [`CONSUL_HTTP_TOKEN`](/consul/commands#consul_http_token) and [`CONSUL_HTTP_ADDR`](/consul/commands#consul_http_addr) environment variables to contact Consul to fetch certificates if the following conditions are met: - The `CONSUL_HTTP_TOKEN` environment variable contains a Consul ACL token. - The Consul ACL token has the necessary permissions to read configuration for that service. If TLS is enabled on Consul, you will also need to add the following environment variables _prior_ to starting Envoy: -- [`CONSUL_CACERT`](/commands#consul_cacert) -- [`CONSUL_CLIENT_CERT`](/commands#consul_client_cert) -- [`CONSUL_CLIENT_KEY`](/commands#consul_client_key) -- [`CONSUL_HTTP_SSL`](/commands#consul_http_ssl) +- [`CONSUL_CACERT`](/consul/commands#consul_cacert) +- [`CONSUL_CLIENT_CERT`](/consul/commands#consul_client_cert) +- [`CONSUL_CLIENT_KEY`](//consulcommands#consul_client_key) +- [`CONSUL_HTTP_SSL`](/consul/commands#consul_http_ssl) ## Bootstrap Configuration @@ -122,27 +122,27 @@ Envoy requires an initial bootstrap configuration file. You can either create th ### Generate the bootstrap file on the Consul CLI -Connect to a local Consul client agent and run the [`consul connect envoy` command](/commands/connect/envoy) to create the Envoy bootstrap configuration. The command either outputs the bootstrap configuration directly to stdout or generates the configuration and issues an `exec` command to the Envoy binary as a convenience wrapper. For more information about using `exec` to bootstrap Envoy, refer to [Exec Security Details](/consul/commands/connect/envoy#exec-security-details). +Connect to a local Consul client agent and run the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration. The command either outputs the bootstrap configuration directly to stdout or generates the configuration and issues an `exec` command to the Envoy binary as a convenience wrapper. For more information about using `exec` to bootstrap Envoy, refer to [Exec Security Details](/consul/commands/connect/envoy#exec-security-details). ### Generate the bootstrap file from Consul Dataplane -Consul Dataplane automatically configures and manages an Envoy process. Consul Dataplane generates the Envoy bootstrap configuration file prior to starting Envoy. To configure how Consul Dataplane starts Envoy, refer to the [Consul Dataplane CLI reference](/docs/connect/dataplane/consul-dataplane). +Consul Dataplane automatically configures and manages an Envoy process. Consul Dataplane generates the Envoy bootstrap configuration file prior to starting Envoy. To configure how Consul Dataplane starts Envoy, refer to the [Consul Dataplane CLI reference](/consul/docs/connect/dataplane/consul-dataplane). ### Control bootstrap configuration from proxy configuration Consul service mesh can control some parts of the bootstrap configuration by specifying Envoy proxy configuration options. Add the following configuration items to the [global `proxy-defaults` configuration -entry](/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` -field of a [proxy service definition](/docs/connect/registration/service-registration). When +entry](/consul/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` +field of a [proxy service definition](/consul/docs/connect/registration/service-registration). When connected to a Consul client agent, you can place the configuration in the `proxy.config` field of -the [`sidecar_service`](/docs/connect/registration/sidecar-service) block. +the [`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. - `envoy_statsd_url` - A URL in the form `udp://ip:port` identifying a UDP StatsD listener that Envoy should deliver metrics to. For example, this may be `udp://127.0.0.1:8125` if every host has a local StatsD listener. In this case users can configure this property once in the [global `proxy-defaults` - configuration entry](/docs/connect/config-entries/proxy-defaults) for convenience. Currently, TCP is not supported. + configuration entry](/consul/docs/connect/config-entries/proxy-defaults) for convenience. Currently, TCP is not supported. ~> **Note:** currently the url **must use an ip address** not a dns name due to the way Envoy is setup for StatsD. @@ -156,7 +156,7 @@ the [`sidecar_service`](/docs/connect/registration/sidecar-service) block. pod in a Kubernetes cluster to learn of a pod-specific IP address for StatsD when the Envoy instance is bootstrapped while still allowing global configuration of all proxies to use StatsD in the [global `proxy-defaults` - configuration entry](/docs/connect/config-entries/proxy-defaults). The env + configuration entry](/consul/docs/connect/config-entries/proxy-defaults). The env variable must contain a full valid URL value as specified above and nothing else. - `envoy_dogstatsd_url` - The same as `envoy_statsd_url` with the following @@ -190,7 +190,7 @@ The [Advanced Configuration](#advanced-configuration) section describes addition ### Bootstrap Envoy on Windows VMs -> Complete the [Connect Services on Windows Workloads to Consul Service Mesh tutorial](https://learn.hashicorp.com/tutorials/consul/consul-windows-workloads?utm_source=docs) to learn how to deploy Consul and use its service mesh on Windows VMs. +> Complete the [Connect Services on Windows Workloads to Consul Service Mesh tutorial](/consu/tutorials/consul-windows-workloads?utm_source=docs) to learn how to deploy Consul and use its service mesh on Windows VMs. If you are running Consul on a Windows VM, attempting to bootstrap Envoy with the `consul connect envoy` command returns the following output: @@ -254,13 +254,13 @@ $ envoy -c bootstrap.json Consul automatically generates Envoy's dynamic configuration based on its knowledge of the cluster. Users may specify default configuration options for a service through the available fields in the [`service-defaults` configuration -entry](/docs/connect/config-entries/service-defaults). Consul will use this +entry](/consul/docs/connect/config-entries/service-defaults). Consul will use this information to configure appropriate proxy settings for that service's proxies and also for the upstream listeners used by the service. One example is how users can define a service's protocol in the `Protocol` field of [`service-defaults` configuration -entry](/docs/connect/config-entries/service-defaults). Agents with -[`enable_central_service_config`](/docs/agent/config/config-files#enable_central_service_config) +entry](/consul/docs/connect/config-entries/service-defaults). Agents with +[`enable_central_service_config`](/consul/docs/agent/config/config-files#enable_central_service_config) 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 represents and use this to configure its main public listener. It will also @@ -269,18 +269,18 @@ automatically configure its upstream listeners appropriately too as below. This automated discovery results in Consul auto-populating the `proxy.config` and `proxy.upstreams[*].config` fields of the [proxy service -definition](/docs/connect/registration/service-registration) that is +definition](/consul/docs/connect/registration/service-registration) that is actually registered. To learn about other options that can be configured centrally see the -[Configuration Entries](/docs/agent/config-entries) docs. +[Configuration Entries](/consul/docs/agent/config-entries) docs. ### Proxy Config Options These fields may also be overridden explicitly in `proxy.config` of the [proxy service -definition](/docs/connect/registration/service-registration), or defined in +definition](/consul/docs/connect/registration/service-registration), or defined in the [global `proxy-defaults` configuration -entry](/docs/connect/config-entries/proxy-defaults) to act as +entry](/consul/docs/connect/config-entries/proxy-defaults) to act as defaults that are inherited by all services. - `protocol` - The protocol the service speaks. Connect's Envoy integration @@ -307,12 +307,12 @@ defaults that are inherited by all services. metrics with `gRPC-status` trailer codes. ~> **Note:** The protocol of a service should ideally be configured via the - [`protocol`](/docs/connect/config-entries/service-defaults#protocol) + [`protocol`](/consul/docs/connect/config-entries/service-defaults#protocol) field of a - [`service-defaults`](/docs/connect/config-entries/service-defaults) + [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config entry for the service. Configuring it in a proxy config will not fully enable some [L7 - features](/docs/connect/l7-traffic). + features](/consul/docs/connect/l7-traffic). It is supported here for backwards compatibility with Consul versions prior to 1.6.0. - `bind_address` - Override the address Envoy's public listener binds to. By @@ -350,19 +350,19 @@ defaults that are inherited by all services. The following configuration items may be overridden directly in the `proxy.upstreams[].config` field of a [proxy service -definition](/docs/connect/registration/service-registration) or -[`sidecar_service`](/docs/connect/registration/sidecar-service) block. +definition](/consul/docs/connect/registration/service-registration) or +[`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. - `protocol` - Same as above in main config but affects the listener setup for the upstream. ~> **Note:** The protocol of a service should ideally be configured via the - [`protocol`](/docs/connect/config-entries/service-defaults#protocol) + [`protocol`](/consul/docs/connect/config-entries/service-defaults#protocol) field of a - [`service-defaults`](/docs/connect/config-entries/service-defaults) + [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config entry for the upstream destination service. Configuring it in a proxy upstream config will not fully enable some [L7 - features](/docs/connect/l7-traffic). + features](/consul/docs/connect/l7-traffic). It is supported here for backwards compatibility with Consul versions prior to 1.6.0. - `connect_timeout_ms` - The number of milliseconds to allow when making upstream @@ -371,9 +371,9 @@ definition](/docs/connect/registration/service-registration) or ~> **Note:** The connection timeout for a service should ideally be configured via the - [`connect_timeout`](/docs/connect/config-entries/service-resolver#connecttimeout) + [`connect_timeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of a - [`service-resolver`](/docs/connect/config-entries/service-resolver) + [`service-resolver`](/consul/docs/connect/config-entries/service-resolver) config entry for the upstream destination service. Configuring it in a proxy upstream config will override any values defined in config entries. It is supported here for backwards compatibility with Consul versions prior to 1.6.0. @@ -420,9 +420,9 @@ definition](/docs/connect/registration/service-registration) or ### Gateway Options These fields may also be overridden explicitly in the [proxy service -definition](/docs/connect/registration/service-registration), or defined in +definition](/consul/docs/connect/registration/service-registration), or defined in the [global `proxy-defaults` configuration -entry](/docs/connect/config-entries/proxy-defaults) to act as +entry](/consul/docs/connect/config-entries/proxy-defaults) to act as defaults that are inherited by all services. Prior to 1.8.0 these settings were specific to Mesh Gateways. The deprecated @@ -432,7 +432,7 @@ will continue to be supported. - `connect_timeout_ms` - The number of milliseconds to allow when making upstream connections before timing out. Defaults to 5000 (5 seconds). If the upstream service has the configuration option - [`connect_timeout_ms`](/docs/connect/config-entries/service-resolver#connecttimeout) + [`connect_timeout_ms`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) set for the `service-resolver`, that timeout value will take precedence over this gateway option. @@ -592,10 +592,10 @@ EOF Users may add the following configuration items to the [global `proxy-defaults` configuration -entry](/docs/connect/config-entries/proxy-defaults) or +entry](/consul/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` field of a [proxy service -definition](/docs/connect/registration/service-registration) or -[`sidecar_service`](/docs/connect/registration/sidecar-service) block. +definition](/consul/docs/connect/registration/service-registration) or +[`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. - `envoy_extra_static_clusters_json` - Specifies one or more [Envoy clusters][pb-cluster] that will be appended to the array of [static @@ -773,16 +773,16 @@ definition](/docs/connect/registration/service-registration) or Users may add the following configuration items to the [global `proxy-defaults` configuration -entry](/docs/connect/config-entries/proxy-defaults) or +entry](/consul/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` field of a [proxy service -definition](/docs/connect/registration/service-registration) or -[`sidecar_service`](/docs/connect/registration/sidecar-service) block. +definition](/consul/docs/connect/registration/service-registration) or +[`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. - `envoy_bootstrap_json_tpl` - Specifies a template in Go template syntax that is used in place of [the default template](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L129) when generating bootstrap via [`consul connect envoy` - command](/commands/connect/envoy). The variables that are available + command](/consul/commands/connect/envoy). The variables that are available to be interpolated are [documented here](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L5). This offers complete control of the proxy's bootstrap although major @@ -972,13 +972,13 @@ definition](/docs/connect/registration/service-registration) or The following configuration items may be overridden directly in the `proxy.upstreams[].config` field of a [proxy service -definition](/docs/connect/registration/service-registration) or -[`sidecar_service`](/docs/connect/registration/sidecar-service) block. +definition](/consul/docs/connect/registration/service-registration) or +[`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block. ~> **Note:** - When a -[`service-router`](/docs/connect/config-entries/service-router), -[`service-splitter`](/docs/connect/config-entries/service-splitter), or -[`service-resolver`](/docs/connect/config-entries/service-resolver) config +[`service-router`](/consul/docs/connect/config-entries/service-router), +[`service-splitter`](/consul/docs/connect/config-entries/service-splitter), or +[`service-resolver`](/consul/docs/connect/config-entries/service-resolver) config entry exists for a service the below escape hatches are ignored and will log a warning. @@ -1100,8 +1100,8 @@ warning. ``` -[protocol]: /docs/connect/config-entries/service-defaults#protocol -[intentions]: /docs/connect/intentions -[intentions]: /docs/connect/intentions +[protocol]: /consul/docs/connect/config-entries/service-defaults#protocol +[intentions]: /consul/docs/connect/intentions +[intentions]: /consul/docs/connect/intentions [pb-cluster]: https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto [pb-listener]: https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/listener/v3/listener.proto