Terminating Gateways

1.8.0+: This feature is available in Consul versions 1.8.0 and newer.

Terminating gateways enable connectivity within your organizational network from services in the Consul service mesh to services and destinations outside the mesh. These gateways effectively act as Connect proxies that can represent more than one service. They terminate Connect mTLS connections, enforce intentions, and forward requests to the appropriate destination.

Terminating Gateway Architecture

For additional use cases and usage patterns, review the tutorial for understanding terminating gateways.

Known limitations: Terminating gateways currently do not support targeting service subsets with L7 configuration. They route to all instances of a service with no capabilities for filtering by instance.

Security Considerations

We recommend that terminating gateways are not exposed to the WAN or open internet. This is because terminating gateways hold certificates to decrypt Consul Connect traffic directed at them and may be configured with credentials to connect to linked services. Connections over the WAN or open internet should flow through mesh gateways whenever possible since they are not capable of decrypting traffic or connecting directly to services.

By specifying a path to a CA file connections from the terminating gateway will be encrypted using one-way TLS authentication. If a path to a client certificate and private key are also specified connections from the terminating gateway will be encrypted using mutual TLS authentication.

If none of these are provided, Consul will only encrypt connections to the gateway and not from the gateway to the destination service.

When certificates for linked services are rotated, the gateway must be restarted to pick up the new certificates from disk. To avoid downtime, perform a rolling restart to reload the certificates. Registering multiple terminating gateway instances with the same name provides additional fault tolerance as well as the ability to perform rolling restarts.

Note: If certificates and keys are configured the terminating gateway will upgrade HTTP connections to TLS. Client applications can issue plain HTTP requests even when connecting to servers that require HTTPS.

Prerequisites

Each terminating gateway needs:

A local Consul client agent to manage its configuration.
General network connectivity to services within its local Consul datacenter.
General network connectivity to services and destinations outside the mesh that are part of the gateway services list.

Terminating gateways also require that your Consul datacenters are configured correctly:

You'll need to use Consul version 1.8.0 or newer.
Consul Connect must be enabled on the datacenter's Consul servers.
gRPC must be enabled on all client agents.

Currently, Envoy is the only proxy with terminating gateway capabilities in Consul.

Terminating gateway proxies receive their configuration through Consul, which automatically generates it based on the gateway's registration. Currently Consul can only translate terminating gateway registration information into Envoy configuration, therefore the proxies acting as terminating gateways must be Envoy.

Connect proxies that send upstream traffic through a gateway aren't affected when you deploy terminating gateways. If you are using non-Envoy proxies as Connect proxies they will continue to work for traffic directed at services linked to a terminating gateway as long as they discover upstreams with the /health/connect endpoint.

Running and Using a Terminating Gateway

For a complete example of how to enable connections from services in the Consul service mesh to services outside the mesh, review the terminating gateway tutorial.

Terminating Gateway Configuration

Terminating gateways are configured in service definitions and registered with Consul like other services, with two exceptions. The first is that the kind must be "terminating-gateway". Second, the terminating 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 as well as escape-hatch overrides.

Note: If ACLs are enabled, terminating gateways must be registered with a token granting node:read on the nodes of all services in its configuration entry. The token must also grant service:write for the terminating gateway's service name and the names of all services in the terminating gateway's configuration entry. These privileges will authorize the gateway to terminate mTLS connections on behalf of the linked services and then route the traffic to its final destination. If the Consul client agent on the gateway's node is not configured to use the default gRPC port, 8502, then the gateway's token must also provide agent:read for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies.

You can link services and destinations to a terminating gateway with a terminating-gateway configuration entry. This config entry can be applied via the CLI or API.

Gateways with the same name in Consul's service catalog are configured with a single configuration entry. This means that additional gateway instances registered with the same name will determine their routing based on the existing configuration entry. Adding replicas of a gateway that routes to a particular set of services requires running the envoy subcommand on additional hosts and specifying the same gateway name with the service flag.

Configuration entries are global in scope. A configuration entry for a gateway name applies across all federated Consul datacenters. If terminating gateways in different Consul datacenters need to route to different sets of services within their datacenter then the terminating gateways must be registered with different names.

The services that the terminating gateway will proxy for must be registered with Consul, even the services outside the mesh. They must also be registered in the same Consul datacenter as the terminating gateway. Otherwise the terminating gateway will not be able to discover the services' addresses. These services can be registered with a local Consul agent. If there is no agent present, the services can be registered directly in the catalog by sending the registration request to a client or server agent on a different host.

All services registered in the Consul catalog must be associated with a node, even when their node is not managed by a Consul client agent. All agent-less services with the same address can be registered under the same node name and address. However, ensure that the node name for external services registered directly in the catalog does not match the node name of any Consul client agent node. If the node name overlaps with the node name of a Consul client agent, Consul's anti-entropy sync will delete the services registered via the /catalog/register HTTP API endpoint.

Service-defaults destinations let you define endpoints external to the mesh and routable through a terminating gateway in transparent mode. After you define a service-defaults configuration entry for each destination, you can use the service-default name as part of the terminating gateway services list. If a service and a destination service-defaults have the same name, the terminating gateway will use the service.

For a complete example of how to register external services review the external services tutorial.