status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Initial Mesh Gateway Docs (#6090)

This commit is contained in:
Matt Keeler 2019-07-08 19:40:57 -04:00 committed by GitHub
parent 3716bac3b7
commit d4a3c0e661
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 345 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
website/source/api/agent/service.html.md
View File

@ -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
the [Proxy documentation](/docs/connect/registration/service-registration.html)
Connect proxy instance. This is only valid if `Kind == "connect-proxy"` or
`Kind == "mesh-gateway"`. See the [Proxy documentation](/docs/connect/registration/service-registration.html)
for full details.
- `Connect` `(Connect: nil)` - Specifies the

BIN
website/source/assets/images/mesh-gateways.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 78 KiB

8
website/source/docs/agent/services.html.md
View File

@ -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`.

101
website/source/docs/commands/connect/envoy.html.md.erb
View File

@ -45,31 +45,16 @@ 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
settings as the HTTPS API. If HTTPS is enabled then gRPC will require HTTPS
as well.
-> **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
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.
* `-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.
* `-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
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
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).
~> **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.
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
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

169
website/source/docs/connect/mesh_gateway.html.md Normal file
View File

@ -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"
}
},
]
}
}
```

25
website/source/docs/connect/proxies/envoy.md
View File

@ -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

65
website/source/docs/connect/registration/service-registration.html.md
View File

@ -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`.

3
website/source/layouts/docs.erb
View File

@ -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">