Kubernetes Ingress resource plays a fundamental role in connecting requests from the outside to services in Kubernetes clusters. Developers use Ingress resources to expose their services and APIs by defining routes in the resource. Although native Ingress is widely accepted and has existed for years, its capabilities are confined to basic routing requirements.
Native Ingress can only provide access to services based on the path and host defined in the request. DevOps and developers rely on vendors who offer Ingress controllers to implement any advanced traffic routing logic. Vendors used proprietary annotations to extend the functionalities of Ingress, making Ingress configurations inoperable across Ingress controllers/implementations. The annotations make Ingress hard to maintain, and it is tedious for multiple teams to work on a single Ingress resource.
Kubernetes Gateway API is here to solve the proliferation of vendor-specific annotations and the lack of standardization with Ingress. Gateway API is the “next-generation Ingress” that also provides advanced features out of the box without using custom annotations.
What is Kubernetes Gateway API
Kubernetes Gateway API is a collection of vendor-agnostic, Kubernetes-native custom resources used to configure basic to advanced ingress rules. The Kubernetes SIG (Special Interest Group) Network manages the Gateway API project.
The Gateway API includes GatewayClass, Gateway, and protocol-specific Route CRDs that platform teams, DevOps, and developers can use independently (see Fig. A).
- GatewayClass specifies the controller used to implement the Gateway API resources.
- Gateway resource acts as a network endpoint that directs traffic from the outside into the cluster. Gateway is attached to a GatewayClass.
- Route objects define protocol-specific (HTTP, TCP, UDP, gRPC) or TLS traffic routing rules for requests from Gateway to the backend service. Route resources are attached to Gateways.
- ReferenceGrant enables secure cross-namespace referencing in a Kubernetes cluster.
Gateway API, like Ingress, leverages custom resource definitions (CRDs) to represent routing configurations. These CRDs require a dedicated controller to interpret and translate them into actionable configurations for the underlying infrastructure. Open source Traefik Proxy v3 is an Ingress controller with built-in support for Gateway API.
Limitations of Kubernetes Ingress
Since its inception, some limitations with native Ingress objects have not been resolved. The following are some challenges with Ingress that Gateway API effectively addresses.
Limited routing features and non-standard workarounds
The native Ingress resource is limited when applying granular routing rules in Kubernetes. If developers want to route requests based on headers, weights, HTTP methods or any other advanced way, they must rely on the vendor's custom annotation. The same is true for configuring advanced traffic management like mirroring, canary rollout, blue-green deployment, and A/B testing.
Similarly, native Ingress only supports routing HTTP/S (L7) requests; routing other protocols, such as gRPC (L7) and TCP/UDP (L4), requires configuring vendor-specific annotations. In a nutshell, common use cases of Ingress in a typical production environment are offloaded to the controller implementation rather than the resource taking care of them in a standardized way.
Non-portable Ingress configurations and vendor lock-in
Ingress configurations that use proprietary, vendor-specific annotations lack portability. That means the same configurations cannot be used with another Ingress controller. This limits IT teams’ ability to use a new Ingress controller, as they will have to learn the syntax and values of the new controller and "redo the plumbing".
The lack of portability is one of the reasons some IT teams are still coping with Ingress controllers born before the cloud-native era. They started using the controller in the early days of Kubernetes and the configurations now contain too many annotations proportional to their custom modification requirements. A modern API Gateway offers greater capabilities for serving APIs, but switching from their current solution presents a significant challenge.
Absence of RBAC and centralized policy enforcement
One of the immense pain points with Ingress for platform teams is that they either have to provide access to modify Ingress or not let anyone access it. For example, if developers want to add a new route to their API in the Ingress resource, platform teams cannot restrict developers to creating just that route in the Ingress resource; developers are free to alter the controller’s behavior by modifying the annotations.
With Ingress, everyone (regardless of their role) modifies the same resource for their purposes. This lack of role delineation makes RBAC difficult, which prevents enterprises from enforcing centralized policy management.
Lack of cross-namespace support
Typically, both the Ingress object and the service it exposes reside in the same namespace. Although IT teams may want Ingress to reference a service outside its namespace to forward requests, there is no secure way to do it with Ingress.
Referencing objects outside the namespace is not limited to services; it can also be secrets, like those required for TLS termination. However, due to the lack of cross-namespace support with Ingress, the team cannot maintain a protected namespace just for secrets.
Now, let us see how Gateway API solves the above problems.
Benefits of implementing Kubernetes Gateway API
By using Gateway API resources, IT teams reap huge benefits compared to the Ingress API in Kubernetes.
Advanced traffic management out-of-the-box
Gateway API resources are expressive and allow developers to configure advanced routing rules without using custom annotations. For example, developers can use HTTPRoute resources to define two backends and route traffic to them based on certain weights. The expressive nature of K8s Gateway API helps developers easily carry out advanced traffic management like canary deployment, blue-green rollout, and A/B testing.
With Gateway API, developers can parse HTTP request data and modify it in-flight for granular routing. For example, a request can be matched against the combination of hostname, path, and header in the request data for sophisticated routing. The request headers can also be modified before forwarding a request to the backend service—for instance, to hide sensitive information like authorization tokens.
All the above features are built into the Gateway API, and developers can configure them for both L4 and L7 requests using dedicated Route resources.
Portable Ingress configuration across a variety of implementations
Kubernetes Gateway API standardizes both basic and advanced Ingress configurations. That means the Ingress configurations are portable from one controller to another, and IT teams can use the same Gateway API configurations regardless of the underlying controller.
The portability aspect of Gateway API is beneficial to future-proofing their Ingress configuration if the team wants to try or migrate to a new controller. If the new controller supports Gateway API, the team does not have to rewrite the Gateway API configuration (except GatewayClass), and there will not be much of a learning curve to adopt the controller.
The Gateway API also provides enough flexibility for users and vendors to extend the specification while standardizing most configurations used in a production environment.
Clear separation of concern and seamless RBAC
With Gateway API, IT teams handle Ingress configuration resources based on their roles: platform teams set up the GatewayClass—they do not have to let DevOps modify it while giving access to attach Gateway resources referencing that class; DevOps engineers set up Gateway instances and allow developers to attach various routes to their applications.
The role-based CRD model of Gateway API helps for the separation of concerns among different organizational roles. It ensures that a role/team does not modify the rules maintained by another role/team. At the same time, platform teams can leverage this model to their advantage by defining standardized access control using Role and ClusterRole resources (RBAC).
Secure referencing and routing across namespaces
The ReferenceGrant object in Gateway API enables cross-namespace referencing, which helps decouple ingress rules from the services. IT teams can use the resource to independently deploy and manage Route resources in dedicated namespaces, which gives them operational flexibility. ReferenceGrant works with secrets, too (see the example below).
The ReferenceGrant resource also enhances security, as the service or secrets owner must create a RefereGrant object and explicitly allow the reference outside its namespace. This “approval” is mandatory for cross-namespace referencing to work. It gives them more power, as the service or secret owners decide who can reference their resources.
How Kubernetes Gateway API CRDs work (with examples)
Gateway API brings a couple of new custom resources. Unlike the all-in-one Ingress object, the resources are meant for different personas.
GatewayClass (platform team)
GatewayClass is a cluster-scoped resource that specifies the controller used to implement the Gateway API resources. Infrastructure providers or platform teams typically install the controller and handle the GatewayClass resource. With Gateway API, they do not need to provide edit access to the resource while letting other teams set up Ingress configurations.
A sample GatewayClass CRD would look like this:
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: my-gateway-class
spec:
controllerName: traefik.io/gateway-controller
The configuration declares a GatewayClass (my-gateway-class) that uses Traefik proxy as the controller to implement Gateway API CRDs.
Gateway (DevOps team)
A Gateway resource is a network endpoint that takes the traffic from outside the cluster. Gateways are attached to respective GatewayClass, and cluster operators or DevOps teams can set up listeners on the Gateway. The Gateway resource provides the flexibility for users to define the namespaces from which Route resources (explained below) can be attached to it.
Below is a sample Gateway CRD:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: my-gateway
spec:
gatewayClassName: my-gateway-class
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
certificateRefs:
- kind: Secret
name: mysecret
- The Gateway configuration (
my-gateway) references a GatewayClass (my-gateway-class) object so that the Gateway will be created by the referenced class - The Gateway object has an HTTPS setting block to listen for requests on port
443 - The TLS certificate for the HTTPS protocol is stored in
mysecret
Route (Developers)
Route resource defines traffic routing rules for requests from Gateway to the backend service. The resource includes HTTPRoute, TCPRoute (and UDPRoute), TLSRoute, and GRPCRoute. Route objects are attached to specific Gateways, and application developers can use HTTPRoute or any other Route object to direct traffic to their service.
Currently, HTTPRoute allows developers to route requests based on HTTP headers and paths or modify requests in flight. Using extended support, they can also route requests based on query and method matches.
Here is a sample HTTPRoute resource:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: http-app
namespace: default
spec:
parentRefs:
- name: my-gateway
hostnames:
- whoami
rules:
- matches:
- path:
type: Exact
value: /foo
backendRefs:
- name: whoami
port: 80
- The HTTPRoute is attached to a Gateway (
my-gateway) - The resource looks for a particular hostname (
whoami) and a path (/foo) in the request - The resource forwards matching requests to whoami service, which is listening on port
80
Combining the above Gateway API resources, the traffic flow in a Kubernetes cluster would look like this:
Route object also lets developers configure advanced traffic management. For example, developers can define weights—the percentage of total traffic that must be forwarded to the backend—in Routes, which is helpful for deployment strategies like canary.
Here is an example canary rollout using HTTPRoute, which forwards 90% of the total traffic to whoami-v1 and the rest 10% to whoami-v2:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: http-app
namespace: default
spec:
parentRefs:
- name: my-gateway
hostnames:
- whoami
rules:
backendRefs:
- name: whoami-v1
port: 80
weight: 90
- name: whoami-v2
port: 80
weight: 10
ReferenceGrant (Developer/service/secrets owner)
The ReferenceGrant object can be used for cross-namespace references, where Route resources can reference services deployed in other namespaces and thus forward requests to those services.
With ReferenceGrant deployed in the same namespace as the service, the Route and the service can now be in two different namespaces while safely exposing the service to be referenced by the Route in the other namespace (refer to Fig. C below). In other words, ReferenceGrant decouples routing logic from the backend service.
In the above image, the ReferenceGrant deployed in the backend namespace allows HTTPRoute from the api-gateway namespace to reference the service deployed in the backend. The sample ReferenceGrant resource would look like this:
kind: ReferenceGrant
metadata:
name: api-gateway-to-service
namespace: backend
spec:
from:
- group: networking.gateway.k8s.io
kind: HTTPRoute
namespace: api-gateway
to:
- group: ""
kind: Service
name: my-service-name (optional)
The ReferenceGrant resource also works with secrets. This feature helps maintain a dedicated, highly regulated namespace for secrets. The following ReferenceGrant (api-gateway-to-secret) resource allows the Gateway resource in the api-gateway namespace to use secrets in the secret namespace:
kind: ReferenceGrant
metadata:
name: api-gateway-to-secret
namespace: secret
spec:
from:
- group: networking.gateway.k8s.io
kind: Gateway
namespace: api-gateway
to:
- group: ""
kind: Secret
name: my-secret-name (optional)
Gateway API vs API Gateway
Kubernetes Gateway API is a collection of CRDs/resources that IT teams use to define ingress rules in Kubernetes. The CRDs define how and where the inbound traffic should be routed in the cluster. The resources need an Ingress controller (like Traefik proxy) or a service mesh (like Istio) to implement the rules defined in them. The scope of the Gateway API resources is within Kubernetes and on traffic routing.
API Gateway typically refers to a specialized reverse proxy that sits between a client and backend services (or APIs). It acts as a single entry point for all incoming and outgoing API calls between clients and backend services. As a literal gateway to the APIs, API Gateways perform authentication, authorization, rate limiting, protocol translation, monitoring, and more, in addition to request routing and traffic management. API Gateways exist in and outside of Kubernetes, such as in on-premise and hybrid cloud environments.
Although two different concepts, the roles of API Gateways and Gateway API overlap regarding traffic management in a Kubernetes environment. An API Gateway can be used to implement Gateway API CRDs, but the CRDs cannot perform all the functions of an API Gateway.
Getting started with Kubernetes Gateway API using Traefik
IT teams can now use the Kubernetes Gateway provider in Traefik to implement the Kubernetes Gateway API v1.0.0 specification. They can use HTTP or TLS (HTTPS) Route resources and filters with Traefik v3.
The filter support helps extend the Gateway API by adding capabilities that are not part of the standard specification; IT teams can use filters to add any middleware present in Traefik v3 to the Gateway API specification, like the Ratelimit middleware.
Check out our documentation to learn more and to get started with the Gateway API spec: https://doc.traefik.io/traefik/providers/kubernetes-gateway/.
A future beyond Gateway configurations
The Kubernetes SIG Network plans to extend Gateway API to configure service-to-service communication (east/west traffic) within a cluster—besides Ingress (north/south). The project is called the GAMMA Initiative (Gateway API for Service Mesh), as configuring service-to-service communication comes under the scope of service mesh. The service mesh support is in GA (v1), which means IT teams can use Gateway API to manage mesh traffic.
The Gateway API project is in v1.1 at the time of writing this. The project has an active roadmap. More and more features will be released in the upcoming versions.