diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index bbeca24a2d..f376218191 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -604,14 +604,16 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." (disabled). **We recommend using `8501`** for `https` by convention as some tooling will work automatically with this. - `grpc` ((#grpc_port)) - The gRPC API, -1 to disable. Default -1 (disabled). - **We recommend using `8502`** for `grpc` by convention as some tooling will work - 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. + **We recommend using `8502` for `grpc`** as your conventional gRPC port number, as it allows some + tools to work automatically. This parameter is set to `8502` by default when the agent runs + in `-dev` mode. The `grpc` port currently supports either plaintext or TLS traffic for + backwards-compatibility, but TLS support is deprecated and will be removed in a future + release. Refer to `grpc_tls` for more information on configuring a TLS-enabled port. - `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. + **We recommend using `8502` for `grpc_tls`** as your conventional gRPC port number, as it allows some + tools to work automatically. `grpc_tls` is always guaranteed to be encrypted. Both `grpc` and `grpc_tls` + can be configured at the same time, but they may not utilize the same port number. If both `grpc` and + `grpc_tls` are defined, then `grpc` will always be plaintext. This field was added in Consul 1.14. - `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. diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index ab288d09d0..193e6593ec 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -20,25 +20,21 @@ upgrade flow. ##### Changes to gRPC TLS configuration -**Configuration changes should be made** if using sidecar proxies or gateways -in conjunction with any of the following: +**Make configuration changes** if using sidecar proxies or gateways that include any of the following configuration file values: 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 +1. [`auto_encrypt`](/docs/agent/config/config-files#auto_encrypt) - Encrypts gRPC in Consul 1.13 and prior +1. [`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. +Prior to Consul 1.14, it was possible to encrypt communication between Consul and Envoy over `ports.grpc` using these settings. -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`. +Consul 1.14 introduces [`ports.grpc_tls`](/docs/agent/config/config-files#grpc_tls_port), a new configuration +for encrypting communication over gRPC. The existing [`ports.grpc`](/docs/agent/config/config- +files#grpc_port) configuration **will stop supporting encryption in a future release**. As of version 1.14, +`ports.grpc_tls` is the recommended configuration to encrypt gRPC traffic. 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. - +If you already use gRPC encryption, change the existing `ports.grpc` to `ports.grpc_tls` in your configuration to ensure compatibility with future releases. ## Consul 1.13.x