Skip to main content
Kubernetes Ingress vs Gateway API: Migrating Without Downtime

Kubernetes Ingress vs Gateway API: Migrating Without Downtime

KU
· Founder & Chief Editor
• 7 min read•Updated •

How to move services off the nginx Ingress controller onto Gateway API by running both side by side and shifting traffic with weighted DNS, so the cutover stays boring.

Key takeaways

  • Migrate from Ingress to Gateway API without downtime by running both edges in parallel, each with its own load balancer.
  • Convert each Ingress to an HTTPRoute, test it with curl --resolve against the new IP, then shift traffic with weighted DNS starting at 5 percent.
  • Ingress NGINX stopped receiving security fixes after March 2026, so plan the move now.

Migrate from Ingress to Gateway API without downtime by running both controllers side by side on separate load balancers, translating each Ingress into an HTTPRoute, testing it with curl --resolve against the new IP, then shifting DNS weight gradually. If you run Ingress NGINX, this is no longer optional: it stopped getting security fixes after March 2026.

Verified against

Gateway API v1.7.0 (released 2026-10-29), ingress2gateway v1.2.0, against the Gateway API migration guide, the Kubernetes Ingress NGINX retirement notice and the Amazon Route 53 weighted routing docs. Checked October 2026.

The thing that finally pushed us off Ingress wasn't a feature. It was a 200-line annotation block on a single Ingress object that nobody on the team could fully explain. Half of it was nginx-specific rewrite rules, the rest was rate limiting glued on through nginx.ingress.kubernetes.io/limit-rps, and every change meant reloading the whole controller and hoping the config passed the lint step. When a junior engineer added a trailing-slash rewrite and knocked out checkout, we booked the Gateway API migration for real.

Why the annotation soup exists

Ingress was designed as a lowest-common-denominator spec. It gives you host and path routing and TLS, and nothing else. Every vendor bolted their real features on through annotations, so an Ingress written for nginx is useless on Traefik or Contour. You aren't writing portable config, you're writing nginx config in a Kubernetes costume.

Gateway API splits that mess into typed resources. Cluster operators own GatewayClass and Gateway (the listeners, ports, TLS certs). App teams own HTTPRoute objects that attach to those gateways. Header matching, traffic weighting, redirects and request mirroring are first-class fields, not string annotations a typo can silently break. The project's migration guide is blunt that Gateway API resources do not accept annotations as an extension point at all; anything vendor-specific goes through policies or external references.

gateway-system/edge-gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: edge
  namespace: gateway-system
spec:
  gatewayClassName: envoy
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.devopsness.io"
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-devopsness-tls
      allowedRoutes:
        namespaces:
          from: All

Ingress vs Gateway API at a glance

Resource modelWho owns whatAdvanced routingVendor features viaStatus (Oct 2026)
IngressOne Ingress plus IngressClassOne persona edits everythingHost and path onlyAnnotationsAPI frozen; Ingress NGINX retired, no security fixes after March 2026
Gateway APIGatewayClass, Gateway, HTTPRoute and friendsPlatform owns Gateways, app teams own RoutesHeader, query and method matching, weights, mirroring, redirectsPolicy resources, no annotationsActive; v1.7.0 released 2026-10-29

Don't hand-write the first draft of each route

The ingress2gateway tool from Kubernetes SIG Network reads your existing Ingress objects and prints equivalent Gateway API resources. It understands Ingress NGINX annotations as a provider:

Bash
brew install ingress2gateway
ingress2gateway print --providers=ingress-nginx -n checkout > checkout-routes.yaml
kubectl apply --dry-run=server -f checkout-routes.yaml

Treat the output as a starting point. The official guide says conversion results "should always be tested and verified," and anything implementation-specific (rate limits, auth snippets, custom error pages) either lands in your new controller's policy CRDs or gets dropped. Diff the generated rules against what the annotations actually did, not what you think they did.

The part that keeps you online

The migration only works if both stacks answer traffic during the cutover. We ran the existing nginx Ingress controller and an Envoy Gateway side by side, each on its own LoadBalancer service with its own external IP. DNS still pointed at nginx.

For each service we wrote an HTTPRoute that mirrored the existing Ingress rules, attached it to the new Gateway, and tested it by hitting the Envoy IP directly:

Bash
curl -sk --resolve api.devopsness.io:443:203.0.113.44 \
    https://api.devopsness.io/healthz

That --resolve flag is the whole game. You exercise the real route, TLS and SNI included, without touching production DNS. We caught two broken path prefixes and one missing Host rewrite this way before any user saw the new path. If the new edge returns 502s or 504s instead, the causes are the same as on any proxy; our 502/504 ingress checklist applies almost unchanged.

Weighted cutover at the DNS layer

Once a route passed checks, we shifted traffic with a weighted DNS record in Route 53 rather than flipping it all at once. Route 53 sends each record its weight's share of the total, so 5 and 95 means 5 percent to Envoy. Start there, watch p99 latency and 5xx rate for 20 minutes, then ramp.

dns/api-envoy.tf
resource "aws_route53_record" "api_envoy" {
  zone_id        = var.zone_id
  name           = "api.devopsness.io"
  type           = "A"
  set_identifier = "envoy"

  weighted_routing_policy {
    weight = 5
  }

  alias {
    name                   = aws_lb.envoy.dns_name
    zone_id                = aws_lb.envoy.zone_id
    evaluate_target_health = true
  }
}

Our old nginx record stayed at weight 95 and dropped as Envoy climbed. Because both stacks routed to the same pods, a request landing on either edge behaved identically. Keep your record TTL low before you start, or the ramp lags behind resolver caches.

The one gotcha: sticky sessions. If you rely on nginx.ingress.kubernetes.io/affinity: cookie, Gateway API's session persistence is still an experimental-channel feature, and v1.7.0 moved it again, onto the XBackend resource, deprecating the route-inline and BackendTrafficPolicy attachment points. Support varies by implementation. Check what yours actually ships before ramping anything with sessions.

What actually broke

Two things. First, request body size. Ingress NGINX maps proxy-body-size to nginx's client_max_body_size, which defaults to 1m, and we had raised it to 25MB via annotation. Our Envoy Gateway setup carried no matching cap, so uploads that nginx used to reject suddenly went through and hit an app bug nobody knew about. Fix your app, don't just match the limit.

Second, header casing. A legacy internal client sent X-Request-Id and read back x-request-id. nginx handled casing in a way the client tolerated; Envoy normalized it differently. Cost us an hour of confused debugging. Grep your clients for case-sensitive header reads before you migrate anything old.

Questions people ask

Is Kubernetes Ingress deprecated?

The Ingress API is not removed; it is frozen, with new features going into Gateway API. What changed is the most popular controller: Kubernetes SIG Network retired Ingress NGINX, with best-effort maintenance ending in March 2026 and no further releases or security fixes after that. Existing installs keep running, but if you stay on Ingress, move to another maintained Ingress controller or to Gateway API.

Can Ingress and Gateway API run in the same cluster?

Yes, and that is the safe way to migrate. They are separate APIs served by separate controllers, so an Ingress controller and a Gateway implementation can each own their own load balancer and external IP while routing to the same Services. Run both, move hostnames one at a time with weighted DNS, and delete each Ingress only after its traffic has fully drained.

Is there a tool to convert Ingress to Gateway API?

Yes. ingress2gateway, maintained by Kubernetes SIG Network, reads Ingress resources (including Ingress NGINX annotations via --providers=ingress-nginx) and prints Gateways and HTTPRoutes. It reached 1.0 and is at v1.2.0 as of October 2026. Treat its output as a draft: implementation-specific annotations such as rate limits or auth snippets need a manual equivalent in your new controller's policies.

The call we'd make

If you're on a single cluster with five services and a maintained, non-nginx Ingress controller that's quiet, leave it; the Ingress API still works. If you're on Ingress NGINX, the decision is already made for you, because an unpatched edge proxy is the wrong place to save effort. And the moment you have multiple teams fighting over one Ingress object, or you're copy-pasting annotations you don't understand, move to Gateway API. Run both edges in parallel, cut over with weighted DNS at 5 percent, and keep the --resolve trick in your pocket. Deleting that 200-line annotation block felt better than any feature ever could.

Sources

Explore topics:KubernetesDevOps
React
Share this post
Cite this article
Plain text

Kiril Urbonas (2026). Kubernetes Ingress vs Gateway API: Migrating Without Downtime. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/kubernetes-ingress-vs-gateway-api-migration

Markdown

[Kubernetes Ingress vs Gateway API: Migrating Without Downtime](https://www.devopsness.com/blog/kubernetes-ingress-vs-gateway-api-migration) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

608 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.