Gateway

Overview

The Kubernetes Gateway API’s Gateway custom resource (CR) defines how external traffic should be routed into a Kubernetes cluster.

Overview

The Kubernetes Gateway API’s Gateway custom resource (CR) defines how external traffic should be routed into a Kubernetes cluster.

Key aspects of the Gateway CR include:

  • Gateway Resource: The Gateway CR specifies a network gateway that manages and configures traffic routing at the edge of a Kubernetes cluster. It acts as the entry point for external traffic.

  • Configuration: It allows you to define how incoming requests should be processed and forwarded to the appropriate services within the cluster. This includes setting up listeners on specific ports and protocols.

  • Integration: The Gateway CR works in conjunction with other resources such as HTTPRoute, GRPCRoute, and L4Route to define routing rules and manage traffic flow based on different criteria.

The Gateway CR provides a flexible and scalable way to handle incoming traffic and ensures that it is properly directed to the right services within the Kubernetes cluster.

Note

Perform custom resource (CR) operations only when the controller is in a running state.

CR Parameters

The table below provides the description and implementation details of Gateway CR spec parameters.

Parameters

Description

Implementation details

addresses.type

Specifies the type of address. For example, IPAddress

addresses.value

Specifies a static IP address (IPv4/IPv6).

gatewayClassName

Specifies the name of a GatewayClass. For example, f5-gateway-class

infrastructure.parametersRef

Specifies a reference to a resource that contains the configuration parameters corresponding to the Gateway.

CNE controller support GatewaySettings resource here.

infrastructure.parametersRef.group

Specifies the group of the referent. For example, k8s.f5net.com

infrastructure.parametersRef.kind

Specifies the kind of the referent. For example, GatewaySettings

infrastructure.parametersRef.name

Specifies the name of the referent. For example, my-gateway

infrastructure.annotations

Defines custom annotations that provide additional configuration to the BNK infrastructure. For example, k8s.f5net.com

infrastructure.annotations."k8s.f5.com/snat-type": "None"

Allows source address translation for Gateway API resources (HTTPRoute, L4Route or GRPCRoute). Possible values:
- Automap: Changes the source IP address to be TMM’s IP address.
- None: The source IP address is not changed.
Note: The default behaviour of the system is Automap.

infrastructure.annotations.semantic_cache

Enables or disables semantic caching for incoming user requests.

infrastructure.annotations.semantic_cache_ip_port

The IP address and port of the ModelCache service (supports IPv4/IPv6).

infrastructure.annotations.semantic_cache_recv_timeout

The maximum duration in milliseconds that the BNK Gateway will wait for a response before the timeout.

listeners.allowedRoutes.kinds.group

Specifies the group of the route.

Group field is optional for attaching HTTPRoute and GRPCRoute routes to the listener.
Group field is mandatory for attaching L4Route routes to the listener. Value must be gateway.k8s.f5net.com

addresses.type

Specifies the type of address. For example, IPAddress

addresses.value

Specifies a static IP address (IPv4/IPv6).

gatewayClassName

Specifies the name of a GatewayClass. For example, f5-gateway-class

infrastructure.parametersRef

Specifies a reference to a resource that contains the configuration parameters corresponding to the Gateway.

CNE controller support GatewaySettings resource here.

infrastructure.parametersRef.group

Specifies the group of the referent. For example, k8s.f5net.com

infrastructure.parametersRef.kind

Specifies the kind of the referent. For example, GatewaySettings

infrastructure.parametersRef.name

Specifies the name of the referent. For example, my-gateway

infrastructure.annotations

Defines custom annotations that provide additional configuration to the BNK infrastructure. For example, k8s.f5net.com

infrastructure.annotations."k8s.f5.com/snat-type": "None"

Allows source address translation for Gateway API resources (HTTPRoute, L4Route or GRPCRoute). Possible values:
- Automap: Changes the source IP address to be TMM’s IP address.
- None: The source IP address is not changed.
Note: The default behaviour of the system is Automap.

infrastructure.annotations.semantic_cache

Enables or disables semantic caching for incoming user requests.

infrastructure.annotations.semantic_cache_ip_port

The IP address and port of the ModelCache service (supports IPv4/IPv6).

infrastructure.annotations.semantic_cache_recv_timeout

The maximum duration in milliseconds that the BNK Gateway will wait for a response before the timeout.

listeners.allowedRoutes.kinds.group

Specifies the group of the route.

Group field is optional for attaching HTTPRoute and GRPCRoute routes to the listener.
Group field is mandatory for attaching L4Route routes to the listener. Value must be gateway.k8s.f5net.com

listeners.allowedRoutes.kinds.kind

Specifies the kind of the route. For example, HTTPRoute

Supported route kinds are, HTTPRoute, GRPCRoute and L4Route

listeners.allowedRoutes.namespaces.from

Specifies the namespace from which routes are selected for this Gateway.

Supported values for this: All, Same, and Selector

listeners.name

Specifies the name of the listener. For example, http

listeners.port

Specifies the port on which a listener is configured to listen to the incoming traffic. For example, 8080

listeners.protocol

Specifies the protocol being used by the listener. For example, HTTP

Supported protocols are TCP, UDP, HTTP, HTTPS. Note: TLS is supported if GatewayAPI CRD version 1.5 is used.

listeners.tls

Specifies TLS configuration for the Listener. This field is required if the Protocol field is “HTTPS”

listeners.tls.certificateRefs

Specifies reference to TLS certificates and private keys.

CNE controller only supports Secret resource of type kubernetes.io/tls in certificateRefs

listeners.tls.group

Specifies the group of the referent.

listeners.tls.kind

Specifies the kind of the referent. For example, Secret

listeners.tls.name

Specifies the name of the referent. For example, tls-secrets

listeners.tls.namespace

Specifies the namespace of the referenced object. When unspecified, this refers to the local namespace of the Gateway.

listeners.tls.options

Provides additional TLS settings. Specify f5.com/ciphers to provide cipher list format defined by OpenSSL, and f5.com/minTLSVersion to specify the minimum TLS version allowed (1.2 or 1.3).

Options are a list of key/value pairs to enable extended TLS configuration for each implementation. For example, configuring the minimum TLS version or supported cipher suites. A set of common keys MAY be defined by the API in the future. To avoid any ambiguity, implementation-specific definitions MUST use domain-prefixed names, such as example.com/my-custom-option. Un-prefixed names are reserved for key names defined by Gateway API.

Note

  • You can refer to Gateway for more details.

  • It is recommended to create separate listeners in Gateway configs for different Route kinds i.e HTTPRoute, GRPCRoute and L4Route.

  • Multiple HTTPRoute routes can be attached to one Gateway listener.

  • It is recommended to attach only one GRPCRoute and L4Route route per Gateway listener. Also, attach only one backendRef to GRPCRoute and L4Route routes.

  • Gateway listener TLS config is supported with attached HTTPRoute and GRPCRoute routes that handles client side SSL configurations.

  • Delete and then recreate the Gateway if you want to modify the existing infrastructure.parametersRef.name; this clears old VIP allocations and provisions new VIPs in accordance with the updated parameters reference.

Prerequisites

Make sure:

  • BNK is deployed and F5 CNE controller is running.

  • The GatewayClass CR is configured.

Gateway CR Status

Gateway condition - Accepted

conditions.status

conditions.reason

description

Unknown

Pending

Initial state - Waiting for controller

True

- Accepted
- ListenersNotValid

- Gateway is accepted
- Gateway has minimum of one valid listener

False

- ListenersNotValid
- UnsupportedAddress

- Gateway has no valid listeners
- Address type is not supported

Gateway condition - Programmed

conditions.status

conditions.reason

description

Unknown

Pending

Initial state - Waiting for controller

True

Programmed

Gateway is programmed.

False

- Invalid
- AddressNotAssigned
- AddressNotUsable

- Gateway has no valid listeners
- Addresses are not assigned
- Requested IP reservation is out of CIDR range

Listener condition - Accepted

conditions.status

conditions.reason

description

True

Accepted

Listener is accepted.

False

- UnsupportedProtocol
- InvalidCertificateRef

- Listener protocol not supported
- TLS CertificateRef is invalid or does not exist.

Listener condition - Programmed

conditions.status

conditions.reason

description

True

Programmed

Listener is programmed.

False

Invalid

- Listener protocol not supported
- Unsupported route kinds for protocol
- L4Route not in group
- TLS CertificateRef is invalid or does not exist

Listener condition - ResolvedRefs

conditions.status

conditions.reason

description

True

ResolvedRefs

All references are resolved.

False

- RefNotPermitted
- InvalidRouteKinds
- InvalidCertificateRef

- Listener protocol not supported - Unsupported route kinds for protocol or L4Route not in group
- TLS CertificateRef is invalid or does not exist

Description from above tables may not reflect exactly same under the status section of CR.

Sample CRs

This section lists the sample CRs of use cases available to apply Gateway CR. Each sample includes the parameters you need to apply the CR.

Note

The listeners.allowedRoutes.kinds.group parameter must be added for L4Route.

Gateway CR with dynamic IP address assigned through GatewaySettings

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: f5-http-gateway
 namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1   
 gatewayClassName: f5-gateway-class
 listeners:
 - name: http
   protocol: HTTP
   port: 80
   allowedRoutes:
     namespaces:
       from: "All"
     kinds:
     - kind: HTTPRoute

In the above configuration, Gateway receives the IP address dynamically from the range specified in GatewaySettings CR (One for each IPv4 and IPv6).

Note: When a Gateway CR is updated with a user-specified GatewaySpecAddress, delete the old Gateway with Dynamic IP and recreate a new Gateway with Static IP (user-specified IP).

kubectl get gateways f5-http-gateway -n gateway-infra -o jsonpath='{.status.addresses}'
[{"type":"IPAddress","value":"11.11.11.1"},{"type":"IPAddress","value":"2002::11:11:11:101"}]

Gateway CR with static IP assignment

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  addresses:
  - type: "IPAddress"
    value: 11.11.11.165
  - type: "IPAddress"
    value: 2002::11:11:11:155
  gatewayClassName: f5-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: HTTPRoute

In the above configuration, which does not include infrastructure.parametersRef referring to GatewaySettings the gateway receives the same static IP addresses provided in the addresses field.

kubectl get gateways f5-http-gateway -n gateway-infra -o jsonpath='{.status.addresses}'
[{"type":"IPAddress","value":"2002::11:11:11:155"},{"type":"IPAddress","value":"11.11.11.165"}]

Gateway CR with both static IP configs and parametersRef

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1  
  addresses:
  - type: "IPAddress"
    value: 11.11.11.2
  gatewayClassName: f5-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: HTTPRoute

This configuration provides a static IPv4 address (11.11.11.2) alongside infrastructure.parametersRef. If the static IP falls within the CIDR range defined in the GatewaySettings CR, the gateway uses that address.

kubectl get gateways f5-http-gateway -n gateway-infra -o jsonpath='{.status.addresses}'
[{"type":"IPAddress","value":"11.11.11.2"}]

Gateway CR with invalid static IP

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1  
  addresses:
  - type: "IPAddress"
    value: 11.11.11.20
  gatewayClassName: f5-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: HTTPRoute

The above configuration does not include a valid static IP (11.11.11.20) specified in GatewaySettings CR CIDR range.

kubectl get gateways f5-http-gateway -n gateway-infra
NAME              CLASS              ADDRESS   PROGRAMMED   AGE
f5-http-gateway   f5-gateway-class             False        13s

Gateway CR allowing HTTPRoutes

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1  
  gatewayClassName: f5-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: HTTPRoute

Gateway CR allowing L4Route

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
   infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1  
  gatewayClassName: f5-gateway-class
  listeners:
  - name: tcp
    protocol: TCP
    port: 8000
    allowedRoutes:
      kinds:
      - kind: L4Route
        group: gateway.k8s.f5.com             # group is mandatory if route kind is specified as L4Route

Gateway CR with minimum TLS version and cipher suites

Gateway TLS configurations provide an options map to add additional TLS settings for client-side implementation-specific features.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: secure-gateway
  namespace: default
spec:
  gatewayClassName: f5-ingress
  listeners:
    # HTTP listener (standard, no TLS)
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All

    # HTTPS listener with OpenSSL cipher list format
    - name: https
      port: 443
      protocol: HTTPS
      hostname: "api.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: api-cert
            kind: Secret
            group: ""
        # Implementation-specific TLS options with OpenSSL cipher format
        options:
          # OpenSSL cipher list format: colon-separated, with modifiers (!, +, -)
          f5.com/ciphers: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK"
          f5.com/minTLSVersion: "1.2"

    # HTTPS listener with strict cipher suite
    - name: https-strict
      port: 8443
      protocol: HTTPS
      hostname: "admin.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: admin-cert
            kind: Secret
            group: ""
        options:
          # Strict ciphers for sensitive endpoints
          f5.com/ciphers: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:!aNULL:!eNULL:!EXPORT"
          f5.com/minTLSVersion: "1.3"

    # HTTPS listener with DEFAULT cipher suite excluding weak algorithms
    - name: https-default-secure
      port: 9443
      protocol: HTTPS
      hostname: "service.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: service-cert
            kind: Secret
            group: ""
        options:
          # Default ciphers excluding weak/obsolete algorithms
          f5.com/ciphers: "DEFAULT:!aNULL:!eNULL:!MD5:!3DES:!DES:!RC4:!IDEA:!SEED:!aDSS:!SRP:!PSK"