open-consul/website/pages/docs/connect/terminating-gateway.mdx

---
layout: docs
page_title: Connect - Terminating Gateways
sidebar_title: Terminating Gateways <sup> Beta </sup>
description: >-
  A terminating gateway enables traffic from services in the Consul
  service mesh to services outside the mesh. This section details
  how to configure and run a terminating gateway.
---

# Terminating Gateways <sup> Beta </sup>

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

Terminating gateways enable connections 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](/img/terminating-gateways.png)

~> **Beta limitations:** Terminating Gateways currently do not support targeting service subsets with
[L7 configuration](/docs/connect/l7-traffic-management). They route to all instances of a service with no capabilities
for filtering by instance. Terminating Gateways also currently do not support routing to services with a hostname
defined as a their address. The service address registered with Consul, that the gateway will route traffic to,  **must** be a resolved IP address.

## 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](/docs/connect/mesh-gateway)
whenever possible since they are not capable of decrypting traffic or connecting directly to services.

By specifying a path to a [CA file](/docs/agent/config-entries/terminating-gateway#cafile) connections
from the terminating gateway will be encrypted using one-way TLS authentication. If a path to a
[client certificate](/docs/agent/config-entries/terminating-gateway#certfile)
and [private key](/docs/agent/config-entries/terminating-gateway#keyfile) 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.

-> **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:

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.
- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers.
- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents.

Currently, [Envoy](https://www.envoyproxy.io/) 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](/api/health#list-nodes-for-connect-capable-service) endpoint.

## Running and Using a Terminating Gateway

You must complete the following steps to configure a terminating gateway to proxy traffic from services in the Consul service mesh:

1. On a host with a Consul client agent, start an Envoy proxy using the [envoy subcommand](/docs/commands/connect/envoy#terminating-gateways) and
specifying the `terminating` gateway type:
  ```shell
  $ consul connect envoy -gateway=terminating -register -service us-west-gateway \
    -address '{{ GetInterfaceIP "eth0" }}:8443'
  ```

2. Create and apply a `terminating-gateway` [configuration entry](/docs/agent/config-entries/terminating-gateway) that defines 
a set of services that the gateway will proxy traffic to. The config entry can be applied via the 
[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration).

3. Ensure that [Consul intentions](/docs/commands/intention) are set up to allow connections from the source services in the mesh 
to the gateway's linked services. The intentions must reference the destination service's name and not the gateway itself.

4. Ensure necessary [upstreams](/docs/connect/registration/service-registration#upstream-configuration-reference)
have been added to service definitions of the source services in the Consul service mesh. Each source service that needs
to connect to a service proxied by a terminating gateway will need to add the external service as an upstream destination.

## 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](/api/agent/service#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](/docs/connect/proxies/envoy#gateway-options) as well as
[escape-hatch overrides](/docs/connect/proxies/envoy#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.

Linking services to a terminating gateway is done with a `terminating-gateway`
[configuration entry](/docs/agent/config-entries/terminating-gateway). This config entry can be applied via the 
[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration).

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](/docs/commands/connect/envoy#terminating-gateways) on additional hosts and specifying
the same gateway name with the `service` flag.

~> [Configuration entries](/docs/agent/config-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](/api/catalog#register-entity)
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](/api/catalog.html#node) 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](/docs/internals/anti-entropy) 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 guide](https://learn.hashicorp.com/consul/developer-discovery/external).