Initial Mesh Gateway Docs (#6090)

website/source/api/agent/service.html.md

@@ -518,7 +518,8 @@ 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
   services that are [Connect-capable](/docs/connect/index.html)
-  proxies representing another service.
+  proxies representing another service or "mesh-gateway" for instances of
+  a [mesh gateway](/docs/connect/mesh_gateway.html)
 
 - `ProxyDestination` `(string: "")` - **Deprecated** From 1.2.0 to 1.2.3 this
   was used for "connect-proxy" `Kind` services however the equivalent field is
@@ -527,8 +528,8 @@ service definition keys for compatibility with the config file format.
   entirely. It's strongly recommended to switch to using the new field.
 
 - `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a
-  Connect proxy instance. This is only valid if `Kind == "connect-proxy"`. See
+  Connect proxy instance. This is only valid if `Kind == "connect-proxy"` or
-  the [Proxy documentation](/docs/connect/registration/service-registration.html)
+  `Kind == "mesh-gateway"`. See the [Proxy documentation](/docs/connect/registration/service-registration.html)
   for full details.
 
 - `Connect` `(Connect: nil)` - Specifies the

website/source/docs/agent/services.html.md

@@ -63,7 +63,10 @@ example shows all possible fields, but note that only a few are required.
       "local_service_address": "127.0.0.1",
       "local_service_port": 9090,
       "config": {},
-      "upstreams": []
+      "upstreams": [],
+      "mesh_gateway": {
+        "mode": "local"
+      }
     },
     "connect": {
       "native": false,
@@ -140,7 +143,8 @@ deprecated and has been removed as of Consul 1.1.
 ### Connect
 
 The `kind` field is used to optionally identify the service as a [Connect
-proxy](/docs/connect/proxies.html) instance with the value `connect-proxy`. For
+proxy](/docs/connect/proxies.html) instance with the value `connect-proxy` or
+a [Mesh Gateway<sup>(beta)</sup>](/docs/connect/mesh_gateway.html) instance with the value `mesh-gateway`. For
 typical non-proxy instances the `kind` field must be omitted. The `proxy` field
 is also required for Connect proxy registrations and is only valid if `kind` is
 `connect-proxy`. The only required `proxy` field is `destination_service_name`.

website/source/docs/commands/connect/envoy.html.md.erb

@@ -45,32 +45,17 @@ proxy configuration needed.
    using `unix:///path/to/socket` if the [agent is configured to
    listen](/docs/agent/options.html#addresses) that way.
 
--> **Note:** gRPC uses the same TLS
+  -> **Note:** gRPC uses the same TLS
     settings as the HTTPS API. If HTTPS is enabled then gRPC will require HTTPS
     as well.
 
    <%= partial "docs/commands/http_api_options_client" %>
 
-#### Envoy Options
+#### Envoy Options for both Sidecars and Gateways
 
-* `-sidecar-for` - The _ID_ (not name if they differ) of the service instance
+ * `-proxy-id` - The [proxy service](/docs/connect/registration/service-registration.html) ID on the
-  this proxy will represent. The target service doesn't need to exist on the
-  local agent yet but a [sidecar proxy
-  registration](/docs/connect/registration/service-registration.html) with
-  `proxy.destination_service_id` equal to the passed value must be present. If
-  multiple proxy registrations targeting the same local service instance are
-  present the command will error and `-proxy-id` should be used instead.
-
-* `-proxy-id` - The [proxy
-  service](/docs/connect/registration/service-registration.html) ID on the
    local agent. This must already be present on the local agent.
 
--> **Note:** If ACLs are enabled, a token granting `service:write` for the
-  _target_ service (configured in `proxy.destination_service_name`) must be
-  passed using the `-token` option or `CONSUL_HTTP_TOKEN` environment variable.
-  This token authorizes the proxy to obtain TLS certificates representing the
-  target service.
-
  * `-envoy-binary` - The full path to a specific Envoy binary to exec. By
    default the current `$PATH` is searched for `envoy`.
 
@@ -82,11 +67,11 @@ proxy configuration needed.
    bootstrap config to stdout in JSON protobuf form. This can be directed to a
    file and used to start Envoy with `envoy -c bootstrap.json`.
 
-~> **Security Note:** If ACLs are enabled the bootstrap JSON will contain the
+    ~> **Security Note:** If ACLs are enabled the bootstrap JSON will contain the
-ACL token from `-token` or the environment and so should be handled as a secret.
+      ACL token from `-token` or the environment and so should be handled as a secret.
-This token grants the identity of any service it has `service:write` permission
+      This token grants the identity of any service it has `service:write` permission
-for and so can be used to access any upstream service that that service is
+      for and so can be used to access any upstream service that that service is
-allowed to access by [Connect intentions](/docs/connect/intentions.html).
+      allowed to access by [Connect intentions](/docs/connect/intentions.html).
 
  * `-- [pass-through options]` - Any options given after a double dash are passed
    directly through to the `envoy` invocation. See [Envoy's
@@ -94,6 +79,54 @@ allowed to access by [Connect intentions](/docs/connect/intentions.html).
    always specifies `--config-file` and `--v2-config-only` and by default passes
    `--disable-hot-restart` see [hot restart](#hot-restart).
 
+#### Envoy Sidecar Proxy Options
+
+* `-sidecar-for` - The _ID_ (not name if they differ) of the service instance
+  this proxy will represent. The target service doesn't need to exist on the
+  local agent yet but a [sidecar proxy
+  registration](/docs/connect/registration/service-registration.html) with
+  `proxy.destination_service_id` equal to the passed value must be present. If
+  multiple proxy registrations targeting the same local service instance are
+  present the command will error and `-proxy-id` should be used instead.
+
+ -> **Note:** If ACLs are enabled, a token granting `service:write` for the
+    _target_ service (configured in `proxy.destination_service_name`) must be
+    passed using the `-token` option or `CONSUL_HTTP_TOKEN` environment variable.
+    This token authorizes the proxy to obtain TLS certificates representing the
+    target service.
+
+#### Envoy Mesh Gateway Options
+
+* `-mesh-gateway` - Flag to indicate that Envoy should be configured as a Mesh
+  Gateway. If multiple mesh gateways are managed by the same local agent then
+  `-proxy-id` should be used as well to specify the instance this represents.
+
+* `-register` - Indicates that the mesh gateway service should be registered
+  with the local agent instead of expecting it to already exist. This flag
+  is unused for traditional sidecar proxies.
+
+* `-address` - The address to advertise for services within the local datacenter
+  to use to reach the mesh gateway instance. This flag is used in combination with
+  `-register`. This takes the form of `<ip address>:<port>` but also supports go-sockaddr
+  templates.
+
+* `-wan-address` - The address to advertise for services within remote datacenters
+  to use to reach the mesh gateway instance. This flag is used in combination with
+  `-register`. This takes the form of `<ip address>:<port>` but also supports go-sockaddr
+  templates.
+
+* `-service` - The name of the mesh gateway service to register. This flag is used
+  in combination with `-register`.
+
+* `-deregister-after-critical` - The amount of time the gateway services health check can
+  be failing before being deregistered. This flag is used in combination with `-register`
+
+-> **Note:** If ACLs are enabled, a token granting `service:write` for the
+   mesh gateway's service name must be passed using the `-token` option or
+   `CONSUL_HTTP_TOKEN` environment variable. This token authorizes the proxy
+   to obtain receive and route communications for other Connect services but
+   does not allow decrypting any of their communications.
+
 ## Examples
 
 Assume a local service instance is registered on the local agent with a
@@ -108,6 +141,8 @@ service {
 }
 ```
 
+### Basic Sidecar Proxy
+
 The sidecar Envoy process can be started with.
 
 ```text
@@ -118,6 +153,8 @@ This example assumes that the correct [environment variables](#api-options) are
 used to set the local agent connection information and ACL token, or that the
 agent is using all-default configuration.
 
+### Additional Envoy Arguments
+
 To pass additional arguments directly to Envoy, for example output logging
 level, you can use:
 
@@ -125,6 +162,8 @@ level, you can use:
 $ consul connect envoy -sidecar-for web -- -l debug
 ```
 
+### Multiple Proxy Instances
+
 To run multiple different proxy instances on the same host, you will
 need to use `-admin-bind` on all but one to ensure they don't attempt to bind to
 the same port as in the following example.
@@ -133,6 +172,16 @@ the same port as in the following example.
 $ consul connect envoy -sidecar-for db -admin-bind localhost:19001
 ```
 
+### Mesh Gateways
+
+The mesh gateway Envoy process can be started with.
+
+```sh
+$ consul connect envoy -mesh-gateway -register \
+  -address '{{ GetInterfaceIP "eth0" }}:8443' \
+  -wan-address '{{ GetInterfaceIP "eth1" }}:8443'
+```
+
 ## Exec Security Details
 
 The command needs to pass the bootstrap config through to Envoy. Envoy currently

website/source/docs/connect/mesh_gateway.html.md

@@ -0,0 +1,169 @@
+---
+layout: "docs"
+page_title: "Connect - Mesh Gateways (beta)"
+sidebar_current: "docs-connect-meshgateways"
+description: |-
+  A Mesh Gateway enables better routing of a Connect service's data to upstreams in other datacenters. This section details how to use Envoy and describes how you can plug in a gateway of your choice.
+---
+
+# Mesh Gateways <sup>(beta)</sup>
+
+Mesh gateways enable routing of Connect traffic between different Consul datacenters. Those datacenters
+can reside in different clouds or runtime environments where general interconnectivity between all services
+in all datacenters isn't feasible. These gateways operate by sniffing the SNI header out of the Connect session
+and then route the connection to the appropriate destination based on the server name requested. The data
+within the Connect session is not decrypted by the Gateway.
+
+![Mesh Gateway Architecture](/assets/images/mesh-gateways.png)
+
+## Prerequisites
+
+Each mesh gateway needs three things:
+
+1. A local Consul agent to manage its configuration.
+2. General network connectivity to all services within its local Consul datacenter.
+3. General network connectivity to all mesh gateways within remote Consul datacenters.
+
+## Modes of Operation
+
+Each upstream of a Connect proxy can be configured to be routed through a mesh gateway. Depending on
+your network, the proxy's connection to the gateway can happen in one of the following modes:
+
+* `local` - In this mode the Connect proxy makes its outbound connection to a gateway running in the
+  same datacenter. That gateway is then responsible for ensuring the data gets forwarded along to
+  gateways in the destination datacenter. This is the mode of operation depicted in the diagram at
+  the beginning of the page.
+
+* `remote` - In this mode the Connect proxy makes its outbound connection to a gateway running in the
+  destination datacenter. That gateway will then forward the data to the final destination service.
+
+* `none` - In this mode, no gateway is used and a Connect proxy makes its outbound connections directly
+  to the destination services.
+
+## Mesh Gateway Configuration
+
+Mesh gateways are defined very similarly to other typical services. The one exception is that a mesh gateway
+service definition may contain a `Proxy.Config` entry just like a Connect proxy service to define opaque
+configuration parameters useful for the actual proxy software.
+
+## Connect Proxy Configuration
+
+Configuring a Connect Proxy to use gateways is as simple as setting its mode of operation. This can be done
+in several different places allowing for global to more fine grained control. If the gateway mode is configured
+in multiple locations the order of precedence is as follows
+
+1. Upstream Definition
+2. Service Instance Definition
+3. Centralized `service-defaults` configuration entry
+4. Centralized `proxy-defaults` configuration entry.
+
+### Enabling Gateways Globally
+
+The following `proxy-defaults` configuration will enable gateways for all Connect services in the `local` mode.
+
+```hcl
+Kind = "proxy-defaults"
+Name = "global"
+MeshGateway {
+   Mode = "local"
+}
+```
+
+### Enabling Gateways Per-Service
+
+The following `service-defaults` configuration will enable gateways for all Connect services with the name "web".
+
+```hcl
+Kind = "service-defaults"
+Name = "web"
+MeshGateway {
+   Mode = "local"
+}
+```
+
+### Enabling Gateways for a Service Instance
+
+The following service definition will enable gateways for the service instance in the `remote` mode.
+
+```hcl
+service {
+   name = "web-sidecar-proxy"
+   port = 8181
+   proxy {
+      destination_service_name = "web"
+      mesh_gateway {
+         mode = "remote"
+      }
+      upstreams = [
+         {
+            destination_name = "api"
+            datacenter = "secondary"
+            local_bind_port = 10000
+         }
+      ]
+   }
+}
+```
+
+Or alternatively as a sidecar service:
+
+```hcl
+service {
+  name = "web"
+  port = 8181
+  connect {
+    sidecar_service {
+      proxy {
+        mesh_gateway {
+         mode = "remote"
+        }
+        upstreams = [
+          {
+            destination_name = "api"
+            datacenter = "secondary"
+            local_bind_port = 10000
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### 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.
+
+```hcl
+service {
+   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"
+            }
+         },
+      ]
+   }
+}
+```

website/source/docs/connect/proxies/envoy.md

@@ -217,6 +217,31 @@ definition](/docs/connect/registration/service-registration.html) or
   connections before timing out. Defaults to 5000
   (5 seconds).
 
+### Mesh Gateway Options <sup>(beta)</sup>
+
+These fields may also be overridden explicitly in the [proxy service
+definition](/docs/connect/registration/service-registration.html), or defined in
+the  [global `proxy-defaults` configuration
+entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) to act as
+defaults that are inherited by all services.
+
+- `connect_timeout_ms` - The number of milliseconds to allow when making upstream
+  connections before timing out. Defaults to 5000
+  (5 seconds).
+
+- `envoy_mesh_gateway_bind_tagged_addresses` - Indicates that the mesh gateway
+  services tagged addresses should be bound to listeners in addition to the
+  default listener address.
+
+- `envoy_mesh_gateway_bind_addresses` - A map of additional addresses to be bound.
+  This map's keys are the name of the listeners to be created and the values are
+  a map with two keys, address and port, that combined make the address to bind the
+  listener to. These are bound in addition to the default address.
+
+- `envoy_mesh_gateway_no_default_bind` - Prevents binding to the default address
+  of the mesh gateway service. This should be used with one of the other options
+  to configure the gateways bind addresses.
+
 ## Advanced Configuration
 
 To support more flexibility when configuring Envoy, several "lower-level" options exist

website/source/docs/connect/registration/service-registration.html.md

@@ -81,7 +81,8 @@ registering a proxy instance.
     "local_service_address": "127.0.0.1",
     "local_service_port": 9090,
     "config": {},
-    "upstreams": []
+    "upstreams": [],
+    "mesh_gateway": {}
   },
   "port": 8181
 }
@@ -119,6 +120,9 @@ registering a proxy instance.
    this proxy should create listeners for. The format is defined in
    [Upstream Configuration Reference](#upstream-configuration-reference).
 
+ - `mesh_gateway` `(object: {})` - Specifies the mesh gateway configuration
+   for this proxy. The format is defined in the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference).
+
 ### Upstream Configuration Reference
 
 The following examples show all possible upstream configuration parameters.
@@ -149,7 +153,10 @@ followed by documentation for each attribute.
   "datacenter": "dc1",
   "local_bind_address": "127.0.0.1",
   "local_bind_port": 1234,
-  "config": {}
+  "config": {},
+  "mesh_gateway": {
+    "mode": "local"
+  }
 },
 ```
 
@@ -187,3 +194,57 @@ followed by documentation for each attribute.
   options available when using the built-in proxy. If using Envoy as a proxy,
   see [Envoy configuration
   reference](/docs/connect/configuration.html#envoy-options)
+* `mesh_gateway` `(object: {})` - Specifies the mesh gateway configuration
+   for this proxy. The format is defined in the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference).
+
+
+### Mesh Gateway Configuration Reference <sup>(beta)</sup>
+
+The following examples show all possible mesh gateway configurations.
+
+Note that `snake_case` is used here as it works in both [config file and API
+registrations](/docs/agent/services.html#service-definition-parameter-case).
+
+#### Using a Local/Egress Gateway in the Local Datacenter
+
+```json
+{
+  "mode": "local"
+}
+```
+
+#### Direct to a Remote/Ingress in a Remote Dataceter
+```json
+{
+  "mode": "remote"
+}
+```
+
+#### Prevent Using a Mesh Gateway
+```json
+{
+  "mode": "none"
+}
+```
+
+#### Default Mesh Gateway Mode
+```json
+{
+  "mode": ""
+}
+```
+
+* `mode` `(string: "")` - This defines the mode of operation for how
+  upstreams with a remote destination datacenter get resolved.
+  - `"local"` - Mesh gateway services in the local datacenter will be used
+     as the next-hop destination for the upstream connection.
+  - `"remote"` - Mesh gateway services in the remote/target datacenter will
+     be used as the next-hop destination for the upstream connection.
+  - `"none"` - No mesh gateway services will be used and the next-hop destination
+     for the connection will be directly to the final service(s).
+  - `""` - Default mode. The default mode will be `"none"` if no other configuration
+     enables them. The order of precedence for setting the mode is
+       1. Upstream
+       2. Proxy Service's `Proxy` configuration
+       3. The `service-defaults` configuration for the service.
+       4. The `global` `proxy-defaults`.

website/source/layouts/docs.erb

@@ -498,6 +498,9 @@
               </li>
             </ul>
           </li>
+          <li<%= sidebar_current("docs-connect-meshgateways") %>>
+             <a href="/docs/connect/mesh_gateway.html">Mesh Gateways <sup>(beta)</sup></a>
+          </li>
           <li<%= sidebar_current("docs-connect-registration") %>>
             <a href="/docs/connect/registration.html">Registering Proxies</a>
             <ul class="nav">