Gateway

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

• 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

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"

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/v1beta1
kind: Gateway
metadata:
  name: example-gateway
  namespace: gateway-namespace
spec:
  gatewayClassName: consul-api-gateway
  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/v1alpha2
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