The Gateway API is the next-generation Kubernetes Ingress API, offering superior features and standardization compared to the traditional Ingress resource. Both APIs will coexist for the foreseeable future, so it’s perfectly fine to stick with the Ingress resource if it meets your needs. However, for those encountering limitations, migration tools are available to transition seamlessly to the Gateway API.
Table of Contents
Bye Bye Ingress – Hello Gateway API?
If you want to expose apps/services running in your cluster to the world outside of the cluster through HTTP/S routes, the Ingress resource is the way to go! An Ingress controller takes care of handling traffic routing, which is governed by rules defined within the Ingress resources. This was the blueprint for controlling ingress traffic of your Kubernetes cluster for a long time. Until now…
The Gateway API is the official successor to the Ingress API. Ingress primarily aims to expose HTTP applications using a simple, declarative syntax. On the other hand, the Gateway API provides a more extensive API for proxying, applicable not only to HTTP but also to other protocols such as TCP, UDP, and more.
The screenshot below from the official Kubernetes documentation indicates that the Ingress resource is now frozen. Any new features will only be implemented in the Gateway API!
Limitation of the Ingress Resource
You might wonder – why would I need the Gatway API at all? Hasn’t the Ingress Resource just became GA since a few releases? You may have noticed these limitations to varying degrees during your daily work:
- Ingress is too simple for many use cases because it only supports HTTP protocol routing.
- The Ingress API supports host and path matching. Advanced routing features can only be achieved through annotations. For instance, achieving URL redirection with the Nginx Ingress Controller mandates the configuration of the
nginx.ingress.kubernetes.io/rewrite-targetannotation. - The same portability that made Ingress widespread also constrained its future. Various Ingress controllers implemented very similar Custom Resource Definitions (CRDs) and somewhat confusing array of configuration options through annotations for each Ingress implementation are not easy understandable for users.
- The Ingress Resource cannot be shared across multiple namespaces. It is not a uncommon use case to bind services from different namespaces to the same gateway.
- The absence of robust RBAC features posed security challenges, including limited access controls, global permissions, misconfiguration risks, and difficulties in multitenancy.
- No standard mechanisms for extension for API growth / implementation / vendor-specific behaviors.
What is the Kubernetes Gateway API?
Gateway API is an open source project managed by the SIG-NETWORK community that extends beyond the limitations of the traditional Ingress resource. It provides a comprehensive and extensible framework for managing network traffic, enabling more flexibility, advanced routing capabilities, and improved integration with diverse protocols. The Gateway API addresses the evolving needs of Kubernetes networking, offering a standardized approach for cluster operators to handle complex networking scenarios.
The initial idea for the Gateway API was born during a discussion on KubeCon 2019 in San Diego:
Meanwhile, the concept has matured significantly and ultimately reached version 1.0 since October last year: https://kubernetes.io/blog/2023/10/31/gateway-api-ga/
Benefits of the Kubernetes Gateway API
The flaws of the Ingress resource led to the following improvements for the Gateway API:
- Large feature set: Beyond HTTP host/path matching and TLS, the Gateway API provides built-in-functionalities such as HTTP header manipulation, traffic weighting, mirroring, TCP/UDP routing, and other capabilities that previously relied on custom annotations within Ingress.
- Role-oriented design: The API resource model mirrors the separation of responsibilities in routing and Kubernetes service networking. A key advantage of these new APIs lies in the seperation of the Gateway API into distinct functions: one for describing the Gateway and another for defining routes to backend services. This creates a new operational model: Platform teams can modify and interchange gateways while retaining the same routing configuration that was originally created by the app developers (cluster users).
- Extensibility: The Gateway API enables the association of custom resources at different layers of the API, facilitating precise customization at specific points within the API structure.
- Cross-Namespace-Support: Route resources can be attached to a common Gateway, enabling teams, even across namespaces, to securely share infrastructure without requiring direct coordination.
Gateway API Architecture
The Gateway API comprises several essential API resources, including GatewayClass, Gateway, HTTPRoute, TCPRoute, ReferenceGrant, and more. These resources can be found as Custom Resource Definitions (CRDs) within the gateway.networking.k8s.io API group.
As an example, the persona infrastructure provider could establish two GatewayClasses, named “internet” and “private,” to distinguish Gateways representing Internet-facing and private, internal applications. This allows categorizing gateways based on their intended use and cluster operators/application developers can segregate traffic easily by choosing the appropriate gateway.
One key benefit of the Gateway API is its role-oriented design, consisting of three primary roles: Infrastructure Provider, Cluster Operator, and Application Developer. These roles enable a segregation of duties, although it is not uncommon for multiple roles to be assigned to the same user.
Route resources define protocol-specific rules for mapping requests from a Gateway to Kubernetes Services. As of writing this blog, there are multiple Route resources available. Except HTTPRoute all other Route resources (like TCPRoute, GRPCRoute, etc.) are still part of the Experimental Channel.
Migrating from Ingress to Gateway API
First of all, there is no need to hurry if you are currently still using Ingress resources. While the Ingress API may be frozen, it is not deprecated yet and perhaps never will be! 🙂
The official Gateway API docs state the following:
Will Gateway API replace the Ingress API?
No. The Ingress API is GA since Kubernetes 1.19. There are no plans to deprecate this API and we expect most Ingress controllers to support it indefinitely.
https://gateway-api.sigs.k8s.io/faq/#will-gateway-api-replace-the-ingress-api
Should I migrate to Gateway API right now?
If you are happy with your Ingress configuration and everything is working fine, stick with it! But if you are feeling limited by Ingress and want more flexibility, check out the Gateway API. Since Gateway API is GA it is safe to use in production, but I wouldn’t change clusters (in production) unless you really see some major benefits in what the Gateway API offers.
Gateway API is the successor to the Ingress API. However, it does not include the Ingress kind. As a result, a one-time conversion from your existing Ingress resources to Gateway API resources is necessary. Refer to the Ingress migration guide for details on migrating Ingress resources to Gateway API resources. If you want to automize the migration process you should have a look at the ingress2gateway tool.
Example: Cilium Gateway API
There are plenty of implementations of the Gateway API already out there. Some current and in-progress implementations include, for example, Cilium, Contour, Envoy Gateway, Istio, Kong, and Traefik. You can find a actual overview of all different implementations and their status in the official docs: https://gateway-api.sigs.k8s.io/implementations/
If you want to get started with the Gateway API, take a look at the “Cilium Gateway API” lab created by Isovalent. In this lab, you’ll explore how HTTP/S traffic is routed to your Kubernetes applications using Gateway API mechanisms. It also includes examples of Gateway API features such as load balancing, traffic splitting, and TLS passthrough or termination. I enjoyed this lab because it explains a rather complex topic very well and intuitively. The lab itself worked smoothly in my browser and is very easy to use. Kudos to the UX designer! 🙂
Summary
I believe both APIs will continue to play a crucial role for most cluster admins in the upcoming years. Most people won’t change their productive clusters with working Ingress configurations unless they face some limitations or they are forced to do so. On the other hand, an increasing number of greenfield deployments will directly start from scratch with the Gateway API. Therefore, I find it highly useful to familiarize myself with the Gateway API now. As a platform engineer, I anticipate encountering more use cases that benefit from the features offered by the Gateway API, as well as potentially more misconfigurations due to its complexity! 😄