open-consul/website/pages/docs/agent/config-entries/ingress-gateway.mdx
2020-06-15 15:15:33 -05:00

160 lines
5.3 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>.ingress.*`, 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`.