Gateway resource configuration reference

This topic provides full details about the Gateway resource.

Introduction

A Gateway is an instance of network infrastructure that determines how service traffic should be handled. A Gateway contains one or more listeners that bind to a set of IP addresses. An HTTPRoute or TCPRoute can then attach to a gateway listener to direct traffic from the gateway to a service.

Gateway instances derive their configurations from the GatewayClass resource, which acts as a template for individual Gateway deployments. Refer to GatewayClass for additional information.

Specify the following parameters to declare a Gateway:

Configuration model

The following outline shows how to format the configurations in the Gateway object. Click on a property name to view details about the configuration.

• gatewayClassName: string | required
• listeners: array of objects | required
  • allowedRoutes: object | required
    • namespaces: object | required
      • from: string | required
      • selector: object | required if from is configured to selector
        • matchExpressions: array of objects | required if matchLabels is not configured
          • key: string | required if matchExpressions is declared
          • operator: string | required if matchExpressions is declared
          • values: array of strings | required if matchExpressions is declared
        • matchLabels: map of strings | required if matchExpressions is not configured
  • hostname: string | required
  • name: string | required
  • port: integer | required
  • protocol: string | required
  • tls: object | required if protocol is set to HTTPS
    • certificateRefs: array or objects | required if tls is declared
      • name: string | required if certificateRefs is declared
      • namespace: string | required if certificateRefs is declared
    • mode: string | required if certificateRefs is declared
    • options: map of strings | optional

Specification

This topic provides details about the configuration parameters.

gatewayClassName

Specifies the name of the GatewayClass resource used for the Gateway instance. Unless you are using a custom GatewayClass, this value should be set to consul.

• Type: string
• Required: required

listeners

Specifies the listeners associated with the Gateway. At least one listener must be specified. Each listener within a Gateway must have a unique combination of hostname, port, and protocol.

• Type: array of objects
• Required: required

listeners.allowedRoutes

Specifies a namespace object that defines the types of routes that may be attached to a listener.

• Type: object
• Required: required

listeners.allowedRoutes.namespaces

Determines which routes are allowed to attach to the listener. Only routes in the same namespace as the Gateway may be attached by default.

• Type: string
• Required: optional
• Default: Same namespace as the parent Gateway

listeners.allowedRoutes.namespaces.from

Determines which namespaces are allowed to attach a route to the Gateway. You can specify one of the following strings:

• All: Routes in all namespaces may be attached to the Gateway.
• Same (default): Only routes in the same namespace as the Gateway may be attached.
• Selector: Only routes in namespaces that match the selector may be attached.

This parameter is required.

listeners.allowedRoutes.namespaces.selector

Specifies a method for selecting routes that are allowed to attach to the listener. The Gateway checks for namespaces in the network that match either a regular expression or a label. Routes from the matching namespace are allowed to attach to the listener.

You can configure one of the following objects:

• matchExpressions
• matchLabels

This field is required when from is configured to Selector.

listeners.allowedRoutes.namespaces.selector.matchExpressions

Specifies an array of requirements for matching namespaces. If a match is found, then routes from the matching namespace(s) are allowed to attach to the Gateway. The following table describes members of the matchExpressions array:

In the following example, routes in namespaces that contain foo and bar are allowed to attach routes to the Gateway.

namespaceSelector:
  matchExpressions:
  - key: kubernetes.io/metadata.name
    operator: In
    values:
    - foo
    - bar

Refer to Labels and Selectors in the Kubernetes documentation for additional information about matchExpressions.

listeners.allowedRoutes.namespaces.selector.matchLabels

Specifies an array of labels and label values. If a match is found, then routes with the matching label(s) are allowed to attach to the Gateway. This selector can contain any arbitrary key/value pair.

In the following example, routes in namespaces that have a bar label are allowed to attach to the Gateway.

namespaceSelector:
    matchLabels:
      foo: bar

Refer to Labels and Selectors in the Kubernetes documentation for additional information about labels.

listeners.hostname

Specifies the listener's hostname.

• Type: string
• Required: required

listeners.name

Specifies the listener's name.

• Type: string
• Required: required

listeners.port

Specifies the port number that the listener attaches to.

• Type: integer
• Required: required

listeners.protocol

Specifies the protocol the listener communicates on.

• Type: string
• Required: required

Allowed values are TCP, HTTP, or HTTPS

Consul on Kubernetes translates HTTP and HTTPS listeners to the http protocol and TCP listeners to the tcp protocol in the API gateway configuration entry. To serve HTTP/2 or gRPC traffic, set the listener protocol to HTTP or HTTPS and add the api-gateway.consul.hashicorp.com/listener-<sectionName>-protocol annotation to the Gateway to select the http2 or grpc protocol for the listener.

listeners.tls

Specifies the tls configurations for the Gateway. The tls object is required if protocol is set to HTTPS. The object contains the following fields:

The following keys for options are available

• api-gateway.consul.hashicorp.com/tls_min_version
• api-gateway.consul.hashicorp.com/tls_max_version
• api-gateway.consul.hashicorp.com/tls_cipher_suites

In the following example, tls settings are configured to use a secret named consul-server-cert in the same namespace as the Gateway and the minimum tls version is set to TLSv1_2.

tls:
  certificateRefs:
  - name: consul-server-cert
    group: ""
    kind: Secret
  mode: Terminate
  options:
    api-gateway.consul.hashicorp.com/tls_min_version: "TLSv1_2"

To terminate HTTPS without a certificateRefs entry, add the consul.hashicorp.com/tls-enabled annotation to the Gateway. The gateway uses its Consul service mesh leaf certificate for listeners that do not reference a certificate. Kubernetes Gateway API v1.4 and later CRDs require a Terminate listener to set either certificateRefs or options, so set an options key when you omit certificateRefs. In the following example, the tls settings do not reference a certificate:

tls:
  mode: Terminate
  options:
    api-gateway.consul.hashicorp.com/tls_min_version: "TLS_AUTO"

Example cross-namespace certificateRef

The following example creates a Gateway named example-gateway in namespace gateway-namespace (lines 2-4). The gateway has a certificateRef in namespace secret-namespace (lines 16-18). The reference is allowed because the ReferenceGrant configuration, named reference-grant in namespace secret-namespace (lines 24-27), allows Gateways in gateway-namespace to reference Secrets in secret-namespace (lines 31-35).

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: gateway-namespace
spec:
  gatewayClassName: consul
  listeners:
  - protocol: HTTPS
    port: 443
    name: https
    allowedRoutes:
      namespaces:
        from: Same
    tls:
      certificateRefs:
        - name: cert
          namespace: secret-namespace
          group: ""
          kind: Secret
---

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: reference-grant
  namespace: secret-namespace
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: Gateway
    namespace: gateway-namespace
    to:
    - group: ""
      kind: Secret
      name: cert

Annotations

You can add the following annotations to the Gateway resource metadata to configure Consul-specific gateway behavior.

consul.hashicorp.com/tls-enabled

Enables Consul-managed TLS termination for the Gateway. When set to "true", Consul on Kubernetes sets TLS.Enabled to true in the translated API gateway configuration entry. Listeners that do not reference a certificate in tls.certificateRefs terminate HTTPS with the gateway's Consul service mesh leaf certificate. Consul issues and rotates the certificate automatically.

The leaf certificate includes wildcard DNS subject alternative names (SANs), such as *.api-gateway.consul, that match the <service>.api-gateway.<domain> names that Consul registers for services bound to the gateway. Refer to Terminate HTTPS with Consul-managed certificates for more information.

• Type: string
• Required: optional
• Allowed values: "true". Any other value, or omitting the annotation, leaves TLS.Enabled set to false.

In the following example, the Gateway terminates HTTPS on port 8443 with the Consul service mesh leaf certificate:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  annotations:
    consul.hashicorp.com/tls-enabled: "true"
spec:
  gatewayClassName: consul
  listeners:
  - name: https
    protocol: HTTPS
    port: 8443
    tls:
      mode: Terminate
      options:
        api-gateway.consul.hashicorp.com/tls_min_version: "TLS_AUTO"
    allowedRoutes:
      namespaces:
        from: All

api-gateway.consul.hashicorp.com/default-* upstream limits

Configures gateway-wide default upstream circuit-breaker limits and passive health checks for every backend service that routes attached to the Gateway target. Consul on Kubernetes translates the annotations into the Defaults field of the API gateway configuration entry. Passive health checks configure Envoy outlier detection, which removes backend service instances that return consecutive errors from the gateway's load balancing pool.

These annotations are supported on Gateway resources in the gateway.networking.k8s.io API group.

The following table describes the supported annotations:

Consul on Kubernetes ignores an annotation when the value is not valid, such as a negative number, a percentage greater than 100, or a malformed duration. The controller logs a message that identifies the ignored annotation, and the corresponding field remains unset.

To override the defaults for a specific backend service, attach a RouteUpstreamLimitsFilter to the backend in an HTTPRoute. Each circuit-breaker limit in the filter overrides the corresponding default. A passive health check in the filter replaces the default passive health check for that backend service.

• Type: string
• Required: optional

In the following example, the Gateway limits each backend service to 40 connections and ejects a backend service instance after five consecutive 5xx errors:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  annotations:
    api-gateway.consul.hashicorp.com/default-max-connections: "40"
    api-gateway.consul.hashicorp.com/default-max-pending-requests: "80"
    api-gateway.consul.hashicorp.com/default-max-concurrent-requests: "160"
    api-gateway.consul.hashicorp.com/default-passive-health-check-interval: "15s"
    api-gateway.consul.hashicorp.com/default-passive-health-check-max-failures: "5"
    api-gateway.consul.hashicorp.com/default-passive-health-check-max-ejection-percent: "20"
spec:
  gatewayClassName: consul
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All

api-gateway.consul.hashicorp.com/listener-<sectionName>-protocol

Selects the Consul protocol for a specific listener. Replace <sectionName> in the annotation key with the name of the listener. Consul on Kubernetes sets the annotation value as the Listeners[].Protocol field of the corresponding listener in the API gateway configuration entry. Each listener reads only its own annotation, so listeners on the same Gateway can use different protocols.

Use this annotation to serve HTTP/2 or gRPC traffic. When you set the value to http2 or grpc, the gateway accepts HTTP/2 connections from clients and uses HTTP/2 for the connection to the backend service. Set the listener protocol field to HTTP or HTTPS, and bind an HTTPRoute to the listener.

The annotation is supported on Gateway resources in the gateway.networking.k8s.io API group.

• Type: string
• Required: optional
• Allowed values: http, http2, grpc, or tcp. Values are not case sensitive.
• Default: When the annotation is not set, Consul on Kubernetes derives the protocol from the listener protocol field.

Consul on Kubernetes ignores the annotation when the value is not one of the allowed values and uses the protocol derived from the listener protocol field. When the <sectionName> in the annotation key does not match the name of any listener, the controller logs a warning and ignores the annotation.

In the following example, the grpc-listener listener uses the grpc protocol, the h2-listener listener uses the http2 protocol, and the http-listener listener uses the default http protocol:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  annotations:
    api-gateway.consul.hashicorp.com/listener-grpc-listener-protocol: "grpc"
    api-gateway.consul.hashicorp.com/listener-h2-listener-protocol: "http2"
spec:
  gatewayClassName: consul
  listeners:
  - name: http-listener
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All
  - name: grpc-listener
    protocol: HTTP
    port: 9080
    allowedRoutes:
      namespaces:
        from: All
  - name: h2-listener
    protocol: HTTP
    port: 9090
    allowedRoutes:
      namespaces:
        from: All