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

Link path fixes

pull/16023/head
boruszak 2023-01-20 09:13:19 -06:00
parent a1e2a4f8d6
commit 9ffd2063ba
1 changed files with 51 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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. 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. 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 ## 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 - Service-discovery results for upstreams to enable each sidecar proxy to load-balance
outgoing connections. outgoing connections.
- L7 configuration including timeouts and protocol-specific options. - 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 For more information on the parts of the Envoy proxy runtime configuration
that are currently controllable via Consul Connect see [Dynamic that are currently controllable via Consul Connect see [Dynamic
@ -104,17 +104,17 @@ per-connection (L4) using an `ext_authz` network filter.
## Fetching Certificates ## 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_HTTP_TOKEN` environment variable contains a Consul ACL token.
- The Consul ACL token has the necessary permissions to read configuration for that service. - 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: 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_CACERT`](/consul/commands#consul_cacert)
- [`CONSUL_CLIENT_CERT`](/commands#consul_client_cert) - [`CONSUL_CLIENT_CERT`](/consul/commands#consul_client_cert)
- [`CONSUL_CLIENT_KEY`](/commands#consul_client_key) - [`CONSUL_CLIENT_KEY`](//consulcommands#consul_client_key)
- [`CONSUL_HTTP_SSL`](/commands#consul_http_ssl) - [`CONSUL_HTTP_SSL`](/consul/commands#consul_http_ssl)
## Bootstrap Configuration ## 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 ### 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 ### 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 ### Control bootstrap configuration from proxy configuration
Consul service mesh can control some parts of the bootstrap configuration by specifying Envoy proxy configuration options. 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 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` 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). When 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 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 - `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 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 `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` 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 ~> **Note:** currently the url **must use an ip address** not a dns name due
to the way Envoy is setup for StatsD. 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 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 when the Envoy instance is bootstrapped while still allowing global
configuration of all proxies to use StatsD in the [global `proxy-defaults` 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. 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 - `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 ### 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: 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 Consul automatically generates Envoy's dynamic configuration based on its
knowledge of the cluster. Users may specify default configuration options for knowledge of the cluster. Users may specify default configuration options for
a service through the available fields in the [`service-defaults` configuration 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 information to configure appropriate proxy settings for that service's proxies
and also for the upstream listeners used by the service. 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 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 entry](/consul/docs/connect/config-entries/service-defaults). Agents with
[`enable_central_service_config`](/docs/agent/config/config-files#enable_central_service_config) [`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 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
@ -269,18 +269,18 @@ automatically configure its upstream listeners appropriately too as below.
This automated discovery results in Consul auto-populating the `proxy.config` This automated discovery results in Consul auto-populating the `proxy.config`
and `proxy.upstreams[*].config` fields of the [proxy service 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. actually registered.
To learn about other options that can be configured centrally see the 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 ### Proxy Config Options
These fields may also be overridden explicitly in `proxy.config` of the [proxy service 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 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. defaults that are inherited by all services.
- `protocol` - The protocol the service speaks. Connect's Envoy integration - `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. metrics with `gRPC-status` trailer codes.
~> **Note:** The protocol of a service should ideally be configured via the ~> **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 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 config entry for the service. Configuring it in a
proxy config will not fully enable some [L7 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. 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 - `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 The following configuration items may be overridden directly in the
`proxy.upstreams[].config` field of a [proxy service `proxy.upstreams[].config` field of a [proxy service
definition](/docs/connect/registration/service-registration) or definition](/consul/docs/connect/registration/service-registration) or
[`sidecar_service`](/docs/connect/registration/sidecar-service) block. [`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block.
- `protocol` - Same as above in main config but affects the listener setup for - `protocol` - Same as above in main config but affects the listener setup for
the upstream. the upstream.
~> **Note:** The protocol of a service should ideally be configured via the ~> **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 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 config entry for the upstream destination service. Configuring it in a
proxy upstream config will not fully enable some [L7 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. 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 - `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 ~> **Note:** The connection timeout for a service should ideally be
configured via the 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 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 config entry for the upstream destination service. Configuring it in a
proxy upstream config will override any values defined in config entries. 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. 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 ### Gateway Options
These fields may also be overridden explicitly in the [proxy service 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 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. defaults that are inherited by all services.
Prior to 1.8.0 these settings were specific to Mesh Gateways. The deprecated 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 - `connect_timeout_ms` - The number of milliseconds to allow when making upstream
connections before timing out. Defaults to 5000 (5 seconds). If the upstream connections before timing out. Defaults to 5000 (5 seconds). If the upstream
service has the configuration option 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 set for the `service-resolver`, that timeout value will take precedence over
this gateway option. this gateway option.
@ -592,10 +592,10 @@ EOF
Users may add the following configuration items to the [global `proxy-defaults` Users may add the following configuration items to the [global `proxy-defaults`
configuration 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 override them directly in the `proxy.config` field of a [proxy service
definition](/docs/connect/registration/service-registration) or definition](/consul/docs/connect/registration/service-registration) or
[`sidecar_service`](/docs/connect/registration/sidecar-service) block. [`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block.
- `envoy_extra_static_clusters_json` - Specifies one or more [Envoy clusters][pb-cluster] - `envoy_extra_static_clusters_json` - Specifies one or more [Envoy clusters][pb-cluster]
that will be appended to the array of [static 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` Users may add the following configuration items to the [global `proxy-defaults`
configuration 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 override them directly in the `proxy.config` field of a [proxy service
definition](/docs/connect/registration/service-registration) or definition](/consul/docs/connect/registration/service-registration) or
[`sidecar_service`](/docs/connect/registration/sidecar-service) block. [`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block.
- `envoy_bootstrap_json_tpl` - Specifies a template in Go template syntax that - `envoy_bootstrap_json_tpl` - Specifies a template in Go template syntax that
is used in place of [the default is used in place of [the default
template](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L129) template](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L129)
when generating bootstrap via [`consul connect envoy` 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 to be interpolated are [documented
here](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/command/connect/envoy/bootstrap_tpl.go#L5). 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 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 The following configuration items may be overridden directly in the
`proxy.upstreams[].config` field of a [proxy service `proxy.upstreams[].config` field of a [proxy service
definition](/docs/connect/registration/service-registration) or definition](/consul/docs/connect/registration/service-registration) or
[`sidecar_service`](/docs/connect/registration/sidecar-service) block. [`sidecar_service`](/consul/docs/connect/registration/sidecar-service) block.
~> **Note:** - When a ~> **Note:** - When a
[`service-router`](/docs/connect/config-entries/service-router), [`service-router`](/consul/docs/connect/config-entries/service-router),
[`service-splitter`](/docs/connect/config-entries/service-splitter), or [`service-splitter`](/consul/docs/connect/config-entries/service-splitter), or
[`service-resolver`](/docs/connect/config-entries/service-resolver) config [`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 entry exists for a service the below escape hatches are ignored and will log a
warning. warning.
@ -1100,8 +1100,8 @@ warning.
``` ```
</CodeTabs> </CodeTabs>
[protocol]: /docs/connect/config-entries/service-defaults#protocol [protocol]: /consul/docs/connect/config-entries/service-defaults#protocol
[intentions]: /docs/connect/intentions [intentions]: /consul/docs/connect/intentions
[intentions]: /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-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 [pb-listener]: https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/listener/v3/listener.proto