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.

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

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

Note: 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
Gateway CR with static IP assignment
Gateway CR with both static IP configs and parametersRef
Gateway CR with invalid static IP
Gateway CR allowing HTTPRoutes
Gateway CR allowing L4Route

Gateway CR with dynamic IP address assigned through F5BnkGateway¶

apiVersion: k8s.f5net.com/v1
kind: F5BnkGateway
metadata:
 name: f5-bnkgateway
 namespace: default  #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: default  #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: default  #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