From 1872f0a665b0fe576432ebd4e2cb2d18d07b068c Mon Sep 17 00:00:00 2001
From: "R.B. Boyer" <4903+rboyer@users.noreply.github.com>
Date: Thu, 10 Jun 2021 10:59:54 -0500
Subject: [PATCH] docs: update envoy docs for changes related to xDS v2->v3 and
SoTW->Incremental (#10166)
Fixes #10098
---
.../content/docs/connect/proxies/envoy.mdx | 80 +++++++++++--------
.../docs/upgrading/upgrade-specific.mdx | 69 +++++++++++++++-
2 files changed, 112 insertions(+), 37 deletions(-)
diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx
index 9b2a2ec240..2072b23aaa 100644
--- a/website/content/docs/connect/proxies/envoy.mdx
+++ b/website/content/docs/connect/proxies/envoy.mdx
@@ -10,7 +10,7 @@ Consul Connect has first class support for using
[Envoy](https://www.envoyproxy.io) as a proxy. Consul configures Envoy by
optionally exposing a gRPC service on the local agent that serves [Envoy's xDS
configuration
-API](https://www.envoyproxy.io/docs/envoy/latest/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
L7 or any other tcp-based protocol at L4. Prior to Consul 1.5.0 Envoy proxies
@@ -43,7 +43,7 @@ compatible Envoy versions.
| 1.4.x, 1.3.x | 1.9.1, 1.8.0†, 1.7.0† |
~> ‡ To ensure that intention enforcement is updated as quickly as possible
-after any changes, it is advised to run Consul 1.9.0 with Envoy 1.15.0+ due to a
+after any changes, it is advised to run Consul 1.9.0+ with Envoy 1.15.0+ due to a
[listener update improvement](https://github.com/envoyproxy/envoy/pull/10662).
† Envoy versions lower than 1.9.1 are vulnerable to
[CVE-2019-9900](https://github.com/envoyproxy/envoy/issues/6434) and
@@ -166,7 +166,7 @@ definition](/docs/connect/registration/service-registration) or
all metrics produced by the proxy.
- `envoy_stats_flush_interval` - Configures Envoy's
- [`stats_flush_interval`](https://www.envoyproxy.io/docs/envoy/v1.10.0/api-v2/config/bootstrap/v2/bootstrap.proto#envoy-api-field-config-bootstrap-v2-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
Configuration](#advanced-configuration) section that allow incremental or
@@ -224,7 +224,7 @@ defaults that are inherited by all services.
- `grpc` - gRPC is a common RPC protocol based on http2. In addition to the
http2 support above, Envoy listeners will be configured with a
[gRPC bridge
- filter](https://www.envoyproxy.io/docs/envoy/v1.10.0/configuration/http_filters/grpc_http1_bridge_filter#config-http-filters-grpc-bridge)
+ filter](https://www.envoyproxy.io/docs/envoy/v1.17.2/configuration/http/http_filters/grpc_http1_bridge_filter)
that translates HTTP/1.1 calls into gRPC, and instruments
metrics with `gRPC-status` trailer codes.
@@ -343,7 +343,7 @@ will continue to be supported.
- `envoy_dns_discovery_type` - Determines how Envoy will resolve hostnames. Defaults to `LOGICAL_DNS`.
Must be one of `STRICT_DNS` or `LOGICAL_DNS`. Details for each type are available in
- the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.14.1/intro/arch_overview/upstream/service_discovery).
+ the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.17.2/intro/arch_overview/upstream/service_discovery).
This option applies to terminating gateways that route to services
addressed by a hostname, such as a managed databased. It also applies to mesh gateways,
such as when gateways in other Consul datacenters are behind a load balancer that is addressed by a hostname.
@@ -381,20 +381,21 @@ noted.
The JSON supplied may describe a protobuf `types.Any` message with an `@type`
field set to the appropriate type (for example
-`type.googleapis.com/envoy.api.v2.Listener`), or it may be the direct encoding
-with no `@type` field.
+`type.googleapis.com/envoy.config.listener.v3.Listener`).
For example, given a tracing config:
```json
-"tracing": {
+{
"http": {
- "name": "envoy.zipkin",
- "config": {
- "collector_cluster": "zipkin",
- "collector_endpoint": "/api/v1/spans",
- "shared_span_context": false
- }
+ "name": "envoy.tracers.zipkin",
+ "typedConfig": {
+ "@type": "type.googleapis.com/envoy.config.trace.v3.ZipkinConfig",
+ "collector_cluster": "zipkin",
+ "collector_endpoint_version": "HTTP_JSON",
+ "collector_endpoint": "/api/v1/spans",
+ "shared_span_context": false
+ }
}
}
```
@@ -407,7 +408,7 @@ and then use that as the value for `envoy_tracing_json`:
"kind": "proxy-defaults",
"name": "global",
"config": {
- "envoy_tracing_json": "{\"http\":{\"name\":\"envoy.zipkin\",\"config\":{\"collector_cluster\":\"zipkin\",\"collector_endpoint\":\"/api/v1/spans\",\"shared_span_context\":false}}}"
+ "envoy_tracing_json": "{\"http\":{\"name\":\"envoy.tracers.zipkin\",\"typedConfig\":{\"@type\":\"type.googleapis.com/envoy.config.trace.v3.ZipkinConfig\",\"collector_cluster\":\"zipkin\",\"collector_endpoint_version\":\"HTTP_JSON\",\"collector_endpoint\":\"/api/v1/spans\",\"shared_span_context\":false}}}\n"
}
}
```
@@ -421,9 +422,11 @@ Config {
envoy_tracing_json = <
+## Consul 1.10.0
+
+### Licensing Changes
Consul Enterprise 1.10 has removed temporary licensing capabilities from the binaries
found on https://releases.hashicorp.com. Servers will no longer load a license previously
@@ -33,7 +35,7 @@ agents require that either the [`start_join`](/docs/agent/opts#start_join) or
agents. If those stipulations are not met, attempting to start the client or snapshot agent will
result in it immediately shutting down.
-### Migration
+#### Migration
Prior to upgrading Consul Enterprise to v1.10 you should ensure the license is set in all the right places.
In general following these steps should be all thats necessary to ensure a smooth upgrade.
@@ -46,6 +48,69 @@ In general following these steps should be all thats necessary to ensure a smoot
4. If ACLs are not in use then repeat step 2 for all snapshot agents.
5. Now proceed with the [standard upgrade procedure](/docs/upgrading#standard-upgrades).
+### Envoy xDS Protocol Upgrades
+
+Consul versions 1.9 and earlier exposed an xDS server for use by
+[Envoy](https://www.envoyproxy.io) proxies using the v2 ["State of the
+World"](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-docs/xds_protocol#variants-of-the-xds-transport-protocol)
+protocol variant.
+
+Consul 1.10.0 adds support for the v3
+[Incremental](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-docs/xds_protocol#incremental-xds)
+protocol variant as the preferred way of conversing with Envoy. Both protocol
+variants are supported in this Consul version to facilitate upgrading Consul
+and Envoy in a stairstep order to avoid downtime.
+
+In a future version of Consul the v2 State of the World protocol support will
+be removed.
+
+| Protocol | Version | Compatible Envoy Versions | Compatible Consul Versions |
+| ------------------ | ------- | ------------------------- | -------------------------- |
+| Incremental | v3 | 1.18.x, 1.17.x | 1.10.x |
+| State of the World | v2 | 1.16.x and older | 1.10.x and older |
+
+#### Escape Hatches
+
+Any [escape hatches](/docs/connect/proxies/envoy#advanced-configuration) that
+are defined will likely need to be switched from using xDS v2 to xDS v3
+structures. Mostly this involves migrating off of deprecated (and now removed)
+fields and switching untyped config to [typed config](https://www.envoyproxy.io/docs/envoy/v1.17.2/configuration/overview/extension)
+with `@type` attributes set appropriately.
+
+xDS v3 syntax has been [supported since Envoy
+1.13.0](https://www.envoyproxy.io/docs/envoy/v1.13.0/api-v3/api) so this could
+be done on most earlier versions of Consul+Envoy in advance of the Consul
+1.10.0 upgrade.
+
+As an example, here's a Zipkin integration
+[before](https://github.com/hashicorp/consul/blob/v1.9.5/test/integration/connect/envoy/case-zipkin/service_s2.hcl)
+and [after](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c6a55cf88fa2fc/test/integration/connect/envoy/case-zipkin/service_s2.hcl)
+
+#### Stairstep Upgrade Path
+
+1. Upgrade Envoy sidecars to the latest version of Envoy that is
+ [supported](/docs/connect/proxies/envoy#supported-versions) by the currently
+ running version of Consul as well as Consul 1.10.0.
+
+1. Determine if you are using the [escape hatch](/docs/connect/proxies/envoy#advanced-configuration)
+ feature. If so, rewrite the escape hatch to use the xDS v3 syntax and update
+ the service registration to reflect the updated escape hatch configuration
+ by re-registering. This should purge v2 elements from any configs.
+
+1. Perform a normal upgrade of both Consul servers and clients to 1.10.0. At
+ this point the existing Envoy instances will continue to speak the v2 State
+ of the World protocol to the new Consul instances without issue.
+
+1. Once a Consul client is upgraded, use an updated CLI binary to re-bootstrap
+ and restart Envoy using [`consul connect envoy`](/commands/connect/envoy).
+ This will ensure it switches over to the v3 Incremental xDS protocol.
+
+ Depending upon how you have chosen to run Envoy this is either one step
+ (`consul connect envoy`) or two steps (`consul connect envoy -bootstrap`
+ followed by running Envoy directly).
+
+1. (Optionally) upgrade Envoy to the latest version supported in Consul 1.10.0.
+
## Consul 1.9.0
### Changes to Raft Protocol Support