Ingress Gateway

v1.8.4+: On Kubernetes, the IngressGateway custom resource is supported in Consul versions 1.8.4+.
v1.8.0+: On other platforms, this config entry is supported in Consul versions 1.8.0+.

The ingress-gateway config entry kind (IngressGateway on Kubernetes) allows you to configure ingress gateways with listeners that expose a set of services outside the Consul service mesh.

For Kubernetes, see Kubernetes Ingress Gateway for more information. For other platforms, see Ingress Gateway.

Note: Configuration 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 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 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>.*. This matches the Consul DNS ingress subdomain.

A wildcard specifier cannot be set on a listener of protocol tcp.

Sample Config Entries

TCP listener

Ingress Gateway - 图1

Ingress Gateway - 图2

Set up a TCP listener on an ingress gateway named “us-east-ingress” to proxy traffic to the “db” service:

HCL

Ingress Gateway - 图3

  • HCL
  • Kubernetes YAML
  • JSON
  1. Kind = "ingress-gateway"
  2. Name = "us-east-ingress"
  4. Listeners = [
  5.   {
  6.     Port     = 3456
  7.     Protocol = "tcp"
  8.     Services = [
  9.       {
  10.         Name = "db"
  11.       }
  12.     ]
  13.   }
  14. ]
  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: IngressGateway
  3. metadata:
  4.   name: us-east-ingress
  5. spec:
  6.   listeners:
  7.     - port: 3456
  8.       protocol: tcp
  9.       services:
  10.         - name: db
  1. {
  2.   "Kind": "ingress-gateway",
  3.   "Name": "us-east-ingress",
  4.   "Listeners": [
  5.     {
  6.       "Port": 3456,
  7.       "Protocol": "tcp",
  8.       "Services": [
  9.         {
  10.           "Name": "db"
  11.         }
  12.       ]
  13.     }
  14.   ]
  15. }

Wildcard HTTP listener

Ingress Gateway - 图4

Ingress Gateway - 图5

Set up a wildcard HTTP listener on an ingress gateway named “us-east-ingress” to proxy traffic to all services in the datacenter. Also make two services available over a custom port with user-provided hosts, and enable TLS on every listener:

HCL

Ingress Gateway - 图6

  • HCL
  • Kubernetes YAML
  • JSON
  1. Kind = "ingress-gateway"
  2. Name = "us-east-ingress"
  4. TLS {
  5.   Enabled = true
  6. }
  8. Listeners = [
  9.   {
  10.     Port     = 8080
  11.     Protocol = "http"
  12.     Services = [
  13.       {
  14.         Name = "*"
  15.       }
  16.     ]
  17.   },
  18.   {
  19.     Port     = 4567
  20.     Protocol = "http"
  21.     Services = [
  22.       {
  23.         Name  = "api"
  24.         Hosts = ["foo.example.com"]
  25.       },
  26.       {
  27.         Name  = "web"
  28.         Hosts = ["website.example.com"]
  29.       }
  30.     ]
  31.   }
  32. ]
  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: IngressGateway
  3. metadata:
  4.   name: us-east-ingress
  5. spec:
  6.   tls:
  7.     enabled: true
  8.   listeners:
  9.     - port: 8080
  10.       protocol: http
  11.       services:
  12.         - name: '*'
  13.     - port: 4567
  14.       protocol: http
  15.       services:
  16.         - name: api
  17.           hosts: ['foo.example.com']
  18.         - name: web
  19.           hosts: ['website.example.com']
  1. {
  2.   "Kind": "ingress-gateway",
  3.   "Name": "us-east-ingress",
  4.   "TLS": {
  5.     "Enabled": true
  6.   },
  7.   "Listeners": [
  8.     {
  9.       "Port": 8080,
  10.       "Protocol": "http",
  11.       "Services": [
  12.         {
  13.           "Name": "*"
  14.         }
  15.       ]
  16.     },
  17.     {
  18.       "Port": 4567,
  19.       "Protocol": "http",
  20.       "Services": [
  21.         {
  22.           "Name": "api",
  23.           "Hosts": ["foo.example.com"]
  24.         },
  25.         {
  26.           "Name": "web",
  27.           "Hosts": ["website.example.com"]
  28.         }
  29.       ]
  30.     }
  31.   ]
  32. }

HTTP listener with path-based routing

Ingress Gateway - 图7

Ingress Gateway - 图8

Set up a HTTP listener on an ingress gateway named “us-east-ingress” to proxy traffic to a virtual service named “api”.

HCL

Ingress Gateway - 图9

  • HCL
  • Kubernetes YAML
  • JSON
  1. Kind = "ingress-gateway"
  2. Name = "us-east-ingress"
  4. Listeners = [
  5.   {
  6.     Port     = 80
  7.     Protocol = "http"
  8.     Services = [
  9.       {
  10.         Name = "api"
  11.       }
  12.     ]
  13.   }
  14. ]
  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: IngressGateway
  3. metadata:
  4.   name: us-east-ingress
  5. spec:
  6.   listeners:
  7.     - port: 80
  8.       protocol: http
  9.       services:
  10.         - name: api
  1. {
  2.   "Kind": "ingress-gateway",
  3.   "Name": "us-east-ingress",
  4.   "Listeners": [
  5.     {
  6.       "Port": 80,
  7.       "Protocol": "http",
  8.       "Services": [
  9.         {
  10.           "Name": "api"
  11.         }
  12.       ]
  13.     }
  14.   ]
  15. }

The api service is not an actual registered service. It exist as a “virtual” service for L7 configuration only. A service-router (ServiceRouter on Kubernetes) is defined for this virtual service which uses path-based routing to route requests to different backend services:

Ingress Gateway - 图10

Ingress Gateway - 图11

HCL

Ingress Gateway - 图12

  • HCL
  • Kubernetes YAML
  • JSON
  1. Kind = "service-router"
  2. Name = "api"
  3. Routes = [
  4.   {
  5.     Match {
  6.       HTTP {
  7.         PathPrefix = "/billing"
  8.       }
  9.     }
  11.     Destination {
  12.       Service = "billing-api"
  13.     }
  14.   },
  15.   {
  16.     Match {
  17.       HTTP {
  18.         PathPrefix = "/payments"
  19.       }
  20.     }
  22.     Destination {
  23.       Service = "payments-api"
  24.     }
  25.   }
  26. ]
  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: ServiceRouter
  3. metadata:
  4.   name: api
  5. spec:
  6.   routes:
  7.     - match:
  8.         http:
  9.           pathPrefix: '/billing'
  10.       destination:
  11.         service: billing-api
  12.     - match:
  13.         http:
  14.           pathPrefix: '/payments'
  15.       destination:
  16.         service: payments-api
  1. {
  2.   "Kind": "service-router",
  3.   "Name": "api",
  4.   "Routes": [
  5.     {
  6.       "Match": {
  7.         "HTTP": {
  8.           "PathPrefix": "/billing"
  9.         }
  10.       },
  11.       "Destination": {
  12.         "Service": "billing-api"
  13.       }
  14.     },
  15.     {
  16.       "Match": {
  17.         "HTTP": {
  18.           "PathPrefix": "/payments"
  19.         }
  20.       },
  21.       "Destination": {
  22.         "Service": "payments-api"
  23.       }
  24.     }
  25.   ]
  26. }

Available Fields

Ingress Gateway - 图13

Ingress Gateway - 图14

  • Kind - Must be set to ingress-gateway

  • Name (string: <required>) - Set to the name of the gateway being configured.

  • Namespace (string: "default")

    Enterprise

    - 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 or will default to the default namespace.

  • Meta (map<string|string>: nil) - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.

  • TLS (TLSConfig: <optional>) - TLS configuration for this gateway.

    • 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<IngressListener>: <optional>)) - A list of listeners that the ingress gateway should setup, uniquely identified by their port number.

    • Port (int: 0) - The port on which the ingress listener should receive traffic. The port will be bound to the IP address that was specified in the -address flag when starting the gateway. Note: The ingress listener port must not conflict with the health check port specified in the -address flag.

    • Protocol (string: "tcp") - The protocol associated with the listener. One of tcp, http, http2, or grpc.

    • 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. 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: "")

        Enterprise

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

ACLs

Configuration entries may be protected by 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.