450 lines
12 KiB
Plaintext
450 lines
12 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'Configuration Entry Kind: Terminating Gateway'
|
|
sidebar_title: terminating-gateway
|
|
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
|
|
|
|
-> **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 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.
|
|
|
|
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
|
|
|
|
<Tabs>
|
|
<Tab heading="HCL">
|
|
|
|
Link gateway named "us-west-gateway" with the billing service:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
|
|
Services = [
|
|
{
|
|
Name = "billing"
|
|
}
|
|
]
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="HCL (Consul Enterprise)">
|
|
|
|
Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
Namespace = "default"
|
|
|
|
Services = [
|
|
{
|
|
Namespace = "finance"
|
|
Name = "billing"
|
|
}
|
|
]
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON">
|
|
|
|
Link gateway named "us-west-gateway" with the billing service:
|
|
|
|
```json
|
|
{
|
|
"Kind": "terminating-gateway",
|
|
"Name": "us-west-gateway",
|
|
"Services": [
|
|
{
|
|
"Name": "billing"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON (Consul Enterprise)">
|
|
|
|
Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace:
|
|
|
|
```json
|
|
{
|
|
"Kind": "terminating-gateway",
|
|
"Name": "us-west-gateway",
|
|
"Namespace": "default",
|
|
"Services": [
|
|
{
|
|
"Namespace": "finance",
|
|
"Name": "billing"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
<Tabs>
|
|
<Tab heading="HCL">
|
|
|
|
Link gateway named "us-west-gateway" with the billing service and specify a CA file for one-way TLS authentication:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
|
|
Services = [
|
|
{
|
|
Name = "billing"
|
|
CAFile = "/etc/certs/ca-chain.cert.pem"
|
|
}
|
|
]
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="HCL (Consul Enterprise)">
|
|
|
|
Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace,
|
|
and specify a CA file for one-way TLS authentication:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
Namespace = "default"
|
|
|
|
Services = [
|
|
{
|
|
Namespace = "finance"
|
|
Name = "billing"
|
|
CAFile = "/etc/certs/ca-chain.cert.pem"
|
|
}
|
|
]
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON">
|
|
|
|
Link gateway named "us-west-gateway" with the billing service and specify a CA file for one-way TLS authentication:
|
|
|
|
```json
|
|
{
|
|
"Kind": "terminating-gateway",
|
|
"Name": "us-west-gateway",
|
|
"Services": [
|
|
{
|
|
"Name": "billing",
|
|
"CAFile": "/etc/certs/ca-chain.cert.pem"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON (Consul Enterprise)">
|
|
|
|
Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace,
|
|
and specify a CA file for one-way TLS authentication:
|
|
|
|
```json
|
|
{
|
|
"Kind": "terminating-gateway",
|
|
"Name": "us-west-gateway",
|
|
"Namespace": "default",
|
|
"Services": [
|
|
{
|
|
"Namespace": "finance",
|
|
"Name": "billing",
|
|
"CAFile": "/etc/certs/ca-chain.cert.pem"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
<Tabs>
|
|
<Tab heading="HCL">
|
|
|
|
Link gateway named "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 = "billing"
|
|
CAFile = "/etc/certs/ca-chain.cert.pem"
|
|
KeyFile = "/etc/certs/gateway.key.pem"
|
|
CertFile = "/etc/certs/gateway.cert.pem"
|
|
}
|
|
]
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="HCL (Consul Enterprise)">
|
|
|
|
Link gateway named "us-west-gateway" in the default namespace with the payments service in the finance namespace.
|
|
Also specify a CA file, key file, and cert file for mutual TLS authentication:
|
|
|
|
```hcl
|
|
Kind = "terminating-gateway"
|
|
Name = "us-west-gateway"
|
|
Namespace = "default"
|
|
|
|
Services = [
|
|
{
|
|
Namespace = "finance"
|
|
Name = "billing"
|
|
CAFile = "/etc/certs/ca-chain.cert.pem"
|
|
KeyFile = "/etc/certs/gateway.key.pem"
|
|
CertFile = "/etc/certs/gateway.cert.pem"
|
|
}
|
|
]
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON">
|
|
|
|
Link gateway named "us-west-gateway" with the payments service and specify a CA file, key file, and cert file for mutual TLS authentication:
|
|
|
|
```json
|
|
{
|
|
"Kind": "terminating-gateway",
|
|
"Name": "us-west-gateway",
|
|
"Services": [
|
|
{
|
|
"Name": "billing",
|
|
"CAFile": "/etc/certs/ca-chain.cert.pem",
|
|
"KeyFile": "/etc/certs/gateway.key.pem",
|
|
"CertFile": "/etc/certs/gateway.cert.pem"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON (Consul Enterprise)">
|
|
|
|
Link gateway named "us-west-gateway" in the default namespace with the payments service in the finance namespace.
|
|
Also specify a CA file, key file, and cert file for mutual TLS authentication:
|
|
|
|
```json
|
|
{
|
|
"Kind": "terminating-gateway",
|
|
"Name": "us-west-gateway",
|
|
"Namespace": "default",
|
|
"Services": [
|
|
{
|
|
"Namespace": "finance",
|
|
"Name": "billing",
|
|
"CAFile": "/etc/certs/ca-chain.cert.pem",
|
|
"KeyFile": "/etc/certs/gateway.key.pem",
|
|
"CertFile": "/etc/certs/gateway.cert.pem"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
<Tabs>
|
|
<Tab heading="HCL">
|
|
|
|
Link gateway named "us-west-gateway" with all services in the datacenter, 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"
|
|
|
|
Services = [
|
|
{
|
|
Name = "*"
|
|
CAFile = "/etc/common-certs/ca-chain.cert.pem"
|
|
KeyFile = "/etc/common-certs/gateway.key.pem"
|
|
CertFile = "/etc/common-certs/gateway.cert.pem"
|
|
},
|
|
{
|
|
Name = "billing"
|
|
CAFile = "/etc/billing-ca/ca-chain.cert.pem",
|
|
SNI = "billing.service.com"
|
|
}
|
|
]
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="HCL (Consul Enterprise)">
|
|
|
|
Link gateway named "us-west-gateway" in the default namespace 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"
|
|
}
|
|
]
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON">
|
|
|
|
Link gateway named "us-west-gateway" with all services in the datacenter, and configure default certificates for mutual TLS.
|
|
Also override the SNI and CA file used for connections to the billing service:
|
|
|
|
```json
|
|
{
|
|
"Kind": "terminating-gateway",
|
|
"Name": "us-west-gateway",
|
|
"Services": [
|
|
{
|
|
"Name": "*",
|
|
"CAFile": "/etc/billing-ca/ca-chain.cert.pem",
|
|
"KeyFile": "/etc/certs/gateway.key.pem",
|
|
"CertFile": "/etc/certs/gateway.cert.pem",
|
|
"SNI": "billing.service.com"
|
|
},
|
|
{
|
|
"Name": "billing",
|
|
"CAFile": "/etc/billing-ca/ca-chain.cert.pem",
|
|
"SNI": "billing.service.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
<Tab heading="JSON (Consul Enterprise)">
|
|
|
|
Link gateway named "us-west-gateway" in the default namespace 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:
|
|
|
|
```json
|
|
{
|
|
"Kind": "terminating-gateway",
|
|
"Name": "us-west-gateway",
|
|
"Namespace": "default",
|
|
"Services": [
|
|
{
|
|
"Namespace": "finance",
|
|
"Name": "*",
|
|
"CAFile": "/etc/billing-ca/ca-chain.cert.pem",
|
|
"KeyFile": "/etc/certs/gateway.key.pem",
|
|
"CertFile": "/etc/certs/gateway.cert.pem",
|
|
"SNI": "billing.service.com"
|
|
},
|
|
{
|
|
"Namespace": "finance",
|
|
"Name": "billing",
|
|
"CAFile": "/etc/billing-ca/ca-chain.cert.pem",
|
|
"SNI": "billing.service.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## 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.
|
|
|
|
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.9.0.
|
|
|
|
- `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/tutorials/consul/access-control-setup-production).
|
|
|
|
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`.
|