159 lines
6.4 KiB
Plaintext
159 lines
6.4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'Configuration Entry Kind: Terminating Gateway'
|
|
sidebar_title: terminating-gateway <sup> Beta </sup>
|
|
description: >-
|
|
The `terminating-gateway` config entry kind allows for configuring terminating gateways
|
|
to proxy traffic from services in the Consul service mesh to services outside the mesh.
|
|
---
|
|
|
|
# Terminating Gateway <sup> Beta </sup>
|
|
|
|
-> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer.
|
|
|
|
The `terminating-gateway` config entry kind you to configure terminating gateways
|
|
to proxy traffic from services in the Consul service mesh to services registered with Consul that do not have a
|
|
[Connect service sidecar proxy](/docs/connect/proxies). The configuration is associated with the name of a gateway service
|
|
and will apply to all instances of the gateway with that name.
|
|
|
|
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
|
|
across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different
|
|
sets of services within their datacenter then the ingress gateways **must** be registered with different names.
|
|
|
|
See [Terminating Gateway](/docs/connect/terminating_gateway) for more information.
|
|
|
|
## TLS Origination
|
|
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.
|
|
|
|
## Wildcard service specification
|
|
|
|
Terminating gateways can optionally target all services within a Consul namespace by specifying a wildcard "*"
|
|
as the service name. Configuration options set on the wildcard act as defaults that can be overridden
|
|
by options set on a specific service name.
|
|
|
|
Note that if the wildcard specifier is used, and some services in that namespace have a Connect sidecar proxy,
|
|
traffic from the mesh to those services will be evenly load-balanced between the gateway and their sidecars.
|
|
|
|
## Sample Config Entries
|
|
|
|
Link gateway "us-west-gateway" with the billing service:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
Services = [
|
|
{
|
|
Name = "billing"
|
|
}
|
|
]
|
|
```
|
|
|
|
Link gateway "us-west-gateway" with the api service and specify a CA file for one-way TLS authentication:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
Services = [
|
|
{
|
|
Name = "api"
|
|
CAFile = "/etc/certs/ca-chain.cert.pem"
|
|
}
|
|
]
|
|
```
|
|
|
|
Link gateway "us-west-gateway" with the payments service and specify a CA file, key file, and cert file for mutual TLS authentication:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
Services = [
|
|
{
|
|
Name = "payments"
|
|
CAFile = "/etc/certs/ca-chain.cert.pem"
|
|
KeyFile = "/etc/certs/gateway.key.pem"
|
|
CertFile = "/etc/certs/gateway.cert.pem"
|
|
}
|
|
]
|
|
```
|
|
|
|
Link gateway "us-west-gateway" with all services in the finance namespace, and configure default certificates for mutual TLS.
|
|
Also override the SNI and CA file used for connections to the billing service:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
Namespace = "default"
|
|
Services = [
|
|
{
|
|
Namespace = "finance"
|
|
Name = "*"
|
|
CAFile = "/etc/common-certs/ca-chain.cert.pem"
|
|
KeyFile = "/etc/common-certs/gateway.key.pem"
|
|
CertFile = "/etc/common-certs/gateway.cert.pem"
|
|
},
|
|
{
|
|
Namespace = "finance"
|
|
Name = "billing"
|
|
CAFile = "/etc/billing-ca/ca-chain.cert.pem"
|
|
SNI = "billing.service.com"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Available Fields
|
|
|
|
- `Kind` - Must be set to `terminating-gateway`
|
|
|
|
- `Name` `(string: <required>)` - Set to the name of the gateway being configured.
|
|
|
|
- `Namespace` `(string: "default")` - <EnterpriseAlert inline /> Specifies the namespace
|
|
the config entry will apply to. This must be the namespace the gateway is registered in.
|
|
If omitted, the namespace will be inherited from [the request](/api/config#ns)
|
|
or will default to the `default` namespace.
|
|
|
|
- `Services` `(array<LinkedService>: <optional>)` - A list of services to link
|
|
with the gateway. The gateway will proxy traffic to these services. These linked services
|
|
must be registered with Consul for the gateway to discover their addresses. They must also
|
|
be registered in the same Consul datacenter as the terminating gateway.
|
|
|
|
- `Name` `(string: "")` - The name of the service to link with the gateway.
|
|
If the wildcard specifier, `*`, is provided, then ALL services within the namespace
|
|
will be linked with the gateway.
|
|
|
|
- `Namespace` `(string: "")` - <EnterpriseAlert inline /> The namespace of the service.
|
|
If omitted, the namespace will be inherited from the config entry.
|
|
|
|
- `CAFile` `(string: "")` - A file path to a PEM-encoded certificate authority.
|
|
The file must be present on the proxy's filesystem.
|
|
The certificate authority is used to verify the authenticity of the service linked with the gateway.
|
|
It can be provided along with a CertFile and KeyFile for mutual TLS authentication, or on its own
|
|
for one-way TLS authentication. If none is provided the gateway **will not** encrypt the traffic to the destination.
|
|
|
|
- `CertFile` `(string: "")` - A file path to a PEM-encoded certificate.
|
|
The file must be present on the proxy's filesystem.
|
|
The certificate is provided servers to verify the gateway's authenticity. It must be provided if a KeyFile was specified.
|
|
|
|
- `KeyFile` `(string: "")` - A file path to a PEM-encoded private key.
|
|
The file must be present on the proxy's filesystem.
|
|
The key is used with the certificate to verify the gateway's authenticity. It must be provided along if a CertFile was specified.
|
|
|
|
- `SNI` `(string: "")` - An optional hostname or domain name to specify during the TLS handshake.
|
|
|
|
## ACLs
|
|
|
|
Configuration entries may be protected by
|
|
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
|
|
|
|
Reading a `terminating-gateway` config entry requires `service:read` on the `Name`
|
|
field of the config entry.
|
|
|
|
Creating, updating, or deleting a `terminating-gateway` config entry requires
|
|
`operator:write`.
|