consul/website/pages/docs/agent/config-entries/terminating-gateway.mdx

---
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.8.4.

- `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`.