New "Mesh Gateways for Peered Clusters" page

website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx

@@ -0,0 +1,51 @@
+---
+layout: docs
+page_title: Service-to-service Traffic Across Peered Clusters
+description: >-
+  This topic describes how to configure mesh gateways to route a service's data to upstreams
+  in clusters that have a peering connection.
+---
+
+# Service-to-service Traffic Across Peered Clusters
+
+~> **Cluster peering is currently in beta**: Functionality associated with cluster peering is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support.
+
+Mesh gateways are required for you to route service mesh traffic between different Consul clusters. Clusters can reside in different clouds or runtime environments where general interconnectivity between all services in all clusters is not feasible.
+
+Unlike mesh gateways for datacenters and partitions, mesh gateways for cluster peering decrypts data to HTTP services within the mTLS session. Data must be decrypted in order to apply dynamic routing rules configured in the destination cluster.
+
+## Prerequisites
+
+To configure mesh gateways for cluster peering, make sure your Consul environment meets the following requirements:
+
+- Consul version 1.13.0 or newer.
+- A local Consul agent is required to manage mesh gateway configuration.
+- [Enable Consul service mesh](/docs/agent/config/config-files#connect-parameters) in all clusters.
+- Use [Envoy proxies](/docs/connect/proxies/envoy). Envoy is the only proxy with mesh gateway capabilities in Consul.
+
+## Configuration
+
+Configure the following settings to register and use the mesh gateway as a service in Consul.
+
+### Gateway registration
+
+- Specify `mesh-gateway` in the `kind` field to register the gateway with Consul.
+- Define the `Proxy.Config` settings using opaque parameters compatible with your proxy. For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information.
+
+Alternatively, you can also use the CLI to spin up and register a gateway in Consul. For additional information, refer to the [`consul connect envoy` command](/commands/connect/envoy#mesh-gateways).
+
+### Sidecar registration
+
+- Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and peer. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_peer` must be configured to enable cross-cluster traffic. The `proxy.upstream/destination_namespace` configuration is only necessary if the destination service is in a non-default namespace.
+
+### Service exporting
+
+- Configure the `exported-services` configuration entry to enable Consul to export services contained in a cluster to one or more additional clusters. For additional information, refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services).
+
+### ACL configuration
+
+- If ACLs are enabled, you must add a token granting `service:write` for the gateway's service name and `service:read` for all services in the Enterprise admin partition or OSS datacenter to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services.
+
+### Modes
+
+In the current release, modes are not configurable for mesh gateways that connect peered clusters. All proxies connected to the gateway behave in [remote mode](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#remote). 

website/data/docs-nav-data.json

@@ -263,6 +263,10 @@
               {
                 "title": "Enabling Service-to-service Traffic Across Admin Partitions",
                 "path": "connect/gateways/mesh-gateway/service-to-service-traffic-partitions"
+              },
+              {
+                "title": "Enabling Service-to-service Traffic Across Peered Clusters",
+                "path": "connect/gateways/mesh-gateway/service-to-service-traffic-peers"
               }
             ]
           },