Kubernetes Gateway API: an Engineering Perspective
The Kubernetes Gateway API represents a massive collaborative effort and key advancement in Kubernetes networking. Developed by multiple vendors and community members, the Gateway API provides a robust and extensible new standard for managing ingress traffic. With the recent general availability of version 1.0.0, the Gateway API is now ready for production use.
The release of the Gateway API is a major milestone for Kubernetes networking that has the potential to simplify and enhance ingress management. In this blog post, we'll explore what the Gateway API is, how it improves upon the existing Ingress API, and how to get started with it.
What is the Gateway API?
The Gateway API, originally proposed in 2019 at San Diego KubeCon, is the next generation of the Kubernetes Ingress API. It is designed to manage traffic from clients outside the cluster to services inside the cluster — the ingress or north/south case. However, the Gateway API is growing in popularity as a way to manage inter-service (east/west) traffic thanks to GAMMA, an experimental project that is being tried and tested by several implementations.
One of the main differences between the Gateway API and the Ingress API is the addition of routes, which are individual resources that are used to implement routing at both L4 and L7 layers. When a *Route is mentioned in the rest of this post, it refers to HTTPRoute, TCPRoute or any of the other available Gateway API route resources.
The Gateway API contains many new resources. If you want to try it out, the minimum set of resources needed to create a Gateway API configuration, are:
Gateway— the cluster access pointGatewayClass— describes the actual type of gateway controller that will handle traffic for the Gateway)*Route— implement traffic routing from the Gateway to the backend services
Why did we need the Gateway API?
The Ingress API lacks many features that would enable users to meet common routing requirements. Ingress API is not able to match based on query string parameters, or define L4 routing. The same goes for matching based on headers, or the HTTP method. This lack of off-the-shelf API features forced API implementations to create custom mechanisms on top of the API, such as annotations and decorators.
This led to the Ingress API annotation hell we live in today. You can learn the Ingress API, but that’s only 20% of what you need to know to be successful. Good luck if you want to try to migrate from one provider to another without re-learning everything. The Gateway API solves this problem.
In addition to core routing requirements, the Ingress API’s permissions model was insufficient for real-world use. The Gateway API significantly improved the permission model by introducing a new API layer (Routes), which isolates the tasks associated with various personas involved in managing the lifecycle of a cluster.
How the Kong Ingress Controller improves the vanilla Ingress API
With the Ingress API not being purpose-built, implementers have to choose how to enable users to be successful. Kong Ingress Controller improves the Ingress API via annotations and custom extensions.
The konghq.com/-prefixed annotations enrich the Ingress semantics with all the possibilities and features that the Kong Gateway provides, such as header matching, method matching, and plugin attachment.
In addition to annotations, the Kong Ingress Controller provides new CRDs to allow users to expose not only L7, but also L4 services. TCPIngresses allow the routing of TCP and TLS services, while UDPIngresses are for UDP traffic. These resources are very similar to the regular Ingress, but due to the lack of defined upstream standards, they have been implemented as vendor-specific resources.
Furthermore, KongIngress is provided as an Ingress decorator, which allows specifying upstream capabilities on top of backend services. A common example of this is controlling how incoming requests should be load-balanced over multiple services.
How the Gateway API improved the Ingress API
The Gateway API improved the Ingress API in many different aspects. The first one is the introduction of the Routes as separate APIs. Here is a diagram of how Ingress and Gateway API differ in terms of APIs and interconnections.
Ingress API
Gateway API
The decoupling of the routes from the ingress allowed the introduction of multiple types of routes (L4 and L7) and will allow new routes to be introduced in the future. The Gateway API currently supports the following route types (at various levels of maturity, indicated in parentheses):
HTTPRoute(v1)GRPCRoute(v1alpha2)TLSRoute(v1alpha2)TCPRoute(v1alpha2)UDPRoute(v1alpha2)
In addition to these Routes, the Gateway API has added brand-new routing capabilities to enable users.
HTTP Header Matching
The Headers field in a HTTPRoute enables HTTP request header matching. Multiple match values are treated as an AND, meaning that a request must match all the specified headers to select the route.
HTTP Method matching
The Method field in an HTTPRoute specifies the HTTP verb to match. When specified, it will be matched only if the request has the specified method.
HTTP Query Parameters matching
The QueryParams field in an HTTPRoute specifies query parameters that must be present in the request. Multiple match values are treated as an AND, meaning that a request must match all the specified query parameters to select the route.
HTTP Route backend weights
The HTTPRoute backendRef Weight specifies the proportion of requests forwarded to the referenced backend. This is computed as weight/(sum of all weights in this BackendRefs list). If service A has a weight of 200 and service B has a weight of 100, ⅔ of the requests will go to service A.
HTTPRoute filters
HTTPRoute Filters are a way to specify additional behavior such as modifying request headers or enabling request mirroring when processing a route. There are different types of filters, and there is also the possibility to attach custom filters to the rule via an ExtensionRef field. This extension point may be used to attach Kong Plugins to the routes.
Cross-namespace references
As opposed to the Ingress API, it is now possible to reference objects in a cross-namespace fashion. There are two main use cases for this:
A
GatewayandRoutein Namespace A reference a service in Namespace B. This kind of reference is blocked by default and can be enabled through the ReferenceGrant API.A
Routein Namespace B configures aGatewayin Namespace C. This is also blocked by default, but can be enabled using the AllowedRoutes field.
Standardized way to add functionalities to the API
The Gateway API defines a standard way to customize and enrich API functionality through the PolicyAttachment specification. The first example of an API born from this specification is the BackendTLSPolicy, an API that aims at specifying the TLS configuration of the connection from the Gateway to a backend pod/s via the Service API object.
Migrating from Ingress to Gateway API
The Ingress API has been around for a long time. Migrating from Ingress to the Gateway API manually is a process that is time-consuming and error-prone. As the Ingress API is a subset of the Gateway API’s functionality, it is possible to convert resources programmatically. This is why we built ingress2gateway.
Ingress2gateway is primarily focused on translating Ingress and provider-specific resources (CRDs) to Gateway API resources. This project is provider-based, which means that any Gateway API implementation can contribute a provider to convert all the Ingress-related annotations and CRDs into Gateway API resources.
Kong has implemented its own provider with the following set of features properly translated from Ingress to Gateway:
- HTTPRoute header matching
- HTTPRoute method matching
- Plugin references conversion into HTTPRoutes ExtensionRef filters
- TCPIngress conversion to Gateway, TCPRoutes, and TLSRoutes
- UDPIngress conversion to Gateway and UDPRoutes
Try the Gateway API today
The Gateway API recently released v1.0.0 and general availability, which is getting a lot of attention. A v1 release is a suitable level of maturity for users to trust that the API is stable.
We believe that the Gateway API is the future of Kubernetes networking. For this reason, the Gateway API is the preferred way of configuring Kong with the latest Kong Ingress Controller version (v3.0.0).
To make getting started with the Gateway API straightforward, we’ve published a step-by-step guide for Kong Ingress Controller. You can get started in under 10 minutes.
To learn more about how to use the Gateway API, watch this video. It contains a demonstration of some features with an example built from scratch. All the manifests used in the tutorial can be found here.
Conclusion
The Gateway API is likely the most collaborative API in Kubernetes history, with representation from multiple vendors and many community members to ensure that it’s a standard that will endure for many years. With its GA release, the Gateway API is officially production-ready.
The entire Gateway API community is looking forward to hearing user feedback about this huge step forward in Kubernetes networking. Get started with the Kong Ingress Controller 3.0 today and let us know what you think.