»Terminating Gateways

Terminating gateways enable connectivity from services in the Consul service mesh to services 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.

»Security Considerations

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.


Each terminating gateway needs:

  1. A local Consul client agent to manage its configuration.
  2. General network connectivity to services within its local Consul datacenter.

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.

Linking services to a terminating gateway is done 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.

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.

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