2020-05-13 21:29:40 +00:00
|
|
|
---
|
|
|
|
|
layout: docs
|
|
|
|
|
page_title: Connect - Ingress Gateways
|
2020-05-13 21:47:20 +00:00
|
|
|
sidebar_title: Ingress Gateways <sup> Beta </sup>
|
2020-05-13 21:29:40 +00:00
|
|
|
description: >-
|
|
|
|
|
An ingress gateway enables ingress traffic from services outside the Consul
|
|
|
|
|
service mesh to services inside the Consul service mesh. This section details
|
|
|
|
|
how to use Envoy and describes how you can plug in a gateway of your choice.
|
|
|
|
|
---
|
|
|
|
|
|
2020-05-13 21:47:20 +00:00
|
|
|
# Ingress Gateways <sup> Beta </sup>
|
2020-05-13 21:29:40 +00:00
|
|
|
|
|
|
|
|
-> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer.
|
|
|
|
|
|
|
|
|
|
Ingress gateways enable ingress traffic from services outside the Consul
|
|
|
|
|
service mesh to services inside the Consul service mesh. An ingress gateway is
|
|
|
|
|
a type of proxy and must be registered as a service in Consul, with the
|
|
|
|
|
[kind](/api/agent/service#kind) set to "ingress-gateway". They are an
|
|
|
|
|
entrypoint for outside traffic and allow you to define what services should be
|
|
|
|
|
exposed and on what port. You configure an ingress gateway by defining a set of
|
|
|
|
|
[listeners](/docs/agent/config-entries/ingress-gateway#listeners) that each map
|
|
|
|
|
to a set of backing
|
|
|
|
|
[services](/docs/agent/config-entries/ingress-gateway#services).
|
|
|
|
|
|
|
|
|
|
Depending on the
|
|
|
|
|
[protocol](/docs/agent/config-entries/ingress-gateway#protocol) defined for a
|
|
|
|
|
listener, multiple services can be specified for a single listener. In this
|
|
|
|
|
case, the ingress gateway relies on host/authority headers to decide the
|
|
|
|
|
service that should receive the traffic.
|
|
|
|
|
|
|
|
|
|
To enable easier service discovery, a new Consul [DNS
|
|
|
|
|
subdomain](/docs/agent/dns#ingress-service-lookups) is provided, on
|
|
|
|
|
`<service>.ingress.<domain>`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Prerequisites
|
|
|
|
|
|
|
|
|
|
Ingress gateways also require that your Consul datacenters are configured correctly:
|
|
|
|
|
|
|
|
|
|
- You'll need to use Consul version 1.8.0.
|
|
|
|
|
- Consul [Connect](/docs/agent/options#connect) must be enabled on the datacenter's Consul servers.
|
|
|
|
|
- [gRPC](/docs/agent/options#grpc_port) must be enabled on all client agents.
|
|
|
|
|
|
|
|
|
|
Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul.
|
|
|
|
|
|
|
|
|
|
## Running and Using an Ingress Gateway
|
|
|
|
|
|
|
|
|
|
You must complete the following steps to configure an ingress gateway to proxy traffic to services in the Consul service mesh:
|
|
|
|
|
|
|
|
|
|
1. On a host with a Consul client agent, start an Envoy proxy using the [envoy
|
|
|
|
|
subcommand](/docs/commands/connect/envoy), specifying the `ingress` gateway
|
|
|
|
|
type:
|
2020-05-14 21:04:53 +00:00
|
|
|
```shell
|
|
|
|
|
$ consul connect envoy -gateway=ingress -register -service ingress-service \
|
|
|
|
|
-address '{{ GetInterfaceIP "eth0" }}:8888'
|
|
|
|
|
```
|
2020-05-13 21:29:40 +00:00
|
|
|
|
|
|
|
|
2. Create and apply an `ingress-gateway` [configuration entry](/docs/agent/config-entries/ingress-gateway) that defines
|
|
|
|
|
a set of listeners that expose the desired backing services. The config entry can be applied via the
|
|
|
|
|
[CLI](/docs/commands/config/write) or [API](/api/config#apply-configuration).
|
|
|
|
|
|
|
|
|
|
3. Ensure that [Consul intentions](/docs/commands/intention) are setup to allow connections from the ingress gateway to the backing services.
|
|
|
|
|
|
|
|
|
|
4. **Optionally** use the `<service>.ingress.<domain>` [DNS subdomain](/docs/agent/dns#ingress-service-lookups) to discover the ingress
|
|
|
|
|
gateways for a service.
|
|
|
|
|
|
|
|
|
|
## Ingress Gateway Configuration
|
|
|
|
|
|
|
|
|
|
Ingress gateways are configured in service definitions and registered with Consul like other services, with two exceptions.
|
|
|
|
|
The first is that the [kind](/api/agent/service#kind) must be "ingress-gateway". Second,
|
|
|
|
|
the ingress gateway service definition may contain a `Proxy.Config` entry just like a
|
|
|
|
|
Connect proxy service, to define opaque configuration parameters useful for the actual proxy software.
|
|
|
|
|
For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as
|
|
|
|
|
[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides).
|
|
|
|
|
|
|
|
|
|
-> **Note:** If ACLs are enabled, a token granting `service:write` for the gateway's service name
|
|
|
|
|
and `service:read` for all services in the datacenter. These permissions authorize the token to route
|
|
|
|
|
communications for other Connect services.
|
|
|
|
|
|
|
|
|
|
~> [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.
|
