From ce99ccd390b559079aaa6b9767cf8dc68dd90e55 Mon Sep 17 00:00:00 2001 From: Derek Menteer Date: Tue, 23 Aug 2022 12:11:56 -0500 Subject: [PATCH] Add documentation and changelog entry. --- .changelog/14294.txt | 6 +++++ .../docs/agent/config/config-files.mdx | 6 ++++- .../docs/upgrading/upgrade-specific.mdx | 26 +++++++++++++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 .changelog/14294.txt diff --git a/.changelog/14294.txt b/.changelog/14294.txt new file mode 100644 index 0000000000..7fcb497b1e --- /dev/null +++ b/.changelog/14294.txt @@ -0,0 +1,6 @@ +```release-note:breaking-change +config: Add new `ports.grpc_tls` configuration option. +Introduce a new port to better separate TLS config from the existing `ports.grpc` config. +The new `ports.grpc_tls` only supports TLS encrypted communication. +The existing `ports.grpc` currently supports both plain-text and tls communication, but tls support will be removed in a future release. +``` diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index 2631378731..bbeca24a2d 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -608,6 +608,10 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." automatically with this. This is set to `8502` by default when the agent runs in `-dev` mode. Currently gRPC is only used to expose Envoy xDS API to Envoy proxies. + - `grpc_tls` ((#grpc_tls_port)) - The gRPC API with TLS connections, -1 to disable. Default -1 (disabled). + **We recommend using `8502`** for `grpc_tls` by convention as some tooling will work + automatically with this. Usually only one of the `grpc_tls` or `grpc` ports should be defined. + Currently gRPC is only used to expose Envoy xDS API to Envoy proxies. - `serf_lan` ((#serf_lan_port)) - The Serf LAN port. Default 8301. TCP and UDP. Equivalent to the [`-serf-lan-port` command line flag](/docs/agent/config/cli-flags#_serf_lan_port). - `serf_wan` ((#serf_wan_port)) - The Serf WAN port. Default 8302. @@ -2003,7 +2007,7 @@ specially crafted certificate signed by the CA can be used to gain full access t interface. - `grpc` ((#tls_grpc)) Provides settings for the gRPC/xDS interface. To enable - the gRPC interface you must define a port via [`ports.grpc`](#grpc_port). + the gRPC interface you must define a port via [`ports.grpc_tls`](#grpc_tls_port). - `ca_file` ((#tls_grpc_ca_file)) Overrides [`tls.defaults.ca_file`](#tls_defaults_ca_file). diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index 2732ffe4f5..ab288d09d0 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -14,6 +14,32 @@ provided for their upgrades as a result of new features or changed behavior. This page is used to document those details separately from the standard upgrade flow. +## Consul 1.14.x + +### Service Mesh Compatibility + +##### Changes to gRPC TLS configuration + +**Configuration changes should be made** if using sidecar proxies or gateways +in conjunction with any of the following: +1. [`ports.https`](/docs/agent/config/config-files#https_port) - Encrypts gRPC in Consul 1.12 and prior +2. [`auto_encrypt`](/docs/agent/config/config-files#auto_encrypt) - Encrypts gRPC in Consul 1.13 and prior +3. [`auto_config`](/docs/agent/config/config-files#auto_config) - Encrypts gRPC in Consul 1.13 and prior + +Prior to Consul 1.14, it was possible for communication between Consul and Envoy over `ports.grpc` +to be encrypted by one of these features. + +In Consul 1.14, a new [`ports.grpc_tls`](/docs/agent/config/config-files#grpc_tls_port) configuration +is introduced. The existing [`ports.grpc`](/docs/agent/config/config-files#grpc_port) configuration +**will stop supporting encryption in a future release**. Now, the recommended way to encrypt gRPC +traffic is only via `ports.grpc_tls`. + +For most environments, the Envoy communication to Consul is loop-back only and does not benefit from encryption. + +If you would like to continue utilizing encryption for gRPC, change the existing `ports.grpc` to `ports.grpc_tls` in +your configuration during the upgrade to ensure compatibility with future releases. + + ## Consul 1.13.x ### Service Mesh Compatibility