»Ingress Gateway Beta

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 for more information.

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>.*, 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:

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:

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") -

    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.

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

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

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.