# Kubernetes Ingress vs Gateway API: Migrating Without Downtime

URL: https://www.devopsness.com/blog/kubernetes-ingress-vs-gateway-api-migration
Author: Kiril Urbonas
Published: 2026-07-04
Updated: 2026-10-31
Categories: DevOps
Tags: Kubernetes, Networking, Ingress, Migration, DevOps

Summary: 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.

---
# Kubernetes Ingress vs Gateway API: Migrating Without Downtime

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]
> 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.

```yaml
# 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 model | Who owns what | Advanced routing | Vendor features via | Status (Oct 2026) |
|---|---|---|---|---|---|
| Ingress | One `Ingress` plus `IngressClass` | One persona edits everything | Host and path only | Annotations | API frozen; Ingress NGINX retired, no security fixes after March 2026 |
| Gateway API | `GatewayClass`, `Gateway`, `HTTPRoute` and friends | Platform owns Gateways, app teams own Routes | Header, query and method matching, weights, mirroring, redirects | Policy resources, no annotations | Active; 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](/blog/fix-ingress-502-504) 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.

```hcl
# 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

- [Kubernetes Blog: Ingress NGINX retirement announcement](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/)
- [Gateway API docs: Migrating from Ingress](https://gateway-api.sigs.k8s.io/guides/getting-started/migrating-from-ingress/)
- [Gateway API v1.7.0 release notes](https://github.com/kubernetes-sigs/gateway-api/releases/tag/v1.7.0)
- [Amazon Route 53 Developer Guide: Weighted routing](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy-weighted.html)

