Ingress Migration Strategy: From Deprecated Controllers to Gateway API

The Kubernetes community's announcement of Ingress NGINX's retirement in March 2026 has created an urgent need for migration planning across thousands of production clusters. With no security patches, bug fixes, or updates coming after the final v1.15.1 release, organizations must act now to avoid running unmaintained software with escalating security risks.

This isn't just about swapping one ingress controller for another. It's an opportunity to modernize your Kubernetes networking stack with better abstractions, improved security models, and future-proof architectures. This guide provides a practical framework for evaluating your options and executing a zero-downtime migration.

Understanding Your Current State

Before choosing a migration path, you need to audit what you're actually using. The migration assessment tool helps identify feature dependencies, but start with this basic check:

kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx

If this returns pods, you're affected. Now catalog your ingress resources and their complexity:

kubectl get ingress --all-namespaces -o yaml > current-ingress-config.yaml
kubectl get configmap -n ingress-nginx ingress-nginx-controller -o yaml > current-configmap.yaml

Pay special attention to:

• Custom annotations beyond basic path routing
• ConfigMap customizations for global behavior
• TCP/UDP services configuration
• SSL/TLS termination patterns
• Rate limiting and authentication rules

The complexity of these configurations will determine your migration strategy and timeline.

Migration Path Options

You have three primary migration targets, each with distinct trade-offs:

F5 NGINX Ingress Controller

The most direct path for teams heavily invested in NGINX-specific features. NGINX Ingress Controller v5.4.0 introduces native validation and CORS support specifically to ease ingress-nginx migrations.

Best for: Organizations with complex NGINX configurations, custom snippets, or NGINX Plus licensing.

Migration complexity: Low to medium, depending on annotation usage.

Gateway API with Envoy Gateway

The forward-looking choice that embraces Kubernetes' networking future. Gateway API provides role-based configuration, better traffic management primitives, and vendor neutrality.

Best for: Teams building new applications or willing to invest in modern Kubernetes networking patterns.

Migration complexity: Medium to high, requires rethinking traffic management concepts.

Cloud Provider Solutions (ALB, GKE Ingress, etc.)

Platform-specific controllers that integrate deeply with cloud load balancers. AWS recommends migrating to AWS Load Balancer Controller first, then to Gateway API when ready.

Best for: Teams already committed to a specific cloud platform.

Migration complexity: Medium, with vendor lock-in considerations.

Risk Assessment Framework

Evaluate each migration option against these critical factors:

Feature Parity Analysis

Not every ingress-nginx feature has direct equivalents in alternative controllers. Create a feature mapping document:

# Example feature assessment
current_features:
  - ssl_redirect: "nginx.ingress.kubernetes.io/ssl-redirect"
  - rate_limiting: "nginx.ingress.kubernetes.io/rate-limit"
  - custom_headers: "nginx.ingress.kubernetes.io/configuration-snippet"

migration_gaps:
  nginx_controller:
    - ssl_redirect: "Direct annotation support"
    - rate_limiting: "VirtualServer CRD required"
    - custom_headers: "Policy CRD recommended"

  gateway_api:
    - ssl_redirect: "HTTPRoute redirect filter"
    - rate_limiting: "Implementation-specific policy"
    - custom_headers: "ExtensionRef to controller policy"

Operational Impact

Consider the blast radius of your migration:

• Traffic patterns: Peak load times when you can't afford disruption
• Team expertise: Learning curve for new APIs and troubleshooting
• Tooling integration: CI/CD pipelines, monitoring, and GitOps workflows
• Compliance requirements: Change management and approval processes

Security Implications

Each migration path has different security characteristics:

• NGINX Ingress Controller: Familiar security model, but requires ongoing license management for Plus features
• Gateway API: Role-based access control (RBAC) with separation of concerns between platform and application teams
• Cloud controllers: Integration with cloud IAM and security services

Zero-Downtime Migration Patterns

Pattern 1: Parallel Controller Migration

Run both controllers simultaneously during the transition period. This approach minimizes risk but requires careful traffic management.

# Install new controller in separate namespace
kubectl create namespace nginx-ingress-new

# Deploy with different ingress class
helm install nginx-ingress-new nginx-stable/nginx-ingress \
  --namespace nginx-ingress-new \
  --set controller.ingressClass=nginx-new

Gradually migrate services by updating the ingressClassName field:

# Before
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-app
spec:
  ingressClassName: nginx  # Old controller
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

# After
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-app
spec:
  ingressClassName: nginx-new  # New controller
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

Pattern 2: Blue-Green Cluster Migration

For organizations with sophisticated deployment pipelines, migrating entire clusters provides the cleanest separation.

# Create new cluster with target ingress controller
# Deploy applications to new cluster
# Switch DNS/load balancer traffic
# Decommission old cluster

This pattern works well with GitOps workflows where infrastructure and applications are versioned together.

Pattern 3: Gateway API Progressive Migration

When migrating to Gateway API, start with basic HTTP routing and gradually adopt advanced features:

# Phase 1: Basic routing
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-app
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - app.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: example-service
      port: 80

# Phase 2: Add traffic policies
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-app
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - app.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        statusCode: 301
    backendRefs:
    - name: example-service
      port: 80

Migration Execution Strategy

Phase 1: Preparation (Weeks 1-2)

1. Audit current configuration using the NGINX migration tool
2. Set up staging environment that mirrors production traffic patterns
3. Train team members on new APIs and troubleshooting approaches
4. Update monitoring and alerting for new controller metrics and logs

Phase 2: Pilot Migration (Weeks 3-4)

1. Select low-risk applications with simple routing requirements
2. Deploy target controller in parallel with existing setup
3. Migrate pilot applications and validate functionality
4. Document lessons learned and refine migration procedures

Phase 3: Production Migration (Weeks 5-8)

1. Create migration timeline prioritizing applications by criticality
2. Implement automated testing to validate each migration step
3. Execute migrations during maintenance windows with rollback procedures
4. Monitor application performance and user experience metrics

Phase 4: Cleanup (Weeks 9-10)

1. Remove old ingress controller after all applications are migrated
2. Update documentation and runbooks for new architecture
3. Conduct post-migration review to capture improvements for future migrations

Automation and Tooling

The NGINX Ingress Migration Tool provides automated assessment and conversion suggestions. For Gateway API migrations, consider tools like:

• Gateway API conformance tests to validate controller behavior
• Helm chart templating to generate both Ingress and Gateway API resources during transition
• GitOps automation to manage configuration drift between environments

Common Pitfalls and Solutions

Annotation Hell

Many teams discover they're using dozens of controller-specific annotations. The NGINX documentation recommends a "CRD-first" approach, migrating to policy-based configuration instead of annotation sprawl.

Load Balancer IP Changes

Cloud controller migrations often result in new load balancer IPs. Plan DNS TTL reductions and consider using CNAME records pointing to load balancer hostnames instead of A records with IPs.

Feature Gaps

Not every ingress-nginx feature has direct equivalents. Document these gaps early and plan workarounds or application changes. Sometimes the "missing" feature represents an opportunity to simplify your architecture.

Looking Forward

The ingress-nginx retirement forces a decision that many teams have been postponing. While disruptive in the short term, this migration presents an opportunity to modernize your Kubernetes networking stack with better security models, improved observability, and future-proof APIs.

Gateway API represents the future of Kubernetes networking, with growing ecosystem support and vendor adoption. Even if you choose an intermediate migration target like NGINX Ingress Controller or a cloud provider solution, plan for eventual Gateway API adoption as the standard matures.

The key to success is starting early, testing thoroughly, and migrating incrementally. The March 2026 deadline may seem distant, but complex production environments require months of planning and validation to ensure zero-downtime transitions.

Your future self will thank you for investing in this migration properly rather than rushing through it under deadline pressure.