Kubernetes Gateway API vs Ingress: Why It Replaces Annotations

I have run traffic through Ingress for years, and the pattern always rots the same way. You start with a clean host-and-path spec, then a TLS quirk appears, then a rewrite, then a rate limit, and six months later your Ingress manifest is a wall of controller-specific annotations that only one person on the team understands. Ingress was standardized in 2015 and its spec barely moved; every feature past basic host routing had to be smuggled in through annotations that are not portable between controllers.

The Gateway API fixes the root cause, not the symptom. It reached its stable v1 milestone and is now at version 1.5.x, with the API group gateway.networking.k8s.io. The timing matters: on March 24, 2026, the kubernetes/ingress-nginx project reached end of life. The repository is read-only, and there will be no more bug fixes or CVE patches. If you run ingress-nginx today, migration is no longer a nice-to-have.

The one resource that tried to do everything

The core design flaw of Ingress is that a single resource mixes two completely different jobs. It describes where traffic enters the cluster (the load balancer, its IP, its TLS certificates) and how traffic is routed to services (hosts, paths, backends) in the same object. In most organizations those are owned by different people: a platform or infrastructure team owns the edge, and application teams own their own routes. Ingress forces both concerns into one manifest, so either the platform team becomes a bottleneck approving every route change, or app teams get write access to the shared edge and can break each other.

The Gateway API splits that single resource along the exact lines your org chart already follows. There are three main resources, each with a clear owner.

• GatewayClass: the template for a kind of gateway, tied to a specific controller implementation. An infrastructure provider or the controller vendor owns this, and you usually install it once per cluster.
• Gateway: an actual entry point. It declares listeners (ports, protocols, TLS certificates) and which routes are allowed to attach. The platform or cluster operator team owns this.
• HTTPRoute: the routing rules, hosts, paths, header matches, rewrites, and traffic splits. Application developers own these in their own namespace and ship them alongside their app.

An HTTPRoute attaches to a Gateway through a parentRefs field, and the Gateway decides via its allowedRoutes rules which namespaces may attach. That is the whole trick: the platform team locks down the edge and TLS once, then hands developers a safe, self-service surface for their own routing. No shared file, no annotation review bottleneck, no accidental blast radius across teams.

Why annotations had to go

Here is the same idea in code. Below is a typical ingress-nginx manifest: a handful of standard fields plus a stack of annotations that only ingress-nginx understands. Move it to Traefik or HAProxy and those annotations mean nothing.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
spec:
  ingressClassName: nginx
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api(/|$)(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: api
                port:
                  number: 80

The canary weight, the rewrite, the SSL redirect: none of that is in the Ingress spec. It lives in vendor annotations, which is why an Ingress manifest is not really portable. The Gateway API pulls those features into typed, first-class spec fields. Here is the equivalent HTTPRoute with a path rewrite and a 20 percent traffic split expressed natively.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: shop-team
spec:
  parentRefs:
    - name: prod-gateway
      namespace: infra
  hostnames:
    - shop.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: api-v1
          port: 80
          weight: 80
        - name: api-v2
          port: 80
          weight: 20

Ingress versus Gateway API at a glance

A migration path that does not require a big bang

The good news is that Ingress and the Gateway API can run side by side in the same cluster, so you migrate one service at a time. The Kubernetes SIG-Network team also shipped ingress2gateway 1.0 in March 2026, a CLI that reads your existing Ingress resources and generates equivalent Gateway and HTTPRoute manifests, including translation of more than thirty common ingress-nginx annotations. It is a starting point, not a rubber stamp: always review the output.

1. Install a conformant controller (Envoy Gateway, kgateway, Traefik, or a cloud provider implementation) and its GatewayClass alongside your existing Ingress controller.
2. Have the platform team create one Gateway with your listeners and TLS certificates, and set allowedRoutes to the namespaces that need it.
3. Run ingress2gateway against one low-risk service to generate its HTTPRoute, then review and commit the manifest.
4. Validate routing parity: hosts, paths, rewrites, headers, and TLS all behave the same as the old Ingress.
5. Cut DNS or traffic over to the Gateway once metrics and SLOs match, then delete the old Ingress. Repeat per service.

Should you migrate now?

If you are on ingress-nginx, yes, and with some urgency, because it no longer receives security patches after its March 2026 end of life. If you run a managed cloud Ingress or another controller that is still supported, you have more time, but the direction of travel is settled: the Ingress spec is frozen and every new networking feature is landing in the Gateway API. For anything greenfield, I would not start a new cluster on Ingress in 2026. Start on the Gateway API, get the role boundaries right on day one, and skip the annotation-soup phase entirely.