2020-05-13 21:29:40 +00:00
---
layout: docs
page_title: Connect - Terminating Gateways
2020-06-18 21:27:06 +00:00
sidebar_title: Terminating Gateways
2020-05-13 21:29:40 +00:00
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.
---
2020-06-18 21:27:06 +00:00
# Terminating Gateways
2020-05-13 21:29:40 +00:00
2020-06-02 14:40:07 +00:00
-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer.
2020-05-13 21:29:40 +00:00
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.
2020-06-18 21:27:06 +00:00
For additional use cases and usage patterns, review the guide for
[understanding terminating gateways](https://learn.hashicorp.com/consul/developer-mesh/understand-terminating-gateways).
2020-06-02 14:40:07 +00:00
2020-06-18 21:27:06 +00:00
~> **Known limitations:** Terminating gateways currently do not support targeting service subsets with
2020-05-13 21:29:40 +00:00
[L7 configuration](/docs/connect/l7-traffic-management). They route to all instances of a service with no capabilities
2020-06-03 21:28:45 +00:00
for filtering by instance.
2020-05-13 21:29:40 +00:00
## 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
2020-05-28 19:19:17 +00:00
to linked services. Connections over the WAN or open internet should flow through [mesh gateways](/docs/connect/mesh-gateway)
2020-05-13 21:29:40 +00:00
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.
2020-06-18 21:27:06 +00:00
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](https://www.consul.io/docs/commands/connect/envoy#service) provides additional fault tolerance
as well as the ability to perform rolling restarts.
2020-06-02 14:40:07 +00:00
-> **Note:** If certificates and keys are configured the terminating gateway will upgrade HTTP connections to TLS.
2020-05-13 21:29:40 +00:00
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:
2020-06-18 21:27:06 +00:00
- You'll need to use Consul version 1.8.0 or newer.
2020-05-13 21:29:40 +00:00
- 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
2020-06-18 21:27:06 +00:00
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 guide](https://learn.hashicorp.com/consul/developer-mesh/terminating-gateways).
2020-05-13 21:29:40 +00:00
## 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).
2020-05-20 15:27:25 +00:00
-> **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.
2020-05-13 21:29:40 +00:00
Linking services to a terminating gateway is done with a `terminating-gateway`
2020-06-02 14:40:07 +00:00
[configuration entry](/docs/agent/config-entries/terminating-gateway). This config entry can be applied via the
2020-05-13 21:29:40 +00:00
[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
2020-06-02 14:40:07 +00:00
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.
2020-05-13 21:29:40 +00:00
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).
