1--- 2layout: docs 3page_title: Connect Datacenters - Mesh Gateways 4description: >- 5 A Mesh Gateway enables better routing of a Connect service's data to upstreams 6 in other datacenters. This section details how to use Envoy and describes how 7 you can plug in a gateway of your choice. 8--- 9 10# Mesh Gateways 11 12-> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer. 13 14Mesh gateways enable routing of Connect traffic between different Consul datacenters. Those datacenters 15can reside in different clouds or runtime environments where general interconnectivity between all services 16in all datacenters isn't feasible. These gateways operate by sniffing the SNI header out of the Connect session 17and then route the connection to the appropriate destination based on the server name requested. The data 18within the mTLS session is not decrypted by the Gateway. 19 20![Mesh Gateway Architecture](/img/mesh-gateways.png) 21 22For a complete example of how to connect services across datacenters, 23review the [mesh gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways). 24 25## Prerequisites 26 27Each mesh gateway needs three things: 28 291. A local Consul agent to manage its configuration. 302. General network connectivity to all services within its local Consul datacenter. 313. General network connectivity to all mesh gateways within remote Consul datacenters. 32 33Mesh gateways also require that your Consul datacenters are configured correctly: 34 35- You'll need to use Consul version 1.6.0. 36- Consul [Connect](/docs/agent/options#connect) must be enabled in both datacenters. 37- Each of your [datacenters](/docs/agent/options#datacenter) must have a unique name. 38- Your datacenters must be [WAN joined](https://learn.hashicorp.com/tutorials/consul/federarion-gossip-wan). 39- The [primary datacenter](/docs/agent/options#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other. 40- [gRPC](/docs/agent/options#grpc_port) must be enabled. 41- If you want to [enable gateways globally](/docs/connect/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/options#enable_central_service_config). 42 43Currently, Envoy is the only proxy with mesh gateway capabilities in Consul. 44 45- Mesh gateway proxies receive their configuration through Consul, which 46 automatically generates it based on the proxy's registration. Currently Consul 47 can only translate mesh gateway registration information into Envoy 48 configuration, therefore the proxies acting as mesh gateways must be Envoy. 49 50- Sidecar proxies that send traffic to an upstream service through a gateway 51 need to know the location of that gateway. They discover the gateway based on 52 their sidecar proxy registrations. Consul can only translate the gateway 53 registration information into Envoy configuration, so any sidecars that send 54 upstream traffic through a gateway must be Envoy. 55 56Sidecar proxies that don't send upstream traffic through a gateway aren't 57affected when you deploy gateways. If you are using Consul's built-in proxy as a 58Connect sidecar it will continue to work for intra-datacenter traffic and will 59receive incoming traffic even if that traffic has passed through a gateway. 60 61## Modes of Operation 62 63Each upstream of a Connect proxy can be configured to be routed through a mesh gateway. Depending on 64your network, the proxy's connection to the gateway can happen in one of the following modes: 65 66- `local` - In this mode the Connect proxy makes its outbound connection to a gateway running in the 67 same datacenter. That gateway is then responsible for ensuring the data gets forwarded along to 68 gateways in the destination datacenter. This is the mode of operation depicted in the diagram at 69 the beginning of the page. 70 71- `remote` - In this mode the Connect proxy makes its outbound connection to a gateway running in the 72 destination datacenter. That gateway will then forward the data to the final destination service. 73 74- `none` - In this mode, no gateway is used and a Connect proxy makes its outbound connections directly 75 to the destination services. 76 77## Mesh Gateway Configuration 78 79Mesh gateways are defined similarly to other services registered with Consul, with two exceptions. 80The first is that the [service kind](/api/agent/service#kind) must be "mesh-gateway". Second, 81the mesh gateway service definition may contain a `Proxy.Config` entry, just like a 82Connect proxy service, to define opaque configuration parameters useful for the actual proxy software. 83For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as 84[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides). 85 86-> **Note:** If ACLs are enabled, a token granting `service:write` for the gateway's service name 87and `service:read` for all services in the datacenter must be added to the gateway's service definition. 88These permissions authorize the token to route communications for other Connect services but does not 89allow decrypting any of their communications. 90 91## Connect Proxy Configuration 92 93Configuring a Connect Proxy to use gateways is as simple as setting its mode of operation. This can be done 94in several different places allowing for global to more fine grained control. If the gateway mode is configured 95in multiple locations the order of precedence is as follows 96 971. Upstream Definition 982. Service Instance Definition 993. Centralized `service-defaults` configuration entry 1004. Centralized `proxy-defaults` configuration entry. 101 102### Enabling Gateways Globally 103 104The following `proxy-defaults` configuration will enable gateways for all Connect services in the `local` mode. 105 106```hcl 107Kind = "proxy-defaults" 108Name = "global" 109MeshGateway { 110 Mode = "local" 111} 112``` 113 114### Enabling Gateways Per-Service 115 116The following `service-defaults` configuration will enable gateways for all Connect services with the name "web". 117 118```hcl 119Kind = "service-defaults" 120Name = "web" 121MeshGateway { 122 Mode = "local" 123} 124``` 125 126### Enabling Gateways for a Service Instance 127 128The following [Proxy Service Registration](/docs/connect/registration/service-registration) 129definition will enable gateways for the service instance in the `remote` mode. 130 131```hcl 132service { 133 name = "web-sidecar-proxy" 134 kind = "connect-proxy" 135 port = 8181 136 proxy { 137 destination_service_name = "web" 138 mesh_gateway { 139 mode = "remote" 140 } 141 upstreams = [ 142 { 143 destination_name = "api" 144 datacenter = "secondary" 145 local_bind_port = 10000 146 } 147 ] 148 } 149} 150``` 151 152Or alternatively inline with the service definition: 153 154```hcl 155service { 156 name = "web" 157 port = 8181 158 connect { 159 sidecar_service { 160 proxy { 161 mesh_gateway { 162 mode = "remote" 163 } 164 upstreams = [ 165 { 166 destination_name = "api" 167 datacenter = "secondary" 168 local_bind_port = 10000 169 } 170 ] 171 } 172 } 173 } 174} 175``` 176 177### Enabling Gateways for a Proxy Upstream 178 179The following service definition will enable gateways in the `local` mode for one upstream, the `remote` mode 180for a second upstream and will disable gateways for a third upstream. 181 182```hcl 183service { 184 name = "web-sidecar-proxy" 185 kind = "connect-proxy" 186 port = 8181 187 proxy { 188 destination_service_name = "web" 189 upstreams = [ 190 { 191 destination_name = "api" 192 local_bind_port = 10000 193 mesh_gateway { 194 mode = "remote" 195 } 196 }, 197 { 198 destination_name = "db" 199 local_bind_port = 10001 200 mesh_gateway { 201 mode = "local" 202 } 203 }, 204 { 205 destination_name = "logging" 206 local_bind_port = 10002 207 mesh_gateway { 208 mode = "none" 209 } 210 }, 211 ] 212 } 213} 214``` 215