Kubernetes Ingress vs Gateway API: What's the Difference

Ingress is Kubernetes’ original API for routing external HTTP(S) traffic to services inside a cluster; Gateway API is its successor, a more expressive and role-oriented resource model designed to fix Ingress’s structural limitations. Both solve the same basic problem — getting traffic from outside the cluster to the right internal service — but they differ sharply in how much you can express without vendor-specific extensions.

What Ingress does and where it breaks down

An Ingress resource is a small, declarative spec: match a host and path, send matching traffic to a backend Service. It’s implemented by an Ingress controller — nginx, Traefik, and cloud-provider controllers are common choices — which reads Ingress objects and configures a real load balancer or reverse proxy accordingly.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-ingress
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 80

The problem is that this spec covers only the simplest case. Anything beyond host/path routing — traffic splitting for canary releases, header-based routing, request mirroring, cross-namespace routing, TCP or gRPC routing instead of HTTP — isn’t part of the Ingress spec at all. Every controller invented its own annotations block to fill the gap, so a working Ingress manifest for nginx often doesn’t translate to Traefik or a cloud load balancer without rewriting the annotations. Ingress became portable only for the basics; everything interesting was vendor lock-in by another name.

What Gateway API changes

Gateway API is a full redesign, not a patch. Its central idea is splitting the single Ingress object into role-scoped resources that map onto who actually owns each piece of a real routing setup:

• GatewayClass — defines an implementation (cloud provider, a specific proxy), managed by infrastructure providers.
• Gateway — a deployed instance of listeners (ports, protocols, TLS), typically owned by a platform or cluster-ops team.
• HTTPRoute / GRPCRoute / TCPRoute — the actual routing rules, owned by application teams and attached to a Gateway.

This split matters operationally: an application team can create and modify their own HTTPRoute without needing permission to touch the shared Gateway resource that a platform team manages. Ingress had no equivalent separation — a single flat object mixed infrastructure concerns (TLS termination, listener ports) with application concerns (path routing) in one resource that anyone could edit.

Gateway API also standardizes what used to be per-vendor annotations: traffic weighting for canary rollouts, header and query-param matching, request/response header modification, and cross-namespace route binding are all part of the core spec, portable across any conformant implementation.

Side-by-side comparison

	Ingress	Gateway API
Core capability	Host/path HTTP routing	HTTP, gRPC, TCP, UDP routing
Traffic splitting / canary	Vendor annotations only	Native (HTTPRoute weights)
Role separation	None — one flat resource	Gateway (infra) vs Route (app teams)
Cross-namespace routing	Not supported	Native, with explicit permission grants
Portability across implementations	Low — annotations diverge	High — conformance test suite
Maturity	Stable, ubiquitous	Stable (GA), broadly implemented

Do you need to migrate

Not urgently, and not wholesale. Ingress remains a supported, stable API — it isn’t deprecated, and simple host/path routing setups work fine on it indefinitely. The case for Gateway API strengthens as your routing needs grow: if you’re hand-writing controller-specific annotations for traffic splitting, if multiple teams need to own routing rules without stepping on each other, or if you’re routing non-HTTP protocols through the same infrastructure, Gateway API’s native support removes real friction that Ingress annotations were papering over.

Most Gateway API implementations can run alongside existing Ingress resources during a transition, which makes an incremental migration — new routes on Gateway API, existing ones left on Ingress until they need the extra capability — a reasonable default rather than a forced cutover.

Where this fits in the broader traffic-routing picture

Both Ingress and Gateway API solve north-south routing — traffic entering the cluster from outside. They’re a different concern from a service mesh, which typically handles east-west traffic between services inside the cluster (retries, mTLS, fine-grained internal traffic policy). Some service mesh projects have adopted Gateway API as their configuration surface for both directions, which is part of why the spec has gained traction — it’s converging into a shared vocabulary for “how do I describe a routing rule” across what used to be separate tools. It’s also worth distinguishing both from an API gateway in the application sense — a component that does authentication, rate limiting, and request transformation at the edge; Gateway API’s Gateway/HTTPRoute resources can back that kind of edge gateway, but the Kubernetes API itself is only concerned with routing, not the broader API-management feature set. If you’re new to how these pieces sit together, Kubernetes vs Docker is a good starting point for the underlying orchestration layer both APIs configure.

The takeaway

Ingress is the simple, stable, but limited original — fine for basic host/path routing, awkward the moment you need anything a controller’s custom annotations don’t cover. Gateway API splits routing into role-scoped resources, standardizes traffic splitting and protocol support that used to require vendor lock-in, and is the better foundation for anything beyond the simplest setups. You don’t need to rip out working Ingress manifests today, but new, non-trivial routing work is a reasonable place to start using Gateway API instead.