Gateway

The Kubernetes Gateway API’s Gateway Custom Resource (CR) is a crucial component that 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

As per the Gateway API community standard.

addresses.value

Specifies a static IP address (IPv4/IPv6).

As per the Gateway API community standard.

gatewayClassName

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

As per the Gateway API community standard.

infrastructure.parametersRef

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

CNE controller support F5BnkGateway resource here.

infrastructure.parametersRef.group

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

As per the Gateway API community standard.

infrastructure.parametersRef.kind

Specifies the kind of the referent. For example, F5BnkGateway

As per the Gateway API community standard.

infrastructure.parametersRef.name

Specifies the name of the referent. For example, f5-bnkgateway

As per the Gateway API community standard.

infrastructure.annotations

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

As per the Gateway API community standard.

infrastructure.annotations."k8s.f5.com/snat-type": "None" (2.2.1 and later)

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.

As per the Gateway API community standard.

infrastructure.annotations.semantic_cache

Enables or disables semantic caching for incoming user requests.

As per the Gateway API community standard.

infrastructure.annotations.semantic_cache_ip_port

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

As per the Gateway API community standard.

infrastructure.annotations.semantic_cache_recv_timeout

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

As per the Gateway API community standard.

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 with the Routes are selected for this Gateway.

Supported values for this: All, Same Not supported value: Selector

listeners.name

Specifies the name of the listener. For example, http

As per the Gateway API community standard.

listeners.port

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

As per the Gateway API community standard.

listeners.protocol

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

Supported protocols are TCP, UDP, HTTP, HTTPS

listeners.tls

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

As per the Gateway API community standard.

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.

As per the Gateway API community standard.

listeners.tls.kind

Specifies the kind of the referent. For example, Secret

As per the Gateway API community standard.

listeners.tls.name

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

As per the Gateway API community standard.

listeners.tls.namespace

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

As per the Gateway API community standard.

Note

  • GatewayBackendTLS, AllowedListeners and Listener/Hostname parameters are not supported.

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

  • BackendTLSPolicy is not supported.

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

  • The product BNK (DPU) is installed and the F5 controller is running.

  • The F5SPKVlan CR is configured.

  • 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. In each sample, necessary parameters for applying a CR is added.

Note

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

Gateway CR with dynamic IP address assigned through F5BnkGateway

apiVersion: k8s.f5net.com/v1
kind: F5BnkGateway
metadata:
 name: f5-bnkgateway
 namespace: f5-bnk  #same namespace in which f5-cne-controller is deployed
spec:
 ingressConfig:
   defaultListenerNetworks:
     - name: "default_ipv4"
       ipv4BaseCidr: "11.11.11.0/24"
       startAddress: "11.11.11.1"
       endAddress: "11.11.11.10"
     - name: "default_ipv6"
       ipv6BaseCidr: "2002::11:11:11:100/112"
       startAddress: "2002::11:11:11:101"
       endAddress: "2002::11:11:11:110"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: f5-http-gateway
 namespace: gateway-infra
spec:
 infrastructure:
   parametersRef:
     group: k8s.f5net.com
     kind: F5BnkGateway
     name: f5-bnkgateway
 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 F5BnkGateway 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 F5BnkGateway 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: k8s.f5net.com/v1
kind: F5BnkGateway
metadata:
  name: f5-bnkgateway
  namespace: f5-bnk  #same namespace in which f5-cne-controller is deployed
spec:
   ingressConfig:
    defaultListenerNetworks:
      - name: "default_ipv4"
        ipv4BaseCidr: "11.11.11.0/24"
        startAddress: "11.11.11.1"
        endAddress: "11.11.11.10"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: k8s.f5net.com
      kind: F5BnkGateway
      name: f5-bnkgateway
  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

In the above configuration, static IPv4 (11.11.11.2) is provided along with infrastructure.parametersRef. In this case, if the provided static IP is within the range of IPs from F5BnkGateway CR then that IP is valid and it gets assigned to gateway. Static IPv6 address is not provided, so it gets assigned dynamically.

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: k8s.f5net.com/v1
kind: F5BnkGateway
metadata:
  name: f5-bnkgateway
  namespace: f5-bnk  #same namespace in which f5-cne-controller is deployed
spec:
   ingressConfig:
    defaultListenerNetworks:
      - name: "default_ipv4"
        ipv4BaseCidr: "11.11.11.0/24"
        startAddress: "11.11.11.1"
        endAddress: "11.11.11.10"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: k8s.f5net.com
      kind: F5BnkGateway
      name: f5-bnkgateway
  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 F5BnkGateway 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.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: k8s.f5net.com
      kind: F5BnkGateway
      name: f5-bnkgateway
  gatewayClassName: f5-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: HTTPRoute

Gateway CR allowing L4Route

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: k8s.f5net.com
      kind: F5BnkGateway
      name: f5-bnkgateway
  gatewayClassName: f5-gateway-class
  listeners:
  - name: tcp
    protocol: TCP
    port: 8000
    allowedRoutes:
      kinds:
      - kind: L4Route
        group: gateway.k8s.f5net.com             # group is mandatory if route kind is specified as L4Route