Gateway and Gateway Class
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,
Gateway, the flag
servicesAPI in the
values.yaml must be set to true.
Installing Gateway Class and Gateway CRD
AKO primarily uses
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 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).
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.
.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.
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-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:
IPAddressentry after the Gateway is assigned an IP from Avi
IPAddressentry 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
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
hostnamefield 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.
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
|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|