Skip to main content

Ingress NGINX Controller Deprecation: Your Migration Guide to Kubernetes Gateway API

8 min read
Cody Landstrom
Senior Product Manager
The NGINX logo, for Ingress NGINX, with an arrow to the Kubernetes logo, for the Gateway API

The Kubernetes project announced in November 2025 that the Ingress NGINX Controller will be retired on March 31st, 2026.

It's one of the most widely used ingress controllers in Kubernetes. It's what countless tutorials recommend, and it's probably what you're running in production right now. In three months, it stops receiving security patches, bug fixes, and compatibility updates.

We've been evaluating what this means for Okteto and the broader Kubernetes ecosystem. Here's our analysis, how to translate your Ingress resources to the Gateway API, and a decision framework that might help if you're navigating this transition.

What's Actually Happening with the Ingress NGINX Deprecation​

The Kubernetes Ingress API itself is not being deprecated. You can still create Ingress resources. What's being retired is the specific NGINX-based controller that implements that API, the kubernetes/ingress-nginx project.

The retirement creates three operational risks:

Security vulnerabilities won't receive patches. After March 2026, CVEs discovered in the Ingress NGINX Controller won't be fixed upstream. You'll need to maintain your own fork or accept the security exposure.

Bug fixes end permanently. When ingress routing breaks or behaves unexpectedly, there's no upstream maintainer to file issues with or expect resolution from.

Kubernetes compatibility will degrade over time. New Kubernetes releases will keep changing, and nobody will adapt the controller to them. Sooner or later, a Kubernetes upgrade will break it.

Note that the retirement affects only the kubernetes/ingress-nginx project. F5's NGINX Ingress Controller, available in an open source and a commercial edition, is a separate codebase with its own lifecycle, and it remains maintained.

Why Kubernetes is Moving to Gateway API​

The Ingress API served the ecosystem during Kubernetes' early years, but its design assumptions no longer match how production platforms operate. Three limitations drove the need for a replacement:

Annotation-based configuration creates vendor lock-in. The Ingress API covers little more than hosts and paths, so every controller implements essential features through its own annotations or custom resources. A request timeout is nginx.ingress.kubernetes.io/proxy-read-timeout on Ingress NGINX, and something else on every other controller. Switching controllers means rewriting your routing configuration.

Role boundaries don't exist. Platform operators, application developers, and security teams all modify the same Ingress resources. A developer adding a route to their service can also change settings that should belong to the platform team, and the Ingress API provides no way to separate them.

Traffic management capabilities are limited. Modern applications need canary deployments with traffic splitting, header-based routing, and request mirroring. The Ingress API can't express these patterns, and each controller invents extensions that don't work anywhere else.

Gateway API addresses these problems. It provides role-separated resources (GatewayClass for infrastructure providers, Gateway for platform teams, HTTPRoute for developers), configuration that works across implementations, and traffic management built into the specification.

The ecosystem has already committed to this direction. Istio, Envoy Gateway, Cilium, Kong, Traefik, Contour, and the major cloud providers implement Gateway API today. This is Kubernetes' established roadmap, not speculation about future possibilities.

From Ingress to HTTPRoute​

Here's an Ingress that sends the requests for app.example.com/api to the api Service, with a timeout set through an Ingress NGINX annotation:

ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app
annotations:
nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: api
port:
number: 8080

With Gateway API, the platform team creates a Gateway, the entry point that receives the traffic, with the GatewayClass of the controller they choose:

gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web-gateway
spec:
gatewayClassName: example
listeners:
- name: http
protocol: HTTP
port: 80

And developers attach HTTPRoutes to it. The routing and the timeout are now part of the specification, so they work the same way on any controller:

httproute.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: app
spec:
parentRefs:
- name: web-gateway
hostnames:
- app.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: api
port: 8080
timeouts:
request: 60s

The two timeouts don't measure exactly the same thing (the annotation limits the time between two reads from the backend, and timeouts.request the whole request), so check what each one covers when you translate them. To convert many Ingress resources at once, the Kubernetes project maintains ingress2gateway, a tool that translates Ingress resources, including some controller-specific annotations, into Gateway API resources.

Real-World Migration Strategy: How We're Approaching This at Okteto​

Okteto's platform depends on ingress infrastructure for generating HTTPS endpoints and routing development environment traffic. This deprecation directly affects our core functionality.

We analyzed three migration strategies:

Replace NGINX with another Ingress controller. This minimizes immediate disruption but keeps the same architectural problems. We'd remain dependent on annotation-based configuration and controller-specific behaviors, and we'd face the same migration pressure when the replacement controller reaches end-of-life.

Migrate completely to Gateway API with Ingress compatibility layers. This aligns with Kubernetes' long-term direction but requires building complex translation mechanisms between networking models. We'd need to handle edge cases where Ingress semantics don't map to Gateway API primitives while supporting both during the transition.

Implement hybrid support for both networking models. Keep Ingress working for existing workloads while building new features on Gateway API. This enables incremental modernization without disrupting operational systems.

We chose the hybrid approach because it balances technical debt reduction with platform stability.

The architectural principle guiding our decision: depend on APIs, not implementations. Platform resilience comes from abstractions that multiple controllers can satisfy, not tight coupling to specific controller behaviors.

Gateway API provides exactly that abstraction layer. We can implement features once and support customer choice in the underlying networking infrastructure.

Practical Next Steps for Platform Teams​

This decision framework applies regardless of whether you're running Okteto or managing your own Kubernetes infrastructure:

Inventory your annotation dependencies now. Every nginx.ingress.kubernetes.io/* annotation is technical debt that needs a migration. Catalog the controller-specific configuration in your manifests, and focus on the annotations that implement business logic rather than basic routing: those are the hardest to migrate.

Assess your controller's Gateway API maturity. A controller without Gateway API support is a long-term risk. You don't need to migrate immediately, but knowing your options prevents crisis-driven decisions. Established Gateway API implementations include Envoy Gateway, Istio, Cilium, Kong, Traefik, and Contour.

Evaluate whether bundling controllers still makes sense. If your platform ships with embedded ingress controllers, reconsider that choice. Every bundled controller creates ongoing CVE tracking, compatibility testing, and support obligations. Letting customers provide their own networking infrastructure while you deliver higher-level abstractions often proves more sustainable.

Design for portability over convenience. Build platform features that work regardless of which Gateway API controller customers deploy. This discipline creates resilience against future infrastructure changes while reducing your maintenance burden.

What This Means for Okteto Users​

Okteto supports Gateway API for the endpoints of your applications and for the Okteto control plane, and works with any Gateway controller that implements it. We run our end-to-end tests against Envoy Gateway, Istio, and Kong.

Following our own advice, Okteto Chart 2.0 will make Gateway API the default and stop bundling NGINX Ingress controllers: you'll bring the Gateway controller you choose, and Okteto will create the routes. The Migrate to Gateway API guide explains how to move your instance before that upgrade.

In the meantime, Okteto maintains a fork of Ingress NGINX where we patch security fixes for the NGINX Ingress controllers that Okteto ships, so your instance doesn't run an unpatched controller while you migrate.

Infrastructure Evolution as Platform Opportunity​

The Ingress NGINX Controller retirement is the ecosystem maturing, not an arbitrary disruption. Kubernetes networking is moving from early defaults toward portable abstractions that serve production requirements better.

For platform teams, this is an opportunity to reduce technical debt, gain flexibility, and align with Kubernetes' direction. The migration pays off through less vendor coupling, better portability across clouds, and more predictable upgrades.

If you're navigating this transition, we'd like to hear about your approach. Migration challenges are similar across platforms, and sharing what worked and what didn't benefits the whole community.

The March 2026 deadline might feel aggressive, but it's pushing the ecosystem toward more maintainable infrastructure. That makes the migration effort worthwhile.