Stop Fighting Annotations: Why Kubernetes Gateway API is Replacing Ingress

If you’ve spent the last few years deploying applications to Kubernetes, you’re intimately familiar with the Ingress resource. It’s the trusty workhorse that gets HTTP traffic from the outside world into your cluster.

But let’s be honest: you’ve also felt the pain.

You want to do something seemingly simple, like split traffic for a canary release, rewrite a header, or do regex path matching. Suddenly, your clean YAML file is overflowing with a massive, unreadable block of controller-specific annotations.

“Wait, was the annotation nginx.ingress.kubernetes.io/rewrite-target or ingress.kubernetes.io/rewrite-target?”

Enter the Kubernetes Gateway API. It’s not just a new tool; it’s a fundamental rethinking of how routing works in a cloud-native world. Let's break down the difference between the legacy Ingress API and the new Gateway APIand why you should start migrating your mindset.

The Legacy Workhorse: Kubernetes Ingress

Introduced way back in Kubernetes v1.1, the Ingress API was designed with a simple goal: provide a unified way to configure HTTP(S) routing to services.

What it does well:

Basic fan-out routing (e.g., /api goes here, /web goes there).
Name-based virtual hosting (e.g., app.example.com).
Basic TLS termination.

Where it falls apart:

It's only for HTTP(S). Need to route TCP/UDP traffic? You're out of luck with standard Ingress. You have to hack it via load balancers or custom controller configs.
The "Annotation Hell". Because the Ingress API spec is so basic, it lacks native fields for advanced routing (retries, header manipulation, traffic splitting). To fill the gap, Ingress controllers (like NGINX, HAProxy, or Traefik) started using custom annotations. Your routing logic became coupled to the specific proxy implementation you were using.
Single Persona Design. In a real organization, an Infrastructure team manages the load balancer, but App Developers manage the application routes. The Ingress object forces everyone to collaborate on a single YAML file, which often leads to stepped-on toes and accidental outages.

The Evolution: Kubernetes Gateway API

The Gateway API (formerly known as Service APIs) is the official evolution of Ingress. After several years in development, the core Gateway APIs reached General Availability (v1.0) in late 2023, making it fully production-ready for standard Kubernetes clusters (typically v1.24+). Because it is delivered as a set of Custom Resource Definitions (CRDs) rather than being baked directly into the Kubernetes core API, you can install it on your cluster right now.

It was designed from the ground up to be expressive, extensible, andmost importantly*role-oriented*.

Here is why it changes the game:

1. Role-Oriented Design

Instead of a single monolithic Ingress object, the Gateway API splits the configuration into three separate resources, aligning perfectly with organizational roles:

GatewayClass (Infrastructure Provider): Defines the underlying load balancer technology (e.g., AWS ALB, GCP Load Balancer, Envoy). Managed by the cloud provider or platform team.
Gateway (Cluster Operator): Instantiates the load balancer and defines listening ports, TLS certificates, and which namespaces are allowed to attach routes to it. Managed by the cluster admins.
HTTPRoute / TCPRoute (App Developer): Defines the actual routing logic (paths, headers, traffic splitting). App developers own this and can attach it to the Gateway without asking the platform team for permission.

This separation of concerns is a massive win for security and self-service capabilities.

2. Goodbye Annotations, Hello Native Expressiveness

Remember all those wild NGINX annotations? The Gateway API bakes advanced routing directly into the API specification.

With HTTPRoute, you can natively configure:

Traffic Splitting (Canary/A-B Testing): Send 90% of traffic to v1 and 10% to v2.
Header Modification: Add, remove, or modify request/response headers.
Advanced Matching: Route based on query parameters or specific HTTP methods.
Cross-Namespace Routing: A Gateway in the infra namespace can securely route traffic to a service in the billing namespace.

All of this is done with strongly typed YAML fields, not brittle annotations.

3. Beyond HTTP and the gRPC Revolution

The Gateway API isn't just for standard L7 HTTP traffic. It natively supports TCPRoute, UDPRoute, TLSRoute, and notably, GRPCRoute.

If you've ever tried to route gRPC traffic through a standard Ingress, you know the struggle: hacking together annotations to force HTTP/2, watching streaming connections drop unexpectedly, and failing to cleanly route traffic to different backend pods based on the specific gRPC method being called.

With the native GRPCRoute, the Gateway API understands gRPC semantics out of the box. You can now reliably route traffic based on specific gRPC services or method names, perform precise traffic splitting for gRPC streams (perfect for canary testing a new microservice), and maintain stable connections without the annotation duct tape. You finally have a unified API to manage all traffic entering your cluster, regardless of the protocol.

So, is Ingress Dead?

Not quite yet. The Ingress API (specifically networking.k8s.io/v1) is stable and isn't being deprecated tomorrow. Millions of clusters rely on it, and it will be supported for a long time.

However, Ingress is feature-frozen. The Kubernetes community has made it clear that all future routing innovations, enhancements, and advanced features will be built exclusively into the Gateway API.

The Verdict

If you are running a simple blog with one container, standard Ingress is still fine.

But if you are building a modern, multi-tenant platform, struggling with complex traffic routing, or tired of vendor lock-in caused by proprietary annotations, the Gateway API is the answer. It’s standardized, it’s secure, and it respects the boundaries between your infra team and your developers.

It’s time to stop hacking your Ingress and start building with Gateways.