Installation

Gateway API Objects

GatewayClass

GatewayClass aggregates a group of Gateway objects, similar to how IngressClass aggregates a group of Ingress objects. GatewayClasses formalizes types of load balancing implementations, which can be different for different load-balancing vendors (Avi/Nginx/HAProxy, and so on).

AKO

identifies GatewayClasses that point to

ako.vmware.com/avi-lb

as the

.spec.controllerName

value in the GatewayClass object.

A sample GatewayClass object looks as shown below:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: avi-lb
spec:
controllerName: "ako.vmware.com/avi-lb"

It is important that the

.spec.controllerName

value specified must match

ako.vmware.com/avi-lb

for

AKO

to honour the GatewayClass and corresponding Gateway API objects.

A GatewayClass named

avi-lb

will get installed as part of the helm install or upgrade when the user enables the Gateway API feature.

Gateway

The Gateway object represents an instance of a service-traffic handling infrastructure by binding Listeners to a set of IP addresses. The

AKO

validates the Gateway object, ensuring that the listeners are valid and then sets

ListenerConditionAccepted

to

true

. If at least one listener in the gateway is valid,

GatewayConditionAccepted

is set to

true

. It then verifies whether all the references specified in the gateway listeners are valid and exist, and then sets

ListenerConditionResolvedRefs

to

true

. Following this, the Gateway and its configuration are translated into a Parent VS. The listeners from the Gateway are mapped to service ports in the Parent VS, and secrets are configured as Certificates in the

Avi Load Balancer Controller

and will be referenced within the same Parent VS.

Once the VS creation is complete,

AKO

updates the Gateway status by setting

GatewayConditionProgrammed

to

true

, along with the VIP of the Parent VS. Further, it sets

ListenerConditionProgrammed

to

true

if the corresponding listener is successfully programmed.

The

AKO

created parent virtual service uses the name convention:

ako-gw-<cluster-name>--<namespace of the gateway>-<name of the gateway>-EVH

.

A sample Gateway object is shown below:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: my-gateway
spec:
gatewayClassName: avi-lb
listeners:
- name: foo-http
protocol: HTTP
port: 80
hostname: *.example.com
- name: bar-https
protocol: HTTPS
port: 443
hostname: *.example.com
tls:
certificateRefs:
- kind: Secret
group: ""
name: bar-example-com-cert

The above Gateway object would correspond to a single Layer 7 virtual service in the

Avi Load Balancer Controller

, with two ports (80, 443) exposed and a

sslKeyAndCertificate

created based on the secret

bar-example-com-cert

.

Starting with version 1.11.1,

AKO

only supports HTTP and HTTPS as protocol and Secret kind for certificateRefs.

Users can also configure a user-preferred static IPv4 address in the Gateway Object using the

.spec.addresses

field, as shown below. This would configure the Layer 7 virtual service with a static IP, as mentioned in the Gateway Object.

spec:
addresses:
- type: IPAddress
value: 10.1.1.10

Starting with

AKO

version 1.11.1, a single address of type IPAddress is supported. The Gateway must be re-created to update the address.

HTTPRoute

The HTTPRoute object provides a way to route HTTP requests. The

AKO

models a child virtual service based on this object. Starting with version 1.11.1,

AKO

supports match requests based on the hostname, path, and header specified. The filters to specify additional processing of the requests will be added as policy in the child virtual service by the

AKO

. The filters of type

RequestHeaderModifier

,

RequestRedirect

, and

ResponseHeaderModifier

are supported.

A sample HTTPRoute object is as shown below:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: my-http-app
spec:
parentRefs:
- name: my-gateway
hostnames:
- "foo.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /bar
backendRefs:
- name: my-service1
port: 8080
- filters:
- type: RequestHeaderModifier
requestHeaderModifier:
add:
 - name: my-header
   value: foo
matches:
- headers:
- type: Exact
name: magic
value: foo
path:
type: PathPrefix
value: /foo
backendRefs:
- name: my-service2
port: 8080
weight: 1
- name: my-service3
port: 8081
weight: 2

The above HTTPRoute object gets translated to two child virtual services in the

Avi Load Balancer Controller

as follows:

One child virtual service with match criteria as the path begins with
/bar
and a single Pool Group with a single pool.
Another child virtual service with match criteria as the path begins with
/foo
and includes a header named
magic
with value
foo
, a single Pool Group with two pools, and an HTTP Request policy to add
my header
with value
foo
to the HTTP request forwarded to the back-ends.

Hostnames are mandatory and can be prefixed with a wildcard.
AKO
Gateway APIs does not support
filters
within
backendRefs
.

Gateway API Objects to

Avi Load Balancer Controller

Objects Mapping

Gateway
translates to an
EVH Parent Virtual Service
with
port/protocol
from each
Listener
added as the
Service
within parent virtual service.
The
tls specification (certificate refs)
from each
Gateway Listener
will get added to the parent virtual service as
SSLKeyAndCertificateRef
.
Every
Secret
created corresponds to an
SSLKeyAndCertificate
object.
Addresses
in a Gateway specification is added as static IPs for
vsvip
for parent virtual service.
Each hostname, except wild card hostnames, specified in a Gateway listener is mapped to the DNS in the Vsvip of the parent VS.
Every
Rule
in
HTTPRoute
corresponds to an
EVH Child Virtual Service
, with
Match
translated to
VH match
and
Filters
translated to
HTTPPolicySet
configuration. If no matches are specified for a particular HTTPRoute rule, a child VS will be created with the path as
/
in
VHmatch
and linked to the parent VS associated with that rule.
If the
hostname
specified in the HTTPRoute is a complete FQDN, it will be included in the
VSVIP
dnsinfo. The hostname for the
VHMatch
of the Child VS will include all the hostnames mentioned in the HTTPRoute.
Each
backendRefs
specification (list of backends) in an
HTTPRoute Rule
is added as a
Pool Group
.
Each
backendRef
in an HTTPRoute rule is translated to a pool.
Each parent VS will have a default
HTTPPolicySet
attached, which will return a
404
error if no path matches the incoming HTTP request.

Naming Conventions

Handling Wildcards in Hostnames

HTTP Traffic Splitting

Status of Gateway API objects

Status:
Addresses:
Type:   IPAddress
Value:  100.66.176.6
Conditions:
Last Transition Time:  2024-12-02T07:20:25Z
Message:               Gateway configuration is valid
Observed Generation:   1
Reason:                Accepted
Status:                True
Type:                  Accepted
Last Transition Time:  2024-12-02T07:21:20Z
Message:               Virtual service configured/updated
Observed Generation:   1
Reason:                Programmed
Status:                True
Type:                  Programmed
Listeners:
Attached Routes:  0
Conditions:
Last Transition Time:  2024-12-02T07:20:25Z
Message:               Listener is valid
Observed Generation:   1
Reason:                Accepted
Status:                True
Type:                  Accepted
Last Transition Time:  2024-12-02T07:20:25Z
Message:               All the references are valid
Observed Generation:   1
Reason:                ResolvedRefs
Status:                True
Type:                  ResolvedRefs
Last Transition Time:  2024-12-02T07:21:20Z
Message:               Virtual service configured/updated
Observed Generation:   1
Reason:                Programmed
Status:                True
Type:                  Programmed
Name:                    https
Supported Kinds:
Group:  gateway.networking.k8s.io
Kind:   HTTPRoute

Status:
Parents:
Conditions:
Last Transition Time:  2024-12-02T07:28:39Z
Message:               Parent reference is valid
Observed Generation:   1
Reason:                Accepted
Status:                True
Type:                  Accepted
Last Transition Time:  2024-12-02T07:28:39Z
Message:
Observed Generation:   1
Reason:                ResolvedRefs
Status:                True
Type:                  ResolvedRefs
Controller Name:         ako.vmware.com/avi-lb
Parent Ref:
Group:         gateway.networking.k8s.io
Kind:          Gateway
Name:          test-gateway
Namespace:     test-httproute-ns
Section Name:  https

Conditions and Caveats

Gateway Limitations
AKO
accepts the following Gateway configuration:
Gateway must contain at least one listener configuration in it.
Gateway must not contain protocols other than HTTP or HTTPS.
Gateway must not contain TLS modes other than
Terminate
.
Two Gateways must not have listeners with the same or overlapping hostname.
Gateway
listeners
allowedRoutes
namespaces
from
with value selector, and thus
Gateway
listeners
allowedRoutes
namespaces
selector
is not supported.
HTTPRoute Limitations
AKO
accepts the following HTTPRoute configuration:
HTTPRoute must contain at least one parent reference.
HTTPRoute must not contain
*
as hostname.
HTTPRoute must specify at least one hostname.
HTTPRoute must contain at least one hostname match with parent Gateway.
Filters nested inside BackendRefs are not supported, that is,
HTTPRoute
spec
rules
backendRefs
filters
are not supported, whereas
HTTPRoute
spec
rules
filters
is supported.
Resource Creation
The
AKO
Gateway API imposes a restriction on the order of GatewayClass and Gateway creation, requiring that the GatewayClass must be created before Gateway.
AKO
allows the creation or updation of HTTPRoute and Gateway in any order, except for the following cases, which require an explicit
AKO
reboot to function properly:
If a gateway is attached to multiple routes with all valid listeners, transitions to a gateway with some invalid listeners.
If a gateway is attached to multiple routes with all valid listeners, transitions to a gateway with all invalid listeners.
If a gateway is attached to multiple routes with some valid listeners, transitions to a gateway with all invalid listeners.
If a gateway is attached to one route with some valid listeners, transitions to a gateway with all invalid listeners.
If a gateway is attached to one route with all valid listeners, transitions to a gateway with all invalid listeners.
High Availability Support
AKO
in active stand-by mode does not support Gateway APIs.
Avi Load Balancer
continues to deliver highly available L4 and L7 LBs for Gateway APIs.
Configuring Static IP address
The
AKO
supports Gateway objects with a single IPv4 address. The user can configure their preferred static IPv4 address by specifying
spec.addresses
in the Gateway object.
A sample configuration is as shown below:
spec:
addresses:
- type: IPAddress
value: 10.1.1.10
The address of type IPAddress is only supported. The length of the addresses is also limited to a single address.
Kubernetes Service types
AKO
Gateway API supports
ClusterIP
,
NodePort
and
NodePortLocal
Service types.
Container Network Interface (CNI) providers
AKO
Gateway API supports Calico and Antrea as a CNI provider.
Platforms/ Environments supported
AKO
Gateway API is supported on the Kubernetes platform.
Cloud Service Providers
AKO
Gateway API supports VMware vCenter/vSphere ESX and NSX-T Cloud.