Improve grpc_tls wording in docs. (#14608)

Improve grpc_tls wording in docs.

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
This commit is contained in:
Derek Menteer 2022-09-14 15:25:39 -05:00 committed by GitHub
parent d0416f593c
commit 2721fc9a6e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 18 additions and 20 deletions

View File

@ -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.

View File

@ -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