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

Merge pull request #10812 from hashicorp/docs-envoy-proxy-breaks-when-enabling-tls 

docs: adding env var info
This commit is contained in:
trujillo-adam 2021-08-09 15:58:37 -07:00 committed by GitHub
parent 00b0633bda 79c25af139
commit 001a108f26
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 59 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -12,17 +12,18 @@ optionally exposing a gRPC service on the local agent that serves [Envoy's xDS
configuration configuration
API](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-docs/xds_protocol). API](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-docs/xds_protocol).
Consul can configure Envoy sidecars to proxy http/1.1, http2, or gRPC traffic at Consul can configure Envoy sidecars to proxy traffic over the following protocols:
L7 or any other tcp-based protocol at L4. Prior to Consul 1.5.0 Envoy proxies
could only proxy tcp at L4.
Configuration of some [L7 features](/docs/connect/l7-traffic-management) | Protocol | Service network support |
is possible via [configuration entries](/docs/agent/config-entries). If | ----------------------- | ----------------------- |
you wish to use an Envoy feature not currently exposed through these config | HTTP/1.1 | L7 |
entries as an interim solution, you can add [custom Envoy | HTTP2 | L7 |
configuration](#advanced-configuration) in the [proxy service | gRPC | L7 |
definition](/docs/connect/registration/service-registration) allowing you | All TCP-based protocols | L4 |
to use the more powerful features of Envoy.
On Consul 1.5.0 and older, Envoy proxies can only proxy TCP traffic at L4.
Some [L7 features](/docs/connect/l7-traffic-management) 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.
~> **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](/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.
@ -32,26 +33,19 @@ Envoy must be run with the `--max-obj-name-len` option set to `256` or greater f
Consul's Envoy support was added in version 1.3.0. The following table shows Consul's Envoy support was added in version 1.3.0. The following table shows
compatible Envoy versions. compatible Envoy versions.
| Consul Version | Compatible Envoy Versions | | Consul Version | Compatible Envoy Versions |
| ------------------- | -------------------------------- | | ------------------- | ------------------------------------------------------ |
| 1.10.x | 1.18.3, 1.17.3, 1.16.4, 1.15.5 | | 1.10.x | 1.18.3, 1.17.3, 1.16.4, 1.15.5 |
| 1.9.x | 1.16.4, 1.15.5, 1.14.7‡, 1.13.7‡ | | 1.9.x | 1.16.4, 1.15.5, 1.14.7<sup>1</sup>, 1.13.7<sup>1</sup> |
| 1.8.x | 1.14.7, 1.13.7, 1.12.7, 1.11.2 | | 1.8.x | 1.14.7, 1.13.7, 1.12.7, 1.11.2 |
| 1.7.x | 1.13.7, 1.12.7, 1.11.2, 1.10.0\* | | 1.7.x | 1.13.7, 1.12.7, 1.11.2, 1.10.0<sup>2</sup> |
| 1.6.x, 1.5.3, 1.5.2 | 1.11.1, 1.10.0, 1.9.1, 1.8.0† | | 1.6.x, 1.5.3, 1.5.2 | 1.11.1, 1.10.0, 1.9.1, 1.8.0<sup>3</sup> |
| 1.5.1, 1.5.0 | 1.9.1, 1.8.0† | | 1.5.1, 1.5.0 | 1.9.1, 1.8.0<sup>3</sup> |
| 1.4.x, 1.3.x | 1.9.1, 1.8.0†, 1.7.0† | | 1.4.x, 1.3.x | 1.9.1, 1.8.0†, 1.7.0<sup>3</sup> |
~> ‡ To ensure that intention enforcement is updated as quickly as possible 1. Use Consul 1.9.0+ with Envoy 1.15.0+ to ensure that intention enforcement is updated as quickly as possible after any changes. [Additional information](https://github.com/envoyproxy/envoy/pull/10662).
after any changes, it is advised to run Consul 1.9.0+ with Envoy 1.15.0+ due to a 1. Envoy 1.10.0 requires setting [`-envoy-version`](/commands/connect/envoy#envoy-version) in the `consul connect envoy` command. This was introduced in Consul 1.7.0.
[listener update improvement](https://github.com/envoyproxy/envoy/pull/10662).<br/><br/> 1. Envoy 1.9.1 and older are vulnerable to [CVE-2019-9900](https://github.com/envoyproxy/envoy/issues/6434) and [CVE-2019-9901](https://github.com/envoyproxy/envoy/issues/6435). Both issues are related to parsing HTTP requests and only affect Consul Connect users if they have configured HTTP routing rules. We recommend that you use the most recent supported Envoy for your version of Consul when possible.
† Envoy versions lower than 1.9.1 are vulnerable to
[CVE-2019-9900](https://github.com/envoyproxy/envoy/issues/6434) and
[CVE-2019-9901](https://github.com/envoyproxy/envoy/issues/6435). Both are
related to HTTP request parsing and so only affect Consul Connect users if they
have configured HTTP routing rules. Still, we recommend that you use the most
recent supported Envoy for your Consul version where possible.<br/><br/> \* Envoy 1.10.0 requires setting
[`-envoy-version`](/commands/connect/envoy#envoy-version) in the `consul connect envoy` command. This was introduced in Consul 1.7.0.
## Getting Started ## Getting Started
@ -61,7 +55,7 @@ Envoy with Connect](https://learn.hashicorp.com/tutorials/consul/service-mesh-wi
## Configuration ## Configuration
Envoy proxies require two types of configuration: an initial _bootstrap Envoy proxies require two types of configuration: an initial _bootstrap
configuration_ and dynamic configuration that is discovered from a "management configuration_ and a _dynamic configuration_ that is discovered from a "management
server", in this case Consul. server", in this case Consul.
The bootstrap configuration at a minimum needs to configure the proxy with an The bootstrap configuration at a minimum needs to configure the proxy with an
@ -93,28 +87,41 @@ responsibility for correctly configuring Envoy and ensuring version support etc.
## Intention Enforcement ## Intention Enforcement
[Intentions] are enforced using Envoy's RBAC filters. Depending upon the [Intentions] are enforced using Envoy's RBAC filters. Depending on the
configured [protocol] of the proxied service these are either enforced configured [protocol] of the proxied service, intentions are either enforced
per-connection (L4) using a network filter or per-request (L7) using an HTTP per-connection (L4) using a network filter, or per-request (L7) using an HTTP
filter. filter.
-> **Note:** Prior to Consul 1.9.0 intentions were exclusively enforced -> **Note:** Prior to Consul 1.9.0 intentions were exclusively enforced
per-connection (L4) using an `ext_authz` network filter. 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:
- 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)
## Bootstrap Configuration ## Bootstrap Configuration
Envoy requires an initial bootstrap configuration file. The easiest way to Envoy requires an initial bootstrap configuration file. The easiest way to
create this is using the [`consul connect envoy` create this is using the [`consul connect envoy`
command](/commands/connect/envoy). The command can either output the command](/commands/connect/envoy). The command can either output the
bootstrap configuration directly to stdout or can generate it and then `exec` bootstrap configuration directly to stdout, or generate the configuration and issue an `exec` command
the Envoy binary as a convenience wrapper. to the Envoy binary as a convenience wrapper.
Because some Envoy configuration options like metrics and tracing sinks can only be Because some Envoy configuration options, such as metrics and tracing sinks, can only be
specified via the bootstrap configuration, Connect as of Consul 1.5.0 adds specified via the bootstrap configuration, Connect as of Consul 1.5.0 adds
the ability to control some parts of the bootstrap config via proxy the ability to control some parts of the bootstrap config via proxy configuration options.
configuration options.
Users can add the following configuration items to the [global `proxy-defaults` 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 configuration entry](/docs/connect/config-entries/proxy-defaults) or override them directly in the `proxy.config` field
of a [proxy service of a [proxy service
definition](/docs/connect/registration/service-registration) or definition](/docs/connect/registration/service-registration) or
@ -168,9 +175,7 @@ definition](/docs/connect/registration/service-registration) or
- `envoy_stats_flush_interval` - Configures Envoy's - `envoy_stats_flush_interval` - Configures Envoy's
[`stats_flush_interval`](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-stats-flush-interval). [`stats_flush_interval`](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-stats-flush-interval).
There are more possibilities available in the [Advanced The [Advanced Configuration](#advanced-configuration) section describes additional configurations that allow incremental or complete control over the bootstrap configuration generated.
Configuration](#advanced-configuration) section that allow incremental or
complete control over the bootstrap configuration generated.
## Dynamic Configuration ## Dynamic Configuration
@ -525,8 +530,8 @@ definition](/docs/connect/registration/service-registration) or
overridden by the Connect TLS certificates and validation context. This overridden by the Connect TLS certificates and validation context. This
means there is no way to override Connect's mutual TLS for the public means there is no way to override Connect's mutual TLS for the public
listener. listener.
- Every `FilterChain` will have the `envoy.filters.{network|http}.rbac` filter - Every `FilterChain` will have the `envoy.filters.{network|http}.rbac` filter
prepended to the filters array to ensure that all inbound connections are prepended to the filters array to ensure that all inbound connections are
authorized by Connect. Before Consul 1.9.0 `envoy.ext_authz` was inserted instead. authorized by Connect. Before Consul 1.9.0 `envoy.ext_authz` was inserted instead.
- `envoy_local_cluster_json` - Specifies a complete [Envoy cluster][pb-cluster] - `envoy_local_cluster_json` - Specifies a complete [Envoy cluster][pb-cluster]

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

@ -161,19 +161,26 @@ systems, such as init, systemd, supervisord, etc. If deployed within a
cluster scheduler (Kubernetes, Nomad), proxies should run as a sidecar container in the cluster scheduler (Kubernetes, Nomad), proxies should run as a sidecar container in the
same namespace. same namespace.
Proxies should use the [`CONSUL_HTTP_TOKEN`](/commands#consul_http_token) and Proxies will use the [`CONSUL_HTTP_TOKEN`](/commands#consul_http_token) and
[`CONSUL_HTTP_ADDR`](/commands#consul_http_addr) environment variables to [`CONSUL_HTTP_ADDR`](/commands#consul_http_addr) environment variables to
contact Consul and fetch certificates. This occurs if the `CONSUL_HTTP_TOKEN` contact Consul and fetch certificates. This occurs if the `CONSUL_HTTP_TOKEN`
environment variable contains a Consul ACL that has the necessary permissions environment variable contains a Consul ACL token that has the necessary permissions
to read configuration for that service. If you use the Go [`api` package], then to read configurations for that service. If you use the Go [`api` package], then
the environment variables will be read and the client configured for you the environment variables will be read and the client configured for you
automatically. automatically.
If TLS is enabled on Consul, you will also need to add the following environment variables _prior_ to starting the proxy:
- [`CONSUL_CACERT`](/commands#consul_cacert)
- [`CONSUL_CLIENT_CERT`](/commands#consul_client_cert)
- [`CONSUL_CLIENT_KEY`](/commands#consul_client_key)
The proxy service ID comes from the user. See [`consul connect envoy`](/commands/connect/envoy#examples) for an example. You can use the `-proxy-id` flag to specify the ID of the proxy service you have already registered with the local agent. The proxy service ID comes from the user. See [`consul connect envoy`](/commands/connect/envoy#examples) for an example. You can use the `-proxy-id` flag to specify the ID of the proxy service you have already registered with the local agent.
Alternatively, you can start the service using the `-sidecar-for=<service>` option. This option queries Consul for a proxy that is registered as a sidecar for the specified `<service>`. If exactly one service associated with the proxy is returned, the ID will be used to start the proxy. Your controller only needs to accept `-proxy-id` as an argument; the Consul CLI will resolve the Alternatively, you can start the service using the `-sidecar-for=<service>` option. This option queries Consul for a proxy that is registered as a sidecar for the specified `<service>`. If exactly one service associated with the proxy is returned, the ID will be used to start the proxy. Your controller only needs to accept `-proxy-id` as an argument; the Consul CLI will resolve the
ID for the name specified in `-sidecar-for` flag. ID for the name specified in `-sidecar-for` flag.
[`/v1/agent/connect/ca/leaf/`]: /api/agent/connect#service-leaf-certificate [`/v1/agent/connect/ca/leaf/`]: /api/agent/connect#service-leaf-certificate
[`/v1/agent/connect/ca/roots`]: /api/agent/connect#certificate-authority-ca-roots [`/v1/agent/connect/ca/roots`]: /api/agent/connect#certificate-authority-ca-roots
[`/v1/health/connect/:service_id`]: /api/health#list-nodes-for-connect-capable-service [`/v1/health/connect/:service_id`]: /api/health#list-nodes-for-connect-capable-service