Gateway and Gateway Class

Overview

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.
With AKO release 1.4.1, the CRDs can be installed on the cluster via Helm, like the other CRDs. To know more, refer to the Installation Guide

Gateway APIs and Service Objects

AKO allows exposing of Kubernetes/ OpenShift services outside the cluster using Gateway and Gateway Class constructs. AKO creates one Layer-4 Avi virtualservice per Gateway object, and configures the backend Services as distinct Avi Pools.

The Gateway object acts as an overlay over service objects (of type ClusterIP or NodePort), the same way an Ingress is implemented for Layer 7. This overlay allows the Gateway to obtain a VIP, which is further shared by the backend services.

Note: Services of type LoadBalancer, will still create dedicated Layer 4 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 (Avi/Nginx/HAProxy etc.), or can point to different load balancing parameters for a single load balancing vendor (via 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 etc. To know more, refer to the Setting up Routing Rules using CRDs article.

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 Avi, with two TCP ports (80, 8081) exposed via 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 Avi. 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 should 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 Avi
Removing IPAddress entry after the Gateway is assigned an IP from Avi

Recreating the Gateway object does the following:

Deletes the Layer 4 virtual service in Avi
Frees up the applied virtual IP
Re-creates the virtual service with the intended configuration

Service

Matching Gateways with backend Services via 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: ClusterIP
  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: ClusterIP
  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 Avi Pool.

Note: The Service namespace may or may 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 via 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 via 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, refer to values.yaml.

Document Revision History

Date	Change Summary
August 31, 2021	Updated the article for features Supported in AKO 1.5.1
April 28, 2021	Published the article for Gateway/ Gateway Class Supported in AKO 1.4.1