Avi Kubernetes Operator Guide 1.11

AKO 1.13 1.12 1.11 1.10

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.
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.
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):
  1. 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.
  2. 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.

Content feedback and comments