Gateway API - v1

Starting with
AKO
version 1.12.1, Gateway API v1 release is supported. The field
GatewayAPI
under the section
featureGates
in values.yaml must be set to
true
to enable this feature. This generates a new container within the
AKO
pod that will handle the Gateway API related objects.
AKO
supports the following objects in the Gateway API:
  1. GatewayClass (v1)
  2. Gateway (v1)
  3. HTTPRoute (v1)
AKO
currently supports all the fields that are mentioned as
Support: Core
in the above objects. For more details, see limitations.
Support Matrix
Release
GatewayClass
Gateway
HTTPRoute
GRPCRoute
TLSRoute
TCPRoute
UDPRoute
ReferenceGrant
1.13.1
v1
v1
v1
Not Supported
Not Supported
Not Supported
Not Supported
Not Supported

Installation

Follow the below steps to enable the GatewayAPI feature in
AKO
:
  1. Set the
    GatewayAPI
    under the section
    featureGates
    to true in the values.yaml.
  2. Do a helm install or upgrade using the edited
    values.yaml
    to install or upgrade the
    AKO
    .
A GatewayClass
avi-lb
with
controllerName
as
ako.vmware.com/avi-lb
will get installed as part of the installation. An Infrastructure Provider can request the cluster operators to use this GatewayClass in their Gateway objects so that the
AKO
honours the objects created by them.
The GatewayClass, Gateway, and Route CRD definitions must be installed on the cluster before enabling the
GatewayAPI
feature in
AKO
. For more information on CRDs, see gateway-api.

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

In
AKO
Gateway API Implementation, Gateway objects correspond to the following Controller objects:
  1. Gateway
    translates to an
    EVH Parent Virtual Service
    with
    port/protocol
    from each
    Listener
    added as the
    Service
    within parent virtual service.
  2. The
    tls specification (certificate refs)
    from each
    Gateway Listener
    will get added to the parent virtual service as
    SSLKeyAndCertificateRef
    .
  3. Every
    Secret
    created corresponds to an
    SSLKeyAndCertificate
    object.
  4. Addresses
    in a Gateway specification is added as static IPs for
    vsvip
    for parent virtual service.
  5. Each hostname, except wild card hostnames, specified in a Gateway listener is mapped to the DNS in the Vsvip of the parent VS.
  6. 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.
  7. 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.
  8. Each
    backendRefs
    specification (list of backends) in an
    HTTPRoute Rule
    is added as a
    Pool Group
    .
  9. Each
    backendRef
    in an HTTPRoute rule is translated to a pool.
  10. 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

AKO
Gateway Implementation follows the following naming convention:
  1. ParentVS
    ako-gw-<cluster-name>--<gateway-namespace>-<gateway-name>-EVH
  2. ChildVS
    ako-gw-<cluster-name>–-<sha1 hash of <gateway-namespace>-<gateway-name>-<route-namespace>-<route-name>-<stringified FNV1a_32 hash of bytes(jsonified match)>>
  3. Pool
    ako-gw-<cluster-name>--<sha1 hash of <gateway-namespace>-<gateway-name>-<route-namespace>-<route-name>-<stringified FNV1a_32 hash of bytes(jsonified match)>-<backendRefs_namespace>-<backendRefs_name>-<backendRefs_port>>
  4. PoolGroup
    ako-gw-<cluster-name>–-<sha1 hash of <gateway-namespace>-<gateway-name>-<route-namespace>-<route-name>-<stringified FNV1a_32 hash of bytes(jsonified match)>>
  5. SSLKeyAndCertificate
    ako-gw-<cluster-name>--<sha1 hash of <gateway-namespace>-<gateway-name>-<secret-namespace>-<secret-name>>
  6. DefaultHTTPPolicySet
    ako-gw-<cluster-name>--default-backend

Handling Wildcards in Hostnames

Starting with
AKO
version 1.13.1,
AKO
Gateway will support the following hostname combinations in Gateway listener and HTTPRoute:
  1. A wildcard prefixed hostname (such as
    *.avi.internal
    ) at Gateway listener and a non-wildcard hostname (such as
    bar.avi.internal
    ) at HTTPRoute.
  2. A non-wildcard hostname (such as
    bar.avi.internal
    ) at Gateway listener and a wildcard prefixed hostname (such as
    *.avi.internal
    ) at HTTPRoute.
  3. An empty hostname (such as
    *
    ) at Gateway listener and a Non-wildcard and wildcard prefixed hostname (such as
    bar.avi.internal
    or
    *.avi.internal
    ) at HTTPRoute.

HTTP Traffic Splitting

AKO
Gateway supports the Canary and Blue-Green traffic rollout.
For more information on configurations corresponding to this, see HTTP traffic splitting.

Status of Gateway API objects

AKO
updates the status of all Gateway API objects with proper reasons. A typical status consists of a reason for the acceptance or rejection using which a user can debug the Gateway API object configuration.
A sample status of the Gateway is as shown below:
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
A sample HTTPRoute status is as shown below:
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

  1. Gateway Limitations
    AKO
    accepts the following Gateway configuration:
    1. Gateway must contain at least one listener configuration in it.
    2. Gateway must not contain protocols other than HTTP or HTTPS.
    3. Gateway must not contain TLS modes other than
      Terminate
      .
    4. Two Gateways must not have listeners with the same or overlapping hostname.
    5. Gateway
      listeners
      allowedRoutes
      namespaces
      from
      with value selector, and thus
      Gateway
      listeners
      allowedRoutes
      namespaces
      selector
      is not supported.
  2. HTTPRoute Limitations
    AKO
    accepts the following HTTPRoute configuration:
    1. HTTPRoute must contain at least one parent reference.
    2. HTTPRoute must not contain
      *
      as hostname.
    3. HTTPRoute must specify at least one hostname.
    4. HTTPRoute must contain at least one hostname match with parent Gateway.
    5. Filters nested inside BackendRefs are not supported, that is,
      HTTPRoute
      spec
      rules
      backendRefs
      filters
      are not supported, whereas
      HTTPRoute
      spec
      rules
      filters
      is supported.
  3. 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:
    1. If a gateway is attached to multiple routes with all valid listeners, transitions to a gateway with some invalid listeners.
    2. If a gateway is attached to multiple routes with all valid listeners, transitions to a gateway with all invalid listeners.
    3. If a gateway is attached to multiple routes with some valid listeners, transitions to a gateway with all invalid listeners.
    4. If a gateway is attached to one route with some valid listeners, transitions to a gateway with all invalid listeners.
    5. If a gateway is attached to one route with all valid listeners, transitions to a gateway with all invalid listeners.
  4. 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.
  5. 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.
  6. Kubernetes Service types
    AKO
    Gateway API supports
    ClusterIP
    ,
    NodePort
    and
    NodePortLocal
    Service types.
  7. Container Network Interface (CNI) providers
    AKO
    Gateway API supports Calico and Antrea as a CNI provider.
  8. Platforms/ Environments supported
    AKO
    Gateway API is supported on the Kubernetes platform.
  9. Cloud Service Providers
    AKO
    Gateway API supports VMware vCenter/vSphere ESX and NSX-T Cloud.