Ingress-nginx EOL is 4 Months Away: Audit Your Ingresses NOW

Random_Round — Thu, 27 Nov 2025 07:38:21 +0000

TL;DR: Last week, Kubernetes announced ingress-nginx retirement by March 2026. We built IMK to audit your clusters for nginx usage and surface migration blockers before you're in panic mode. Open-source, MIT licensed, no magic—just visibility.

The Problem (That's Real)

Last week, the Kubernetes SIG Network announced: ingress-nginx is end-of-life March 2026. Best-effort maintenance ends. No more security patches. No more features.

Some of our infrastructure runs on it. 7 clusters. 200+ Ingress resources. Some configured years ago. Some with annotations nobody remembers why they exist.

What followed was brutal:

Manual audits under pressure: Grep through 100+ YAML files. SSH into each cluster. Cross-reference Helm values. Realize you missed namespaces. Do it again.
The annotation nightmare: nginx.ingress.kubernetes.io/rewrite-target—what's the Gateway API equivalent? Maybe a filter. Maybe a policy. Maybe it's unsupported and requires a custom controller.
Blank HTTPRoute panic: You open the Gateway API spec. It's elegant. It's minimal. How do your 50 nginx-specific settings translate?
The deadline crunch: "We have 4 months." Four months is NOT a lot when you have 200+ ingresses, multiple teams, and no clear path forward.

We realized: time is the real problem. You need visibility fast, not perfect planning.

So we built IMK.

What IMK Does

IMK is an audit and planning tool for Gateway API migrations. It does three things:

Audits fast — Scans manifests or live clusters (multi-context, parallel)
Surfaces blockers — Flags nginx-specific annotations and scores migration difficulty
Generates templates — Creates Gateway API starter YAML so you don't start from blank

What it does NOT do:

Rewrite your Lua scripts (you do that)
Deploy for you (you test, validate, cutover)
Solve your auth schemes (IMK flags them; you architect the solution)
Handle canary/affinity (use Flagger, Cilium, or manual setup)
Tell you if features work with Traefik/Kong/other controllers (Gateway API-specific)

That's the point: The tool gives you the map. You navigate.

How It Works (Real Scenario)

Step 1: Audit Your Clusters

imk scan --all-contexts --all-namespaces \
  --plan-output imk-plan.json \
  --scan-images \
  --image-filter nginx

Runs in parallel. Hits all your clusters. Finds every Ingress. Flags nginx usage. Spots nginx containers in Deployments.

What you see:

NAMESPACE/NAME                        HOSTS               NGINX           DIFFICULTY
default/api-ingress                   api.example.com     class=nginx     LOW
prod/legacy-payments                  *.pay.example       annotations:5   HIGH
infrastructure/logging                logs.internal       none            LOW
prod/admin-dashboard                  admin.internal      class=nginx     MEDIUM

Translation:

✅ api-ingress → Pure nginx, basic config → Easy migration (do first)
🔴 legacy-payments → 5 nginx annotations, unknown complexity → Will hurt (plan for it)
✅ logging → Doesn't use nginx → Skip it
⚠️ admin-dashboard → nginx + some annotations → Medium effort

Now you have a roadmap. You know your 4-month timeline.

Step 2: Understand What Won't Auto-Migrate

imk plan --path ./manifests

Output shows per-ingress difficulty + blockers:

INGRESS: prod/legacy-payments
Difficulty: HIGH
Blockers:
  ✗ nginx.ingress.kubernetes.io/lua-resty-waf → UNSUPPORTED
    (Requires custom controller or manual port)
  ⚠ nginx.ingress.kubernetes.io/auth-url → PARTIAL
    (Needs Gateway API + auth policy controller)
  ✓ nginx.ingress.kubernetes.io/rewrite-target → MAPPED
  ✓ nginx.ingress.kubernetes.io/ssl-redirect → MAPPED

Feature counts: mapped=2, partial=1, unsupported=1

This is the conversation you have with your team on day 1. Not day 100.

Step 3: Get a Starting Point (Don't Start Blank)

imk plan --path ./manifests \
  --gateway-dir ./out \
  --gateway-name my-gateway \
  --gateway-namespace default

Generates:

./out/gateway.yaml — Your Gateway resource
./out/<namespace>-<name>-httproute.yaml — One HTTPRoute per ingress
imk-plan.json — Detailed migration plan with blockers

Sample generated Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: standard
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: api-cert
      - name: legacy-payments-cert

Sample HTTPRoute (with rewrite):

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: legacy-payments-httproute
  namespace: prod
spec:
  parentRefs:
  - name: my-gateway
    namespace: default
  hostnames:
  - pay.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplaceFullPath
          replaceFullPath: /v2/api
    backendRefs:
    - name: payments-service
      port: 8080

You still need to tune auth policy, TLS details, maybe adjust paths. But you're not staring at the HTTPRoute spec wondering what goes where.

What's Actually Supported

Annotations IMK Maps to Gateway API

Fully mapped (will work):

rewrite-target, use-regex → HTTPRoute rewrite filter
permanent-redirect → HTTPRoute redirect filter
ssl-redirect, force-ssl-redirect → HTTPS listener

Partially mapped (needs extra work):

auth-url → Requires auth policy controller (Envoy, etc.)
enable-cors, cors-* → Needs policy or filter
proxy-body-size, proxy-timeout → Policy/extension tuning
limit-rps, limit-connections → Rate-limit policy
websocket-services → Manual HTTPRoute tuning

Not supported (manual porting required):

lua-* (Lua scripts) → Custom controller or manual rewrite
configuration-snippet, server-snippet → Controller-specific behavior
auth-* (auth schemes beyond basic) → Depends on your auth system
canary* (canary deployments) → Use Flagger or similar
affinity* (session affinity) → Manual setup
server-alias, grpc-backend → Requires custom config

See the full annotation coverage list in the README.

The Honest Limitations

What IMK IS

✅ An audit tool (shows what you have)
✅ A planning tool (scores difficulty, surfaces blockers)
✅ A template generator (Gateway API starter YAML)
✅ A decision-making aid ("which ingresses should I tackle first?")

What IMK IS NOT

❌ A silver bullet (some features require manual work)
❌ Controller-agnostic (Gateway API-focused; doesn't know Traefik/Kong/Cilium support)
❌ An auto-converter (generates templates, not production-ready YAML)
❌ A deployment tool (you handle testing, validation, cutover)

If You're Picking Another Controller

If you decide to migrate to Traefik, Kong, or Cilium instead of Gateway API, IMK still helps with the audit ("which ingresses use nginx-specific features?"). But you'd need to check that controller's docs separately for annotation support. IMK is Gateway API-specific.

Getting Started (Right Now)

Install

go install github.com/ubermorgenland/ingress-migration-kit@latest

Or grab a binary from releases.

First scan (manifests)

imk scan --path ./manifests

Output: imk-inventory.json + summary table to stdout.

First scan (live cluster)

imk scan --context my-cluster --all-namespaces

Uses your kubeconfig. Finds all Ingresses.

Generate a migration plan

imk plan --path ./manifests --gateway-dir ./out

See: difficulty scores + generated Gateway/HTTPRoute YAML + imk-plan.json.

Why We Open-Sourced This

Because March 2026 is coming for everyone running ingress-nginx. And migrations shouldn't be opaque or panic-driven.

IMK gives you visibility first. Then you decide: Gateway API, another controller, or hybrid approach. But at least you'll know what you're deciding about.

Feedback Welcome

We built this for our migration. If you're doing the same, try it. If it breaks, file an issue. If it's missing something, tell us.

GitHub: ubermorgenland/ingress-migration-kit
Issues/discussions: Go for it
Contributions: PRs welcome (see CONTRIBUTING.md)

What nginx annotations are you most worried about migrating? We can prioritize.

The Bottom Line

You have 4 months until ingress-nginx stops getting patched. That's enough time if you start today with a clear plan.

IMK gives you that clarity in 10 minutes.

Run it. See your ingresses. Know your effort. Plan your migration.

Don't wait until February.

Forem: Random_Round