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

docs: link fixes for Envoy proxy page (#16023) 

* Link path fixes

* update

* Revert "update"

This reverts commit 6b3344481c501a2d8e1190e80977cc1bb7ae7ee1.

* Link fixes
This commit is contained in:
Jeff Boruszak 2023-01-20 11:12:18 -06:00 committed by GitHub
parent 9f0a6c50b8
commit feacfb2886
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 57 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
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.
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
@ -94,8 +94,8 @@ responsibility for correctly configuring Envoy and ensuring version support etc.
## Intention Enforcement
[Intentions] are enforced using Envoy's RBAC filters. Depending on the
configured [protocol] of the proxied service, intentions are either enforced
[Intentions](/consul/docs/connect/intentions) are enforced using Envoy's RBAC filters. Depending on the
configured [protocol](/consul/docs/connect/config-entries/service-defaults#protocol) of the proxied service, intentions are either enforced
per-connection (L4) using a network filter, or per-request (L7) using an HTTP
filter.
@ -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,12 +592,12 @@ 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]
- `envoy_extra_static_clusters_json` - Specifies one or more [Envoy clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto)
that will be appended to the array of [static
clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-clusters)
in the bootstrap config. This enables you to add custom clusters for tracing sinks,
@ -635,7 +635,7 @@ definition](/docs/connect/registration/service-registration) or
</CodeBlockConfig>
- `envoy_extra_static_listeners_json` - Similar to
`envoy_extra_static_clusters_json` but appends one or more [Envoy listeners][pb-listener] to the array of [static
`envoy_extra_static_clusters_json` but appends one or more [Envoy listeners](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/listener/v3/listener.proto) to the array of [static
listener](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-listeners) definitions.
Can be used to setup limited access that bypasses Connect mTLS or
authorization for health checks or metrics.
@ -773,23 +773,23 @@ 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
deviations from the default template may break Consul's ability to correctly
manage the proxy or enforce its security model.
- `envoy_public_listener_json` - Specifies a complete [Envoy listener][pb-listener]
- `envoy_public_listener_json` - Specifies a complete [Envoy listener](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/listener/v3/listener.proto)
to be delivered in place of the main public listener that the proxy used to
accept inbound connections. This will be used verbatim with the following
exceptions:
@ -925,7 +925,7 @@ definition](/docs/connect/registration/service-registration) or
</CodeBlockConfig>
- `envoy_local_cluster_json` - Specifies a complete [Envoy cluster][pb-cluster]
- `envoy_local_cluster_json` - Specifies a complete [Envoy cluster](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto)
to be delivered in place of the local application cluster. This allows
customization of timeouts, rate limits, load balancing strategy etc.
@ -972,17 +972,17 @@ 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.
- `envoy_listener_json` - Specifies a complete [Listener][pb-listener]
- `envoy_listener_json` - Specifies a complete [Listener](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/listener/v3/listener.proto)
to be delivered in place of the upstream listener that the proxy exposes to
the application for outbound connections. This will be used verbatim with the
following exceptions:
@ -1066,7 +1066,7 @@ warning.
```
</CodeTabs>
- `envoy_cluster_json` - Specifies a complete [Envoy cluster][pb-cluster]
- `envoy_cluster_json` - Specifies a complete [Envoy cluster](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/cluster/v3/cluster.proto)
to be delivered in place of the discovered upstream cluster. This allows
customization of timeouts, circuit breaking, rate limits, load balancing
strategy etc.
@ -1098,10 +1098,4 @@ warning.
}
}
```
</CodeTabs>
[protocol]: /docs/connect/config-entries/service-defaults#protocol
[intentions]: /docs/connect/intentions
[intentions]: /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
</CodeTabs>