160 lines
5.2 KiB
Plaintext
160 lines
5.2 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'Configuration Entry Kind: Ingress Gateway'
|
|
sidebar_title: ingress-gateway <sup> Beta </sup>
|
|
description: >-
|
|
The `ingress-gateway` config entry kind allows for configuring Ingress gateways
|
|
with listeners that expose a set of services outside the Consul service mesh.
|
|
---
|
|
|
|
# Ingress Gateway <sup> Beta </sup>
|
|
|
|
-> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer.
|
|
|
|
The `ingress-gateway` config entry kind allows you to configure ingress gateways
|
|
with listeners that expose a set of services outside the Consul service mesh.
|
|
See [Ingress Gateway](/docs/connect/ingress_gateway) for more information.
|
|
|
|
~> [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 [Ingress Gateway](/docs/connect/ingress_gateway) for more information.
|
|
|
|
## Wildcard service specification
|
|
|
|
Ingress gateways can optionally target all services within a Consul namespace by
|
|
specifying a wildcard `*` as the service name. A wildcard specifier allows
|
|
for a single listener to route traffic to all available services on the
|
|
Consul service mesh, differentiating between the services by their host/authority
|
|
header.
|
|
|
|
A wildcard specifier provides the following properties for an ingress
|
|
gateway:
|
|
- All services with the same
|
|
[protocol](/docs/agent/config-entries/ingress-gateway#protocol) as the
|
|
listener will be routable.
|
|
- The ingress gateway will route traffic based on the host/authority header,
|
|
expecting a value matching `<service-name>.*`, or if using namespaces,
|
|
`<service-name>.ingress.<namespace>.*`.
|
|
|
|
A wildcard specifier cannot be set on a listener of protocol `tcp`.
|
|
|
|
## Sample Config Entries
|
|
|
|
Set up a TCP listener for a single service:
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "ingress-service"
|
|
|
|
Listeners = [
|
|
{
|
|
Port = 3456
|
|
Protocol = "tcp"
|
|
Services = [
|
|
{
|
|
Name = "db"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
Set up a wildcard HTTP listener to proxy traffic to all available services,
|
|
make two services available over a custom port with user-provided hosts, and
|
|
enable TLS on every listener:
|
|
|
|
```hcl
|
|
Kind = "ingress-gateway"
|
|
Name = "ingress-service"
|
|
|
|
TLS {
|
|
Enabled = true
|
|
}
|
|
|
|
Listeners = [
|
|
{
|
|
Port = 8080
|
|
Protocol = "http"
|
|
Services = [
|
|
{
|
|
Name = "*"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
Port = 4567
|
|
Protocol = "http"
|
|
Services = [
|
|
{
|
|
Name = "api"
|
|
Hosts = ["foo.example.com"]
|
|
},
|
|
{
|
|
Name = "web"
|
|
Hosts = ["website.example.com"]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
## Available Fields
|
|
|
|
- `Kind` - Must be set to `ingress-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.
|
|
|
|
- `TLS` `(TLSConfig: <optional>)` - TLS configuration for this gateway.
|
|
|
|
- `Enabled` `(bool: false)` - Set this configuration to enable TLS for
|
|
every listener on the gateway.
|
|
|
|
- `Listeners` `(array<IngressListener>: <optional>)` - A list of listeners that
|
|
the ingress gateway should setup, uniquely identified by their port number.
|
|
|
|
- `Port` `(int: 0)` - The port that the listener should receive traffic on.
|
|
|
|
- `Protocol` `(string: "tcp")` - The protocol associated with the listener.
|
|
This can be any protocol supported by
|
|
[service-defaults](/docs/agent/config-entries/service-defaults#protocol).
|
|
|
|
- `Services` `(array<IngressService>: <optional>)` - A list of services to be
|
|
exposed via this listener. For "tcp" listeners, only a single service is
|
|
allowed.
|
|
|
|
- `Name` `(string: "")` - The name of the service that should be exposed
|
|
through this listener. This can be either a service registered in the
|
|
catalog, or a service defined only by [other config
|
|
entries](/docs/connect/l7-traffic-management). If the wildcard specifier,
|
|
`*`, is provided, then ALL services will be exposed through the listener.
|
|
This is not supported for listener's with protocol "tcp".
|
|
|
|
- `Namespace` `(string: "")` - <EnterpriseAlert inline /> The namespace to resolve the service from
|
|
instead of the current namespace. If empty the current namespace is
|
|
assumed.
|
|
|
|
- `Hosts` `(array<string>: <optional>)` - A list of hosts that specify what
|
|
requests will match to this service. This cannot be used with a `tcp`
|
|
listener, and cannot be specified alongside a `*` service name.
|
|
|
|
If TLS is enabled, then each host will be added as a DNSSAN to the
|
|
gateway's x509 certificate.
|
|
|
|
## ACLs
|
|
|
|
Configuration entries may be protected by
|
|
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
|
|
|
|
Reading an `ingress-gateway` config entry requires `service:read` on the `Name`
|
|
field of the config entry.
|
|
|
|
Creating, updating, or deleting an `ingress-gateway` config entry requires
|
|
`operator:write`.
|