docs: add 1.13 upgrade considerations

Adds guidance when upgrading a Consul service mesh deployment to 1.13 and:
- using auto-encrypt or auto-config; or
- the HTTPS port is not enabled on Consul agents

website/content/docs/agent/config/config-files.mdx

@@ -2082,7 +2082,7 @@ specially crafted certificate signed by the CA can be used to gain full access t
 ### Deprecated Options ((#tls_deprecated_options))
 
 The following options were deprecated in Consul 1.12, please use the
-[`tls`](#tls) stanza instead.
+[`tls`](#tls-1) stanza instead.
 
 - `ca_file` See: [`tls.defaults.ca_file`](#tls_defaults_ca_file).
 

website/content/docs/upgrading/instructions/index.mdx

@@ -31,6 +31,9 @@ we recommend reviewing the changelog for versions between the one you are on and
 one you are upgrading to at each step to familiarize yourself with changes.
 
 Select your _currently installed_ release series:
+- 1.12.x: work upwards from [1.13 upgrade notes](/docs/upgrading/upgrade-specific#consul-1-13-x)
+- 1.11.x: work upwards from [1.12 upgrade notes](/docs/upgrading/upgrade-specific#consul-1-12-0)
+- 1.10.x: work upwards from [1.11 upgrade notes](/docs/upgrading/upgrade-specific#consul-1-11-0)
 - [1.9.x](/docs/upgrading/instructions/upgrade-to-1-10-x)
 - [1.8.x](/docs/upgrading/instructions/upgrade-to-1-10-x)
 - [1.7.x](/docs/upgrading/instructions/upgrade-to-1-8-x)

website/content/docs/upgrading/upgrade-specific.mdx

@@ -18,8 +18,15 @@ upgrade flow.
 
 ### Service Mesh Compatibility
 
-Existing Consul deployments using service mesh (i.e., containing any registered 
+Before upgrading existing Consul deployments using service mesh to Consul 1.13.x,
-Connect proxies) should upgrade to **at least Consul 1.13.1**.
+review the following guidances relevant to your deployment:
+- [All service mesh deployments](#all-service-mesh-deployments)
+- [Service mesh deployments using auto-encrypt or auto-config](#service-mesh-deployments-using-auto-encrypt-or-auto-config)
+- [Service mesh deployments without the HTTPS port enabled on Consul agents](#service-mesh-deployments-without-the-https-port-enabled-on-consul-agents)
+
+#### All service mesh deployments
+
+Upgrade to **Consul version 1.13.1 or later**.
 
 Consul 1.13.0 contains a bug that prevents Consul server agents from restoring 
 saved state on startup if the state
@@ -29,17 +36,117 @@ saved state on startup if the state
 
 This bug is fixed in Consul versions 1.13.1 and newer.
 
-### gRPC TLS
+#### Service mesh deployments using auto-encrypt or auto-config
 
-In prior Consul versions if HTTPS was enabled for the client API and exposed
+**Do not upgrade to Consul 1.13 yet** if using
-via `ports { https = NUMBER }` then the same TLS material was used to encrypt
+[auto-encrypt](/docs/agent/config/config-files#auto_encrypt) or
-the gRPC port used for xDS. Now this is decoupled and activating TLS on the
+[auto-config](/docs/agent/config/config-files#auto_config).
-gRPC endpoint is controlled solely with the gRPC section of the new 
-[`tls` stanza](/docs/agent/config/config-files#tls-configuration-reference).
 
-If you have not yet switched to the new `tls` stanza and were NOT using HTTPS
+In Consul 1.13, auto-encrypt and auto-config both cause Consul
-for the API then updating to Consul 1.13 will activate TLS for gRPC since the
+to require TLS for gRPC communication with Envoy proxies.
-deprecated TLS settings are used as defaults.
+In environments where Envoy proxies are not already configured
+to use TLS for gRPC, upgrading Consul 1.13 will cause
+Envoy proxies to disconnect from the control plane (Consul agents).
+
+The underlying cause is the same as discussed in
+[deployments without the HTTPS port enabled on Consul agents](#service-mesh-deployments-without-the-https-port-enabled-on-consul-agents).
+However, when using auto-encrypt or auto-config,
+the problem **cannot** currently be avoided by 
+[modifying the agent's TLS configuration](#modify-the-consul-agent-s-tls-configuration)
+because auto-encrypt and auto-config automatically set
+interface-generic TLS configuration in a manner similar to
+[`tls.defaults`](/docs/agent/config/config-files#tls_defaults).
+We are working to address this problem in an upcoming 1.13 patch release.
+
+#### Service mesh deployments without the HTTPS port enabled on Consul agents ((#grpc-tls))
+
+If the HTTPS port is not enabled
+([`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port))
+on a pre-1.13 Consul agent,
+**[modify the agent's TLS configuration before upgrading](#modify-the-consul-agent-s-tls-configuration)**
+to avoid Envoy proxies disconnecting from the control plane (Consul agents).
+Envoy proxies include service mesh sidecars and gateways.
+
+##### Changes to gRPC and HTTP interface configuration
+
+If a Consul agent's HTTP API is exposed externally,
+enabling HTTPS (TLS encryption for HTTP) is important.
+
+The gRPC interface is used for xDS communication between Consul and
+Envoy proxies when using Consul service mesh.
+A Consul agent's gRPC traffic is often loopback-only,
+which TLS encryption is not important for.
+
+Prior to Consul 1.13, if [`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port)
+was configured, TLS was enabled for both HTTP *and* gRPC.
+This was inconvenient for deployments that
+needed TLS for HTTP, but not for gRPC.
+Enabling HTTPS also required launching Envoy proxies
+with the necessary TLS material for xDS communication
+with its Consul agent via TLS over gRPC.
+
+Consul 1.13 addresses this inconvenience by fully decoupling the TLS configuration for HTTP and gRPC interfaces.
+TLS for gRPC is no longer enabled by setting
+[`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port).
+TLS configuration for gRPC is now determined exclusively by:
+
+1. [`tls.grpc`](/docs/agent/config/config-files#tls_grpc), which overrides
+1. [`tls.defaults`](/docs/agent/config/config-files#tls_defaults), which overrides
+1. [Deprecated TLS options](/docs/agent/config/config-files#tls_deprecated_options) such as
+   [`ca_file`](/docs/agent/config/config-files#ca_file-4),
+   [`cert_file`](/docs/agent/config/config-files#cert_file-4), and
+   [`key_file`](/docs/agent/config/config-files#key_file-4).
+
+This decoupling has a side effect that requires a
+[TLS configuration change](#modify-the-consul-agent-s-tls-configuration)
+for pre-1.13 agents without the HTTPS port enabled.
+Without a TLS configuration change,
+Consul 1.13 agents may now expect gRPC *with* TLS,
+causing communication to fail with Envoy proxies
+that continue to use gRPC *without* TLS.
+
+##### Modify the Consul agent's TLS configuration
+
+If [`tls.grpc`](/docs/agent/config/config-files#tls_grpc),
+[`tls.defaults`](/docs/agent/config/config-files#tls_defaults),
+or the [deprecated TLS options](/docs/agent/config/config-files#tls_deprecated_options)
+define TLS material in their
+`ca_file`, `ca_path`, `cert_file`, or `key_file` fields,
+TLS for gRPC will be enabled in Consul 1.13, even if
+[`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port)
+is not set.
+
+This will cause Envoy proxies to disconnect from the control plane
+after upgrading to Consul 1.13 if associated pre-1.13 Consul agents
+have **not** set
+[`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port).
+To avoid this problem, make the following agent configuration changes:
+
+1. Remove TLS material from the Consul agents'
+   interface-generic TLS configuration options:
+   [`tls.defaults`](/docs/agent/config/config-files#tls_grpc) and
+   [deprecated TLS options](/docs/agent/config/config-files#tls_deprecated_options)
+1. Reapply TLS material to the non-gRPC interfaces that need it with the
+   interface-specific TLS configuration stanzas
+   [introduced in Consul 1.12](/docs/upgrading/upgrade-specific#tls-configuration):
+   [`tls.https`](/docs/agent/config/config-files#tls_https) and
+   [`tls.internal_rpc`](/docs/agent/config/config-files#tls_internal_rpc).
+
+   If upgrading directly from pre-1.12 Consul,
+   the above configuration change cannot be made before upgrading.
+   Therefore, consider upgrading agents to Consul 1.12 before upgrading to 1.13.
+
+If pre-1.13 Consul agents have set
+[`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port),
+this configuration change is not required to upgrade.
+That setting means the pre-1.13 Consul agent requires TLS for gRPC *already*,
+and will continue to do so after upgrading to 1.13.
+If your pre-1.13 service mesh is working, you have already
+configured your Envoy proxies to use TLS for gRPC when bootstrapping Envoy
+via [`consul connect envoy`](/commands/connect/envoy),
+such as with flags or environment variables like
+[`-ca-file`](/commands/connect/envoy#ca-file) and
+[`CONSUL_CACERT`](/commands#consul_cacert).
 
 ### 1.9 Telemetry Compatibility