From bb103f22dd362a8938eea08681e9e49d4238d0f2 Mon Sep 17 00:00:00 2001 From: Chris Piraino Date: Wed, 17 Jun 2020 14:43:58 -0500 Subject: [PATCH] Updates docs with ingress Host header clarifications (#8062) * Updates docs with ingress Host header changes Clarify that a Host header is required for L7 protocols, and specify that the default is to use the Consul DNS ingress subdomain * Add sentence about using '*' by itself for testing * Add optional step for using L7 routing config * Note that port numbers may need to be added in the Hosts field --- .../agent/config-entries/ingress-gateway.mdx | 33 +++++++++++++++---- .../pages/docs/connect/ingress-gateway.mdx | 17 ++++++---- 2 files changed, 38 insertions(+), 12 deletions(-) diff --git a/website/pages/docs/agent/config-entries/ingress-gateway.mdx b/website/pages/docs/agent/config-entries/ingress-gateway.mdx index f0e339b45a..0e978abcd6 100644 --- a/website/pages/docs/agent/config-entries/ingress-gateway.mdx +++ b/website/pages/docs/agent/config-entries/ingress-gateway.mdx @@ -36,7 +36,8 @@ description: >- listener will be routable. - The ingress gateway will route traffic based on the host/authority header, expecting a value matching `.ingress.*`, or if using namespaces, - `.ingress..*`. + `.ingress..*`. This matches the [Consul DNS + ingress subdomain](/docs/agent/dns#ingress-service-lookups). A wildcard specifier cannot be set on a listener of protocol `tcp`. @@ -116,6 +117,9 @@ Listeners = [ - `Enabled` `(bool: false)` - Set this configuration to enable TLS for every listener on the gateway. + If TLS is enabled, then each host defined in the `Host` field will be added + as a DNSSAN to the gateway's x509 certificate. + - `Listeners` `(array: )` - A list of listeners that the ingress gateway should setup, uniquely identified by their port number. @@ -141,11 +145,28 @@ Listeners = [ assumed. - `Hosts` `(array: )` - 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. + requests will match this service. This cannot be used with a `tcp` + listener, and cannot be specified alongside a `*` service name. If not + specified, the default domain `.ingress.*` will be used to + match services. Requests **must** send the correct host to be routed to + the defined service. + + The wildcard specifier, `*`, can be used by itself to match all traffic + coming to the ingress gateway, if TLS is not enabled. This allows a user + to route all traffic to a single service without specifying a host, + allowing simpler tests and demos. Otherwise, the wildcard specifier can + be used as part of the host to match multiple hosts, but only in the + leftmost DNS label. This ensures that all defined hosts are valid DNS + records. For example, `*.example.com` is valid, while `example.*` and + `*-suffix.example.com` are not. + + ~> **Note:** If a well-known port is not used, i.e. a port other than 80 + (http) or 443 (https), then the port must be appended to the host to + correctly match traffic. This is defined in the [HTTP/1.1 + RFC](https://tools.ietf.org/html/rfc2616#section-14.23). If TLS is + enabled, then the host **without** the port must be added to the `Hosts` + field as well. TLS verification only matches against the hostname of the + incoming connection, and thus does not take into account the port. ## ACLs diff --git a/website/pages/docs/connect/ingress-gateway.mdx b/website/pages/docs/connect/ingress-gateway.mdx index 5328017d5e..1dcee7034c 100644 --- a/website/pages/docs/connect/ingress-gateway.mdx +++ b/website/pages/docs/connect/ingress-gateway.mdx @@ -22,16 +22,19 @@ exposed and on what port. You configure an ingress gateway by defining a set of 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 `.ingress.`. +For listeners with a +[protocol](/docs/agent/config-entries/ingress-gateway#protocol) other than +`tcp`, 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. The host used to match traffic +defaults to the [Consul DNS ingress +subdomain](/docs/agent/dns#ingress-service-lookups), but can be changed using +the [hosts](/docs/agent/config-entries/ingress-gateway#hosts) field. + ![Ingress Gateway Architecture](/img/ingress-gateways.png) ## Prerequisites @@ -65,6 +68,8 @@ a set of listeners that expose the desired backing services. The config entry ca 4. **Optionally** use the `.ingress.` [DNS subdomain](/docs/agent/dns#ingress-service-lookups) to discover the ingress gateways for a service. +5. **Optionally** use the [Consul L7 traffic management](/docs/connect/l7-traffic-management) for exposed services to route traffic. + ## Ingress Gateway Configuration Ingress gateways are configured in service definitions and registered with Consul like other services, with two exceptions.