Setting up a cluster network cleanly and future-proof? WZ-IT plans and operates Kubernetes networks: CNI, Gateway API, load balancing, DNS and TLS - and private access via NetBird instead of unnecessary public exposure. See Network & Secure Access
Ingress or Gateway API? The question comes up with every new Kubernetes cluster - and, with the end of ingress-nginx, with many existing ones too. Both APIs do the same basic job: route HTTP traffic from the outside to the right services. But they do it in fundamentally different ways. This article explains the difference, shows what Ingress structurally cannot do, and answers the real question: when each is the right choice. As of October 2026.
Table of contents
- Two APIs for the same job
- The core difference: one resource vs. a role model
- What Ingress cannot do without annotations
- Ingress and the Gateway API compared
- More than ingress: service mesh too
- When Ingress still suffices and when the Gateway API
Two APIs for the same job
Ingress has been the standard way to let HTTP and HTTPS traffic into a cluster for years. The Ingress resource remains a stable GA API and is not being removed - but it is feature-frozen. New functionality in Kubernetes networking lands exclusively in the Gateway API.
The Gateway API is the official successor, developed by the same SIG Network. It is not a beta experiment: GA since v1.0 on 31 October 2023 (Kubernetes blog), v1.5 from February 2026 focused on moving further features into the stable Standard channel (Kubernetes blog). The current minor version v1.6 from 29 June 2026 graduates TCPRoute and UDPRoute to GA (v1) and allows BackendTLSPolicy with other route types (v1.6.0 release notes); the current patch level is v1.6.3 from 6 October 2026. For production, the Standard channel with stable v1 resources applies.
An important distinction: the widely discussed retirement concerns ingress-nginx, a single ingress controller - not the Ingress API. This confusion regularly leads to the wrong conclusions. More in the migration guide from ingress-nginx to the Gateway API.
The core difference: one resource vs. a role model
Ingress models the entire entry point in a single resource: hosts, paths, TLS and - via annotations - everything else. In a cluster where several teams share the same public address, that mixes responsibilities: whoever edits the Ingress object inevitably also touches infrastructure concerns like TLS and listeners.
The Gateway API separates these concerns into a role model of several object types (Gateway API roles):
- GatewayClass - the template provided by an infrastructure provider or controller.
- Gateway - the concrete entry point with listeners, ports and TLS, managed by cluster operations.
- HTTPRoute (as well as GRPCRoute, TLSRoute) - the application's routing rules, managed by the respective team.
Each role owns exactly its slice: the provider owns the GatewayClass, cluster operations own the Gateway including TLS termination, application teams own their routes. This is not a cosmetic difference but the reason the Gateway API works cleanly in shared clusters, where Ingress's self-service model reaches its limits.
What Ingress cannot do without annotations
Ingress natively does exactly one thing well: distribute traffic by host and path. Everything beyond that - header-based routing, weighted traffic splitting for canary deployments, path rewriting, CORS, rate limiting - has to be expressed through controller-specific annotations.
That is precisely the structural problem: these annotations are not standardized. An nginx.ingress.kubernetes.io/... annotation does not work with Traefik or HAProxy. The configuration is therefore tied to one controller - switching means rewriting every non-trivial rule. This makes Ingress non-portable and explains why replacing a discontinued controller is so laborious.
The Gateway API lifts these functions into the standardized core: header and method matching, weighted traffic splitting via backendRefs weights, and cross-namespace routing are part of the specification, not of proprietary annotations. Where a function does remain implementation-specific, it is attached via explicit policy objects rather than opaque string annotations. The result is portable across conformant implementations.
Ingress and the Gateway API compared
| Dimension | Ingress | Gateway API |
|---|---|---|
| Status | Stable GA resource, but feature-frozen | Actively developed, GA since v1.0 (Oct 2023), currently v1.6 |
| Model | One resource for everything | Role model: GatewayClass / Gateway / Route |
| Advanced features | Only via controller-specific annotations | Header/method matching, traffic splitting, cross-namespace in the standard |
| Portability | Tied to the controller | Portable across conformant implementations |
| Extension | Opaque string annotations | Explicit, typed policy and filter objects |
| Protocols | HTTP/HTTPS | HTTP, HTTPS, gRPC, TLS, TCP and UDP |
| Service mesh | Not covered | East-west traffic via GAMMA (GA since v1.1) |
| Multi-team clusters | Concerns mixed | Concerns separated by role |
More than ingress: service mesh too
Perhaps the underrated difference: the Gateway API covers not only north-south traffic (from the outside into the cluster, the classic ingress job) but, through the GAMMA initiative, also east-west traffic between services inside the cluster - the service mesh use case.
The same familiar object types like HTTPRoute thus configure both the edge entry and the communication between services. This mesh support has been part of the Standard channel since v1.1 and is considered GA. Ingress does not know this use case at all - it ends at the cluster edge. Anyone planning to introduce a mesh down the line gets a single, consistent model with the Gateway API instead of two separate configuration worlds.
When Ingress still suffices and when the Gateway API
The honest answer is not "always the Gateway API". For a simple, stable setup - one controller, plain host/path routing, no shared clusters, no pressure to change - an existing Ingress installation keeps working technically and is simply less rework.
Reach for the Gateway API when at least one of these applies:
- You run ingress-nginx. The controller has been retired since March 2026, without security patches. Migration is due anyway - so move straight to the successor standard.
- You need advanced routing. Header/method matching, canary by weight, clean cross-namespace routing - natively instead of through annotation hacks.
- Several teams share a cluster. The role model separates infrastructure and application concerns cleanly.
- Portability matters to you. Configuration that is not chained to a single controller.
- A service mesh is on the horizon. One consistent model for north-south and east-west.
And even when none of these forces the issue today: since new functionality lands exclusively in the Gateway API and the official switch is supported by ingress2gateway, it is the forward-looking choice for new clusters. For the practical execution of the switch, the migration guide from ingress-nginx to the Gateway API walks through tooling, annotations and cutover step by step. And anyone planning the rebuild anyway should avoid exposing internal services publicly in the first place and make them reachable privately via NetBird.
