Gateway API - v1alpha1

Layer 4 Service integration with Gateway APIs v1alpha1 is supported. In order to enable the feature, and allow AKO to watch for Gateway API objects, GatewayClass and Gateway, the flag servicesAPI in the values.yaml must be set to true.

Installing Gateway Class and Gateway CRD

AKO primarily uses GatewayClass and Gateway CRDs for the Gateway API implementation and integration with Layer 4 Services. These GatewayClass and Gateway CRDs must be installed on the cluster running AKO. CRDs can be installed on the cluster through Helm, like the other CRDs. For more information, see Install Avi Kubernetes Operator.

Gateway APIs and Service Objects

AKO allows users to expose Kubernetes/ OpenShift services outside the cluster using Gateway and Gateway Class constructs. AKO creates one Layer-4 NSX Advanced Load Balancer virtual service per Gateway object, and configures the back end Services as distinct NSX Advanced Load Balancer Pools. The Gateway object acts as an overlay over Service objects (of type ClusterIP or NodePort), the same way an Ingress is implemented for Layer7. This overlay allows the Gateway to obtain a VIP, which is further shared by backend Services.

Note:

Services of type LoadBalancer will continue creating dedicated Layer4 virtual services.

GatewayClass

GatewayClass aggregates a group of Gateway objects, similar to IngressClass, which aggregates a group of Ingress objects. GatewayClasses formalize types of load balancing implementations which can be different for different load balancing vendors (NSX Advanced Load Balancer, Nginx, HAProxy, and so on) or can point to different load balancing parameters for a single load balancing vendor (through the parametersRef key).

AKO identifies GatewayClasses that point to ako.vmware.com/avi-lb as the .spec.controller value, in the GatewayClass object. A sample GatewayClass object can look as shown below:

apiVersion: networking.x-k8s.io/v1alpha1
kind: GatewayClass
metadata:
  name: avi-gateway-class
spec:
  controller: ako.vmware.com/avi-lb
  parametersRef:
    group: ako.vmware.com
    kind: AviInfraSetting
    name: my-infrasetting

It is important that the .spec.controller value specified MUST match ako.vmware.com/avi-lb for AKO to honour the GatewayClass and the corresponding Gateway objects.

The .spec.parametersRef allows users to point to AKO’s AviInfraSetting Custom Resource (cluster-scoped CRD), to fine tune specific load balancing parameters like the VIP network, Service Engine Group, and so on. For more information, see Setting up Routing Rules using CRDs.

Gateway

The Gateway object provides a way to configure multiple Services as backends to the Gateway using label matching. The labels are specified as constant key-value pairs, the keys being ako.vmware.com/gateway-namespace and ako.vmware.com/gateway-name. The values corresponding to these keys must match the Gateway namespace and name respectively, for AKO to consider the Gateway valid. In case any one of the label keys are not provided as part of matchLabels OR the namespace/name provided in the label values do no match the actual Gateway namespace/name, AKO will consider the Gateway invalid.

kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: my-gateway
  namespace: blue
spec:
  gatewayClassName: avi-lb
  listeners:
  - protocol: TCP
    port: 80
    routes:
      selector:
        matchLabels:
          ako.vmware.com/gateway-namespace: blue
          ako.vmware.com/gateway-name: my-gateway
      group: v1
      kind: Service
  - protocol: TCP
    port: 8081
    routes:
      selector:
        matchLabels:
          ako.vmware.com/gateway-namespace: blue
          ako.vmware.com/gateway-name: my-gateway
      group: v1
      kind: Service

This Gateway object would correspond to a single Layer 4 virtual service in NSX Advanced Load Balancer, with two TCP ports (80, 8081) exposed through the L4 virtual service.

You can also configure a user-preferred static IPv4 address in the Gateway Object using the .spec.addresses field as shown below:

 spec:
   addresses:
   - type: IPAddress
     value: 10.10.10.11

This configures the Layer 4 virtual service with a static IP as provided in the Gateway Object. AKO only supports assigning a single IPv4 address to the Layer 4 virtual service.

Updating preferred virtual IPs bound to a particular virtual service is not permitted in NSX Advanced Load Balancer. To update the user-preferred IP, it is required to re-create the Gateway object, failing which AKO throws an error. The following transition cases must be kept in mind, and for these, an explicit Gateway re-create with changed configuration is required:

Updating IPAddress value, from 10.10.10.11 to 10.10.10.22
Adding IPAddress entry after the Gateway is assigned an IP from NSX Advanced Load Balancer
Removing IPAddress entry after the Gateway is assigned an IP from NSX Advanced Load Balancer

Recreating the Gateway object does the following:

Deletes the Layer 4 virtual service in NSX Advanced Load Balancer
Frees up the applied virtual IP
Re-creates the virtual service with the intended configuration

Service

Matching Gateways with backend Services through label selection, requires Services to have the same Labels as shown in the example below:

apiVersion: v1
kind: Service
metadata:
  name: avisvc-advlb
  namespace: blue
  labels:
    ako.vmware.com/gateway-name: my-gateway
    ako.vmware.com/gateway-namespace: blue
spec:
  type: LoadBalancer
  ports:
  - port: 8081
    name: eighty-eighty-one
    targetPort: 8080
    protocol: TCP
  selector:
    app: avi-server-one
---
apiVersion: v1
kind: Service
metadata:
  name: avisvc-advlb
  namespace: red
  labels:
    ako.vmware.com/gateway-name: my-gateway
    ako.vmware.com/gateway-namespace: blue
spec:
  type: LoadBalancer
  ports:
  - port: 80
    name: eighty-eighty
    targetPort: 8080
    protocol: TCP
  selector:
    app: avi-server-two

Each Service with the appropriate labels, corresponds to a single NSX Advanced Load Balancer Pool.

Note:

The Service namespace might or might not be in the same namespace as that of the parent Gateway.

Configuring FQDN for Gateway Listeners/Backend Services

While using the Service APIs, Fully Qualified Domain Names (FQDN) can be configured for Services that are exposed through the Gateway object in the following two ways (in this order of precedence):

Using the hostname field in the Gateway. A hostname can be configured on an individual Gateway listeners as shown below:
```
 spec:
   gatewayClassName: avi-lb
   listeners:
   — protocol: TCP
     port: 80
     hostname: svc.example.com
     routes:
       selector:
         matchLabels:
           ako.vmware.com/gateway-namespace: blue
           ako.vmware.com/gateway-name: my-gateway
       group: v1
       kind: Service
```
From this example note that you can specify a FQDN svc.example.com for all TCP Services running on Port 80 that are programmed with the appropriate labels. This helps in collectively identifying Services through a single FQDN exposed by the Gateway.
Using autoFQDN
In case a hostname is not provided for a Gateway listener, AKO relies on the value provided by the autoFQDN field during installation. This can be set to either, default, flat or disabled. For more information on how to provide the autoFQDN functionality, see values.yaml.