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:
- GatewayClass (v1)
- Gateway (v1)
- HTTPRoute (v1)
AKO
currently supports all the fields that are mentioned as Support: Core
in the above objects. For more details, see limitations.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
:
- Set theGatewayAPIunder the sectionfeatureGatesto true in the values.yaml.
- Do a helm install or upgrade using the editedvalues.yamlto install or upgrade theAKO.
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).AKOidentifies GatewayClasses that point toako.vmware.com/avi-lbas the.spec.controllerNamevalue 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.controllerNamevalue specified must matchako.vmware.com/avi-lbforAKOto honour the GatewayClass and corresponding Gateway API objects.A GatewayClass namedavi-lbwill 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. TheAKOvalidates the Gateway object, ensuring that the listeners are valid and then setsListenerConditionAcceptedtotrue. If at least one listener in the gateway is valid,GatewayConditionAcceptedis set totrue. It then verifies whether all the references specified in the gateway listeners are valid and exist, and then setsListenerConditionResolvedRefstotrue. 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 theAvi Load Balancer Controllerand will be referenced within the same Parent VS.Once the VS creation is complete,AKOupdates the Gateway status by settingGatewayConditionProgrammedtotrue, along with the VIP of the Parent VS. Further, it setsListenerConditionProgrammedtotrueif the corresponding listener is successfully programmed.TheAKOcreated 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-certThe above Gateway object would correspond to a single Layer 7 virtual service in theAvi Load Balancer Controller, with two ports (80, 443) exposed and asslKeyAndCertificatecreated based on the secretbar-example-com-cert.Starting with version 1.11.1,AKOonly 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.addressesfield, 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.10Starting withAKOversion 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. TheAKOmodels a child virtual service based on this object. Starting with version 1.11.1,AKOsupports 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 theAKO. The filters of typeRequestHeaderModifier,RequestRedirect, andResponseHeaderModifierare 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: 2The above HTTPRoute object gets translated to two child virtual services in theAvi Load Balancer Controlleras follows:
- One child virtual service with match criteria as the path begins with/barand a single Pool Group with a single pool.
- Another child virtual service with match criteria as the path begins with/fooand includes a header namedmagicwith valuefoo, a single Pool Group with two pools, and an HTTP Request policy to addmy headerwith valuefooto the HTTP request forwarded to the back-ends.
- Hostnames are mandatory and can be prefixed with a wildcard.
- AKOGateway APIs does not supportfilterswithinbackendRefs.
Gateway API Objects to Avi Load Balancer Controller Objects Mapping
Avi Load Balancer Controller
Objects MappingIn
AKO
Gateway API Implementation, Gateway objects correspond to the following Controller objects:- Gatewaytranslates to anEVH Parent Virtual Servicewithport/protocolfrom eachListeneradded as theServicewithin parent virtual service.
- Thetls specification (certificate refs)from eachGateway Listenerwill get added to the parent virtual service asSSLKeyAndCertificateRef.
- EverySecretcreated corresponds to anSSLKeyAndCertificateobject.
- Addressesin a Gateway specification is added as static IPs forvsvipfor 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.
- EveryRuleinHTTPRoutecorresponds to anEVH Child Virtual Service, withMatchtranslated toVH matchandFilterstranslated toHTTPPolicySetconfiguration. If no matches are specified for a particular HTTPRoute rule, a child VS will be created with the path as/inVHmatchand linked to the parent VS associated with that rule.
- If thehostnamespecified in the HTTPRoute is a complete FQDN, it will be included in theVSVIPdnsinfo. The hostname for theVHMatchof the Child VS will include all the hostnames mentioned in the HTTPRoute.
- EachbackendRefsspecification (list of backends) in anHTTPRoute Ruleis added as aPool Group.
- EachbackendRefin an HTTPRoute rule is translated to a pool.
- Each parent VS will have a defaultHTTPPolicySetattached, which will return a404error if no path matches the incoming HTTP request.
Naming Conventions
AKO
Gateway Implementation follows the following naming convention:- ParentVSako-gw-<cluster-name>--<gateway-namespace>-<gateway-name>-EVH
- ChildVSako-gw-<cluster-name>–-<sha1 hash of <gateway-namespace>-<gateway-name>-<route-namespace>-<route-name>-<stringified FNV1a_32 hash of bytes(jsonified match)>>
- Poolako-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>>
- PoolGroupako-gw-<cluster-name>–-<sha1 hash of <gateway-namespace>-<gateway-name>-<route-namespace>-<route-name>-<stringified FNV1a_32 hash of bytes(jsonified match)>>
- SSLKeyAndCertificateako-gw-<cluster-name>--<sha1 hash of <gateway-namespace>-<gateway-name>-<secret-namespace>-<secret-name>>
- DefaultHTTPPolicySetako-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:
- A wildcard prefixed hostname (such as*.avi.internal) at Gateway listener and a non-wildcard hostname (such asbar.avi.internal) at HTTPRoute.
- A non-wildcard hostname (such asbar.avi.internal) at Gateway listener and a wildcard prefixed hostname (such as*.avi.internal) at HTTPRoute.
- An empty hostname (such as*) at Gateway listener and a Non-wildcard and wildcard prefixed hostname (such asbar.avi.internalor*.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
- Gateway LimitationsAKOaccepts 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 thanTerminate.
- Two Gateways must not have listeners with the same or overlapping hostname.
- with value selector, and thus is not supported.
- HTTPRoute LimitationsAKOaccepts 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,are not supported, whereas is supported.
- Resource CreationTheAKOGateway API imposes a restriction on the order of GatewayClass and Gateway creation, requiring that the GatewayClass must be created before Gateway.AKOallows the creation or updation of HTTPRoute and Gateway in any order, except for the following cases, which require an explicitAKOreboot 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 SupportAKOin active stand-by mode does not support Gateway APIs.Avi Load Balancercontinues to deliver highly available L4 and L7 LBs for Gateway APIs.
- Configuring Static IP addressTheAKOsupports Gateway objects with a single IPv4 address. The user can configure their preferred static IPv4 address by specifyingspec.addressesin the Gateway object.A sample configuration is as shown below:spec: addresses: - type: IPAddress value: 10.1.1.10The address of type IPAddress is only supported. The length of the addresses is also limited to a single address.
- Kubernetes Service typesAKOGateway API supportsClusterIP,NodePortandNodePortLocalService types.
- Container Network Interface (CNI) providersAKOGateway API supports Calico and Antrea as a CNI provider.
- Platforms/ Environments supportedAKOGateway API is supported on the Kubernetes platform.
- Cloud Service ProvidersAKOGateway API supports VMware vCenter/vSphere ESX and NSX-T Cloud.