Merge pull request #11859 from hashicorp/docs/service-mesh-gateways-clarification-for-1.11.0
clarify mesh gateway docs use cases; include admin partition flow
This commit is contained in:
trujillo-adam
GitHub
commit
2edf383b79
|
|
@ -7,31 +7,29 @@ description: >-
|
|||
|
||||
# Gateways
|
||||
|
||||
Gateways provide connectivity into, out of, and between Consul service meshes.
|
||||
This topic provides an overview of the gateway features shipped with Consul. Gateways provide connectivity into, out of, and between Consul service meshes. You can configure the following types of gateways:
|
||||
|
||||
- Enable service-to-service traffic between Consul datacenters with [mesh gateways](#mesh-gateways).
|
||||
- Accept traffic from outside the Consul service mesh to services in the mesh with [ingress gateways](#ingress-gateways).
|
||||
- Route traffic from services in the Consul service mesh to external services with [terminating gateways](#terminating-gateways).
|
||||
- [Mesh gateways](#mesh-gateways) enable service-to-service traffic between Consul datacenters or between Consul admin partitions. They also enable datacenters to be federated across wide area networks.
|
||||
- [Ingress gateways](#ingress-gateways) enable services to accept traffic from outside the Consul service mesh.
|
||||
- [Terminating gateways](#terminating-gateways) enable you to route traffic from services in the Consul service mesh to external services.
|
||||
|
||||
## Mesh Gateways
|
||||
|
||||
-> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer.
|
||||
|
||||
Mesh gateways enable routing of service mesh traffic between different Consul datacenters. Those datacenters can reside
|
||||
Mesh gateways enable service mesh traffic to be routed between different Consul datacenters and admin partitions. The datacenters or partitions can reside
|
||||
in different clouds or runtime environments where general interconnectivity between all services in all datacenters
|
||||
isn't feasible. One scenario where this is useful is when connecting networks with overlapping IP address space.
|
||||
isn't feasible.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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/wan-federation-via-mesh-gateways).
|
||||
Mesh gateways enable the following scenarios:
|
||||
|
||||
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).
|
||||
* **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/wan-federation-via-mesh-gateways) for additional information.
|
||||
* **Service-to-service communication across datacenters**. Refer to [Enabling Service-to-service Traffic Accross Datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters) for additional information.
|
||||
* **Service-to-service communication across admin partitions**. Since Consul 1.11.0, you can create administrative boundaries for single Consul deployements called "admin partitions". You can use mesh gateways to facilitate cross-partition communication. Refer to [Enabling Service-to-service Traffic Accross Admin Partitions](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions) for additional 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.
|
||||
|
||||
## Ingress Gateways
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: External <> Internal Services - Ingress Gateways
|
||||
page_title: Using Ingress Gateways to Connect External Traffic to Internal Services
|
||||
description: >-
|
||||
An ingress gateway enables ingress traffic from services outside the Consul
|
||||
service mesh to services inside the Consul service mesh. This section details
|
||||
how to use Envoy and describes how you can plug in a gateway of your choice.
|
||||
This topic describes how ingress gateways enable traffic from external services to reach services inside the Consul service mesh.
|
||||
It provides guidance on how to use Envoy and how to plug into your preferred gateway.
|
||||
---
|
||||
|
||||
# Ingress Gateways
|
||||
|
|
|
|||
|
|
@ -1,215 +0,0 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Connect Datacenters - Mesh Gateways
|
||||
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
|
||||
|
||||
-> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer.
|
||||
|
||||
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 mTLS session is not decrypted by the Gateway.
|
||||
|
||||
|
||||
|
||||
For a complete example of how to connect services across datacenters,
|
||||
review the [mesh gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways).
|
||||
|
||||
## 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.
|
||||
|
||||
Mesh gateways also require that your Consul datacenters are configured correctly:
|
||||
|
||||
- Consul version 1.6.0 or newer is required.
|
||||
- Consul [Connect](/docs/agent/options#connect) must be enabled in both datacenters.
|
||||
- Each of your [datacenters](/docs/agent/options#datacenter) must have a unique name.
|
||||
- Your datacenters must be [WAN joined](https://learn.hashicorp.com/tutorials/consul/federarion-gossip-wan).
|
||||
- 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.
|
||||
- [gRPC](/docs/agent/options#grpc_port) must be enabled.
|
||||
- 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).
|
||||
|
||||
Currently, 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. Currently Consul
|
||||
can only translate mesh gateway registration information into Envoy
|
||||
configuration, therefore the proxies acting as mesh gateways must be Envoy.
|
||||
|
||||
- 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, so any sidecars that send
|
||||
upstream traffic through a gateway must be Envoy.
|
||||
|
||||
Sidecar proxies that don't send upstream traffic through a gateway aren't
|
||||
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.
|
||||
|
||||
## 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
|
||||
illustrated in the diagram above:
|
||||
|
||||
- `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 similarly to other services registered with Consul, with two exceptions.
|
||||
The first is that the [service kind](/api/agent/service#kind) must be "mesh-gateway". Second,
|
||||
the 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.
|
||||
For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as
|
||||
[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides).
|
||||
|
||||
-> **Note:** If ACLs are enabled, a token granting `service:write` for the gateway's service name
|
||||
and `service:read` for all services in the datacenter must be added to the gateway's service definition.
|
||||
These permissions authorize the token to route communications for other Connect services but does not
|
||||
allow decrypting any of their communications.
|
||||
|
||||
## 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 [Proxy Service Registration](/docs/connect/registration/service-registration)
|
||||
definition will enable gateways for the service instance in the `remote` mode.
|
||||
|
||||
```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:
|
||||
|
||||
```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"
|
||||
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"
|
||||
}
|
||||
},
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,267 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Service-to-service Traffic Across Datacenters
|
||||
description: >-
|
||||
This topic describes how to configure mesh gateways to route a service's data to upstreams
|
||||
in other datacenters. It describes how to use Envoy and how you can integrate with your preferred gateway.
|
||||
---
|
||||
|
||||
# Service-to-service Traffic Across Datacenters
|
||||
|
||||
-> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer.
|
||||
|
||||
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.
|
||||
|
||||
Mesh gateways 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.
|
||||
|
||||
The following diagram describes the architecture for using mesh gateways for cross-datacenter communication:<a name="mesh-architecture-diagram"/>
|
||||
|
||||
|
||||
|
||||
-> **Mesh Gateway Tutorial**: Follow the [mesh gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways) to learn important concepts associated with using mesh gateways for connecting services across datacenters.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Ensure that your Consul environment meets the following requirements.
|
||||
|
||||
### Consul
|
||||
|
||||
* Consul version 1.6.0 or newer.
|
||||
* A local Consul agent is required to manage its configuration.
|
||||
* Consul [Connect](/docs/agent/options#connect) must be enabled in both datacenters.
|
||||
* Each [datacenter](/docs/agent/options#datacenter) must have a unique name.
|
||||
* Each datacenters must be [WAN joined](https://learn.hashicorp.com/tutorials/consul/federarion-gossip-wan).
|
||||
* 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.
|
||||
* [gRPC](/docs/agent/options#grpc_port) must be enabled.
|
||||
* 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).
|
||||
|
||||
### 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 (refer to the [mesh-architecture-diagram](#mesh-architecture-diagram)):
|
||||
|
||||
* `none` - (Default) No gateway is used and a service mesh connect proxy makes its outbound connections directly
|
||||
to the destination services.
|
||||
|
||||
* `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.
|
||||
Refer to the flow labeled `local` in the [mesh-architecture-diagram](#mesh-architecture-diagram).
|
||||
|
||||
* `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.
|
||||
Refer to the flow labeled `remote` in the [mesh-architecture-diagram](#mesh-architecture-diagram).
|
||||
|
||||
### 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>
|
||||
|
|
@ -0,0 +1,244 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Service-to-service Traffic Across Partitions
|
||||
description: >-
|
||||
This topic describes how to configure mesh gateways to route a service's data to upstreams
|
||||
in other partitions. It describes how to use Envoy and how you can integrate with your preferred gateway.
|
||||
---
|
||||
|
||||
# Service-to-service Traffic Across Partitions
|
||||
|
||||
-> **Consul Enterprise 1.11.0+:** Admin partitions are supported in Consul Enterprise versions 1.11.0 and newer.
|
||||
|
||||
Mesh gateways enable you to route service mesh traffic between different Consul [admin partitions](/docs/enteprise/admin-partitions).
|
||||
Partitions can reside in different clouds or runtime environments where general interconnectivity between all services
|
||||
in all partitions isn't feasible.
|
||||
|
||||
Mesh gateways 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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Ensure that your Consul environment meets the following requirements.
|
||||
|
||||
### Consul
|
||||
|
||||
* Consul Enterprise version 1.11.0 or newer.
|
||||
* A local Consul agent is required to manage its configuration.
|
||||
* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/options#connect) for details.
|
||||
* Each partition must have a unique name. Refer to the [admin partitions documentation](/docs/enteprise/admin-partitions) for details.
|
||||
* 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).
|
||||
|
||||
### 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 partition. 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_partition` must be configured to enable cross-partition traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace.
|
||||
* Configure the `exported-services` configuration entry to enable Consul to export services contained in an admin partition to one or more additional partitions. Refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services) for details.
|
||||
* 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` - (Default) No gateway is used and a service mesh connect proxy makes its outbound connections directly
|
||||
to the destination services.
|
||||
|
||||
* `local` - The service mesh connect proxy makes an outbound connection to a gateway running in the same datacenter. The gateway at the outbound connection is responsible for ensuring that the data is forwarded to gateways in the destination partition.
|
||||
|
||||
* `remote` - The service mesh connect proxy makes an outbound connection to a gateway running in the destination datacenter.
|
||||
The gateway forwards the data to the final destination service.
|
||||
|
||||
### 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 `web` service instances in the `finance` partition.
|
||||
|
||||
<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 = "local"
|
||||
}
|
||||
upstreams = [
|
||||
{
|
||||
destination_partition = "finance"
|
||||
destination_namespace = "default"
|
||||
destination_type = "service"
|
||||
destination_name = "billing"
|
||||
local_bind_port = 9090
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
service:
|
||||
- kind: connect-proxy
|
||||
name: web-sidecar-proxy
|
||||
port: 8181
|
||||
proxy:
|
||||
- destination_service_name: web
|
||||
mesh_gateway:
|
||||
- mode: local
|
||||
upstreams:
|
||||
- destination_name: billing
|
||||
destination_namespace: default
|
||||
destination_partition: finance
|
||||
destination_type: service
|
||||
local_bind_port: 9090
|
||||
```
|
||||
</CodeTabs>
|
||||
|
||||
### Enabling Gateways for a Proxy Upstream
|
||||
|
||||
The following service definition will enable gateways in `local` mode for three different partitions. Note that each service exists in the same namepace, but are separated by admin partition.
|
||||
|
||||
<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"
|
||||
destination_namespace = "dev"
|
||||
destination_partition = "api"
|
||||
local_bind_port = 10000
|
||||
mesh_gateway {
|
||||
mode = "local"
|
||||
}
|
||||
},
|
||||
{
|
||||
destination_name = "db"
|
||||
destination_namespace = "dev"
|
||||
destination_partition = "db"
|
||||
local_bind_port = 10001
|
||||
mesh_gateway {
|
||||
mode = "local"
|
||||
}
|
||||
},
|
||||
{
|
||||
destination_name = "logging"
|
||||
destination_namespace = "dev"
|
||||
destination_partition = "logging"
|
||||
local_bind_port = 10002
|
||||
mesh_gateway {
|
||||
mode = "local"
|
||||
}
|
||||
},
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
service:
|
||||
- kind: connect-proxy
|
||||
name: web-sidecar-proxy
|
||||
port: 8181
|
||||
proxy:
|
||||
- destination_service_name: web
|
||||
upstreams:
|
||||
- destination_name: api
|
||||
destination_namespace: dev
|
||||
destination_partition: api
|
||||
local_bind_port: 10000
|
||||
mesh_gateway:
|
||||
- mode: local
|
||||
- destination_name: db
|
||||
destination_namespace: dev
|
||||
destination_partition: db
|
||||
local_bind_port: 10001
|
||||
mesh_gateway:
|
||||
- mode: local
|
||||
- destination_name: logging
|
||||
destination_namespace: dev
|
||||
destination_partition: logging
|
||||
local_bind_port: 10002
|
||||
mesh_gateway:
|
||||
- mode: local
|
||||
```
|
||||
</CodeTabs>
|
||||
|
|
@ -277,24 +277,28 @@
|
|||
"path": "connect/gateways"
|
||||
},
|
||||
{
|
||||
"title": "Connect Datacenters - Mesh Gateways",
|
||||
"title": "Mesh Gateways",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "connect/gateways/mesh-gateway"
|
||||
},
|
||||
{
|
||||
"title": "WAN Federation",
|
||||
"path": "connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways"
|
||||
},
|
||||
{
|
||||
"title": "Enabling Service-to-service Traffic Across Datacenters",
|
||||
"path": "connect/gateways/mesh-gateway/service-to-service-traffic-datacenters"
|
||||
},
|
||||
{
|
||||
"title": "Enabling Service-to-service Traffic Across Admin Partitions",
|
||||
"path": "connect/gateways/mesh-gateway/service-to-service-traffic-partitions"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "External <> Internal Services - Ingress Gateways",
|
||||
"title": "Ingress Gateways",
|
||||
"path": "connect/gateways/ingress-gateway"
|
||||
},
|
||||
{
|
||||
"title": "Internal <> External Services - Terminating Gateways",
|
||||
"title": "Terminating Gateways",
|
||||
"path": "connect/gateways/terminating-gateway"
|
||||
}
|
||||
]
|
||||
|
|
|
|||
Loading…
Reference in New Issue