hashicorp · hashi-derek · Nov 14, 2022 · Nov 14, 2022
@@ -635,7 +635,7 @@ service definition keys for compatibility with the config file format.
 - `Kind` `(string: "")` - The kind of service. Defaults to "" which is a
   typical Consul service. This value may also be "connect-proxy" for
   [Connect](/docs/connect) proxies representing another service,
-  "mesh-gateway" for instances of a [mesh gateway](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters),
+  "mesh-gateway" for instances of a [mesh gateway](/docs/connect/gateways/mesh-gateway#connect-proxy-configuration),
   "terminating-gateway" for instances of a [terminating gateway](/docs/connect/gateways/terminating-gateway),
   or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/gateways/ingress-gateway).
 

@@ -93,7 +93,7 @@ The table below shows this endpoint's support for
   parameter.
 
 - `OverrideMeshGateway` `(MeshGatewayConfig: <optional>)` - Overrides the final
-  [mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#connect-proxy-configuration)
+  [mesh gateway configuration](/docs/connect/gateways/mesh-gateway#connect-proxy-configuration)
   for this any service resolved in the compiled chain.
 
   This value comes from either the [proxy

@@ -344,7 +344,7 @@ spec:
       name: 'MeshGateway',
       type: 'MeshGatewayConfig: <optional>',
       description: `Controls the default
-      [mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#connect-proxy-configuration)
+      [mesh gateway configuration](/docs/connect/gateways/mesh-gateway#connect-proxy-configuration)
       for all proxies. Added in v1.6.0.`,
       children: [
         {

@@ -444,7 +444,7 @@ represents a location outside the Consul cluster. They can be dialed directly wh
               name: 'MeshGateway',
               type: 'MeshGatewayConfig: <optional>',
               description: `Controls the default
-                [mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#connect-proxy-configuration)
+                [mesh gateway configuration](/docs/connect/gateways/mesh-gateway#connect-proxy-configuration)
                 for this upstream.`,
               children: [
                 {
@@ -595,7 +595,7 @@ represents a location outside the Consul cluster. They can be dialed directly wh
               name: 'MeshGateway',
               type: 'MeshGatewayConfig: <optional>',
               description: `Controls the default
-                  [mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#connect-proxy-configuration)
+                  [mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters#connect-proxy-configuration)
                   for this upstream.`,
               children: [
                 {
@@ -753,7 +753,7 @@ represents a location outside the Consul cluster. They can be dialed directly wh
       name: 'MeshGateway',
       type: 'MeshGatewayConfig: <optional>',
       description: `Controls the default
-      [mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#connect-proxy-configuration)
+      [mesh gateway configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters#connect-proxy-configuration)
       for this service. Added in v1.6.0.`,
       children: [
         {

@@ -19,13 +19,15 @@ in different clouds or runtime environments where general interconnectivity betw
 isn't feasible. One scenario where this is useful is when connecting networks with overlapping IP address space.
 
 These gateways operate by sniffing the SNI header out of the mTLS connection and then routing the connection to the
-appropriate destination based on the server name requested. The data within the mTLS session is not decrypted by
-the Gateway.
+appropriate destination based on the server name requested. 
 
 As of Consul 1.8.0, mesh gateways can also forward gossip and RPC traffic between Consul servers.
 This is enabled by [WAN federation via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways).
 
-For more information about mesh gateways, review the [complete documentation](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters)
+As of Consul 1.14.0, mesh gateways can route both data-plane (service-to-service) and control-plane (consul-to-consul) traffic for peered clusters. 
+See [Mesh Gateways for Peering Control Plane Traffic](/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways)
+
+For more information about mesh gateways, review the [complete documentation](/docs/connect/gateways/mesh-gateway)
 and the [mesh gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways).
 
 ![Mesh Gateway Architecture](/img/mesh-gateways.png)

@@ -23,13 +23,15 @@ Mesh gateways enable service mesh traffic to be routed between different Consul
 in different clouds or runtime environments where general interconnectivity between all services in all datacenters
 isn't feasible.
 
-They operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested. The gateway does not decrypt the data within the mTLS session.
+They operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested.
 
 Mesh gateways enable the following scenarios:
 
 * **Federate multiple datacenters across a WAN**. Since Consul 1.8.0, mesh gateways can forward gossip and RPC traffic between Consul servers. See [WAN federation via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) for additional information.
-- **Service-to-service communication across datacenters**. Refer to [Enabling Service-to-service Traffic Across Datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters) for additional information.
+- **Service-to-service communication across WAN-federated datacenters**. Refer to [Enabling Service-to-service Traffic Across Datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) for additional information.
 - **Service-to-service communication across admin partitions**. Since Consul 1.11.0, you can create administrative boundaries for single Consul deployments called "admin partitions". You can use mesh gateways to facilitate cross-partition communication. Refer to [Enabling Service-to-service Traffic Across Admin Partitions](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions) for additional information.
+- **Bridge multiple datacenters using Cluster Peering**. Since Consul 1.14.0, mesh gateways can be used to route peering control-plane traffic between peered Consul Servers. See [Mesh Gateways for Peering Control Plane Traffic](/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) for more information.
+- **Service-to-service communication across peered datacenters**. Refer to [Mesh Gateways between Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers) for more information.
 
 -> **Mesh gateway tutorial**: Follow the [mesh gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways) to learn concepts associated with mesh gateways.
 

@@ -0,0 +1,256 @@
+---
+layout: docs
+page_title: Mesh Gateways
+description: >-
+  Mesh gateways are specialized proxies that route data between services that cannot communicate directly. Learn how mesh gateways are used in different Consul configurations.
+---
+
+# Mesh Gateways
+
+Mesh gateways enable service mesh traffic to be routed between different Consul datacenters.
+Datacenters can reside in different clouds or runtime environments where general interconnectivity between all services in all datacenters isn't feasible.
+
+## Prerequisites
+
+Mesh gateways can be used with any of the following Consul configrations for managing separate datacenters or partitions.
+
+1. WAN Federation
+  * [Mesh gateways can be used to route service-to-service traffic between datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters)
+  * [Mesh gateways can be used to route all WAN traffic, including from Consul servers](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways)
+2. Cluster Peering
+  * [Mesh gateways can be used to route service-to-service traffic between datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers)
+  * [Mesh gateways can be used to route control-plane traffic from Consul servers](/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways)
+3. Admin Partitions
+  * [Mesh gateways can be used to route service-to-service traffic between admin partitions in the same Consul datacenter](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions)
+
+### Consul
+
+Review the [specific guide](#prerequisites) for your use case to determined the required version of Consul.
+
+### Network
+
+* General network connectivity to all services within its local Consul datacenter.
+* General network connectivity to all mesh gateways within remote Consul datacenters.
+
+### Proxy
+
+Envoy is the only proxy with mesh gateway capabilities in Consul.
+
+Mesh gateway proxies receive their configuration through Consul, which automatically generates it based on the proxy's registration.
+Consul can only translate mesh gateway registration information into Envoy configuration.
+
+Sidecar proxies that send traffic to an upstream service through a gateway need to know the location of that gateway. They discover the gateway based on their sidecar proxy registrations. Consul can only translate the gateway registration information into Envoy configuration.
+
+Sidecar proxies that do not send upstream traffic through a gateway are not affected when you deploy gateways. If you are using Consul's built-in proxy as a Connect sidecar it will continue to work for intra-datacenter traffic and will receive incoming traffic even if that traffic has passed through a gateway.
+
+## Configuration
+
+Configure the following settings to register the mesh gateway as a service in Consul.
+
+* Specify `mesh-gateway` in the `kind` field to register the gateway with Consul.
+* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. 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.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace.
+* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). 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.
+* If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications.
+
+### Modes
+
+Each upstream associated with a service mesh proxy can be configured so that it is routed through a mesh gateway.
+Depending on your network, the proxy's connection to the gateway can operate in one of the following modes:
+
+* `none` - No gateway is used and a service mesh connect proxy makes its outbound connections directly
+  to the destination services. This is the default for WAN federation. This setting is invalid for peered clusters
+  and will be treated as remote instead. 
+
+* `local` - The service mesh connect proxy makes an outbound connection to a gateway running in the
+  same datacenter. That gateway is responsible for ensuring that the data is forwarded to gateways in the destination datacenter.
+
+* `remote` - The service mesh proxy makes an outbound connection to a gateway running in the destination datacenter.
+  The gateway forwards the data to the final destination service. This is the default for peered clusters.
+
+### Connect Proxy Configuration
+
+Set the proxy to the preferred [mode](#modes) to configure the service mesh proxy. You can specify the mode globally or within child configurations to control proxy behaviors at a lower level. Consul recognizes the following order of precedence if the gateway mode is configured in multiple locations the order of precedence:
+
+1. Upstream definition (highest priority)
+2. Service instance definition
+3. Centralized `service-defaults` configuration entry
+4. Centralized `proxy-defaults` configuration entry
+
+## Example Configurations
+
+Use the following example configurations to help you understand some of the common scenarios.
+
+### Enabling Gateways Globally
+
+The following `proxy-defaults` configuration will enable gateways for all Connect services in the `local` mode.
+
+<CodeTabs heading="Example: Enabling gateways globally.">
+
+```hcl
+Kind = "proxy-defaults"
+Name = "global"
+MeshGateway {
+   Mode = "local"
+}
+```
+
+```yaml
+Kind: proxy-defaults
+MeshGateway:
+- Mode: local
+Name: global
+```
+</CodeTabs>
+
+### Enabling Gateways Per Service
+
+The following `service-defaults` configuration will enable gateways for all Connect services with the name `web`.
+
+<CodeTabs heading="Example: Enabling gateways per service.">
+
+```hcl
+Kind = "service-defaults"
+Name = "web"
+MeshGateway {
+   Mode = "local"
+}
+```
+
+```yaml
+Kind: service-defaults
+MeshGateway:
+- Mode: local
+Name: web
+```
+
+</CodeTabs>
+
+### Enabling Gateways for a Service Instance
+
+The following [Proxy Service Registration](/docs/connect/registration/service-registration)
+definition will enable gateways for the service instance in the `remote` mode.
+
+<CodeTabs heading="Example: Enabling gateways for a service instance.">
+
+```hcl
+service {
+   name = "web-sidecar-proxy"
+   kind = "connect-proxy"
+   port = 8181
+   proxy {
+      destination_service_name = "web"
+      mesh_gateway {
+         mode = "remote"
+      }
+      upstreams = [
+         {
+            destination_name = "api"
+            datacenter = "secondary"
+            local_bind_port = 10000
+         }
+      ]
+   }
+}
+
+# Or alternatively inline with the service definition:
+
+service {
+  name = "web"
+  port = 8181
+  connect {
+    sidecar_service {
+      proxy {
+        mesh_gateway {
+         mode = "remote"
+        }
+        upstreams = [
+          {
+            destination_name = "api"
+            datacenter = "secondary"
+            local_bind_port = 10000
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+```yaml
+service:
+- kind: connect-proxy
+  name: web-sidecar-proxy
+  port: 8181
+  proxy:
+  - destination_service_name: web
+    mesh_gateway:
+    - mode: remote
+    upstreams:
+    - datacenter: secondary
+      destination_name: api
+      local_bind_port: 100
+```
+
+</CodeTabs>
+
+### Enabling Gateways for a Proxy Upstream
+
+The following service definition will enable gateways in the `local` mode for one upstream, the `remote` mode for a second upstream and will disable gateways for a third upstream.
+
+<CodeTabs heading="Example: Enabling gateways for a proxy upstream.">
+
+```hcl
+service {
+   name = "web-sidecar-proxy"
+   kind = "connect-proxy"
+   port = 8181
+   proxy {
+      destination_service_name = "web"
+      upstreams = [
+         {
+            destination_name = "api"
+            local_bind_port = 10000
+            mesh_gateway {
+               mode = "remote"
+            }
+         },
+         {
+            destination_name = "db"
+            local_bind_port = 10001
+            mesh_gateway {
+               mode = "local"
+            }
+         },
+         {
+            destination_name = "logging"
+            local_bind_port = 10002
+            mesh_gateway {
+               mode = "none"
+            }
+         },
+      ]
+   }
+}
+```
+```yaml
+service:
+- kind: connect-proxy
+  name: web-sidecar-proxy
+  port: 8181
+  proxy:
+  - destination_service_name: web
+    upstreams:
+    - destination_name: api
+      local_bind_port: 10000
+      mesh_gateway:
+      - mode: remote
+    - destination_name: db
+      local_bind_port: 10001
+      mesh_gateway:
+      - mode: local
+    - destination_name: logging
+      local_bind_port: 10002
+      mesh_gateway:
+      - mode: none
+  ```
+  </CodeTabs>