Ingress-NGINX is retiring. The hard part isn’t Gateway API. It’s your annotations.

Why hosts-and-paths conversion isn’t enough, and how GateShift helps you migrate without silently dropping production behavior. Tags: Kubernetes GatewayAPI Ingress DevOps PlatformEngineering OpenSource CloudNative

Most Ingress → Gateway API migrations look fine in the PR. Then production traffic shows what quietly disappeared: rate limits, redirects, cert-manager wiring, canaries, and snippets. Hosts and paths usually convert. Annotations often don’t.

The real problem

Kubernetes announced the retirement of Ingress-NGINX.

Best-effort maintenance continues until March 2026. After that: no releases, no bugfixes, and no updates for new security vulnerabilities. Existing clusters won’t magically stop routing traffic on that date. That’s exactly why it’s dangerous. You can keep running it until the day a new CVE has nowhere to go. So teams are moving to Gateway API. That is the right direction.

But here’s the catch.

Ingress was always a thin API. Ingress-NGINX filled the gaps with annotations. For years, production behavior lived here:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: checkout
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /app
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/limit-rps: "20"
    nginx.ingress.kubernetes.io/enable-cors: "true"
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/configuration-snippet: |
      more_set_headers "X-Frame-Options: DENY";
spec:
  rules:
    - host: checkout.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: checkout
                port:
                  number: 80

That one object is not “just routing.” It’s rewrite policy, TLS redirects, rate limiting, CORS, certificate automation, and custom NGINX behavior.

Why “just convert the YAML” fails

Community converters help. Tools like ingress2gateway can turn Ingress into Gateway / HTTPRoute drafts and translate a growing set of annotations. That is useful.

It is also incomplete for real clusters.Anyone who has done this in production has seen some version of: valid YAML ≠ same behavior

Common surprises:

1. Path matching gets stricter Ingress-NGINX quirks (regex host-wide effects, trailing-slash redirects, case sensitivity) do not always match Gateway controllers.
2. Timeouts and body limits change Defaults differ by implementation. What was implicit in NGINX becomes explicit Policy or silent drift.
3. Snippets don’t translate configuration-snippet / server-snippet were powerful and unsafe. They also don’t map cleanly to Gateway API. If a tool drops them quietly, you lose behavior and sometimes security assumptions.
4. Canaries and affinity need more than a rename Weighted backends and session cookies often become controller-specific Policy or HTTPRoute weight wiring.

The industry already has good writing on EOL and controller choice (Datadog, Kubernetes blog, field migration guides). What’s still underserved is a practical question:

After conversion, do I know what was kept, what needs a Policy CRD, and what still needs a human?

What a safe migration actually needs

A good migration is not one command. It’s a loop:

1. Inventory every migration annotation
2. Classify automatic vs Policy vs manual
3. Validate against your target controller (Envoy Gateway, Cilium, Istio, Kong, …)
4. Dual-run keep Ingress live, send shadow traffic to Gateway, compare
5. Cut over DNS / listeners last; delete Ingress only when you’re sure

That dual-run step matters more than a perfect first convert. Platform teams already do this manually with two load balancers and careful DNS. The tooling should make that path obvious.

Introducing GateShift

I built GateShift for that problem.

GateShift is an open-source CLI (with an optional operator) for Ingress → Gateway API migration with clearer annotation fidelity.

It classifies features into three levels:

The point is simple: nothing important should disappear silently.

Repo: https://github.com/vi-shub/gateshift

Install

curl -fsSL https://raw.githubusercontent.com/vi-shub/gateshift/main/scripts/install.sh | bash

Or build from source:

git clone https://github.com/vi-shub/gateshift.git
cd gateshift
make tidy test build

A practical workflow

1. Audit first

gateshift audit -f ingress.yaml - target=envoy-gateway

You’ll get an L1 / L2 / L3 matrix and a readiness score. This is the “what am I actually migrating?” step.

2. Convert

gateshift convert -f ingress.yaml - target=envoy-gateway -o gateway.yaml

3. Validate against the controller

gateshift validate -f ingress.yaml - target=envoy-gateway

Valid Gateway API YAML can still be unschedulable if your controller doesn’t support the features you emitted. Validate is the fail-closed gate.

4. Dual-run before cutover

gateshift dual-run -f ingress.yaml - target=envoy-gateway -o dual-run.yaml

This keeps Ingress live. It emits a staging Gateway and a shadow HTTPRoute (annotated gateshift.io/mode=dual-run) so you can compare behavior before flipping production DNS.

For Ingress-NGINX behavioral quirks (regex host-wide effects, trailing slash redirects), GateShift can also emit preserve options when you need closer parity:

gateshift convert -f ingress.yaml - target=envoy-gateway \
 - preserve-nginx-regex \
 - emit-trailing-slash-redirects \
 -o gateway.yaml

Gateway API is the future of Kubernetes edge routing.Annotation honesty is how you get there without a weekend outage.

If you’re planning an Ingress-NGINX migration (or already mid-flight), try GateShift and tell me what your cluster still trips on.

GitHub: https://github.com/vi-shub/gateshift

Further Reading

Want to dive deeper? Check out these essential resources:

• **Kubernetes Gateway API Official Documentation** — Complete API reference and guides
• **NGINX Gateway Fabric Documentation** — Official implementation docs
• **Ingress NGINX Retirement Announcement** — Official Kubernetes blog post
• **Gateway API Implementations Comparison** — Compare different vendors
• Gateshift — Migration tool source code
• **cert-manager Documentation** — TLS certificate management

About Me

I’m a DevOps Engineer specializing in Kubernetes, cloud-native architectures, and production reliability engineering. Through this blog, I share real-world experiences from managing large-scale container orchestration platforms — the challenges, solutions, and lessons learned along the way.

Have questions or want to share your own Gateway API migration experiences? **Connect with me on LinkedIn** or leave a comment below! I’d love to hear about your Kubernetes journey.