NGINX Ingress Migration Tool

Overview

This interactive guide helps you migrate from the community-maintained Ingress-NGINX controller (kubernetes/ingress-nginx) to NGINX Ingress Controller (nginx/kubernetes-ingress). It covers 130+ annotation mappings, ConfigMap key translations, and CRD migration examples across three pages, listed in the sidebar:

• Getting started: background on why to migrate, CRD overviews, installation, and a migration checklist
• Ingress-NGINX config analyzer: paste an Ingress manifest and get automatic migration suggestions with ready-to-use YAML
• Reference guide: complete annotation and ConfigMap mapping tables with side-by-side examples

Why migrate?

The two controllers take fundamentally different approaches to configuring NGINX in Kubernetes.

• Ingress-NGINX is annotation-driven: it relies on annotations and ConfigMap keys to customize NGINX. These are opaque strings with no schema validation, so a single Ingress resource may carry dozens of annotations as unstructured key-value pairs.
• NGINX Ingress Controller is CRD-native: it uses Custom Resource Definitions (VirtualServer, Policy, TransportServer) as its primary config model, providing structured, schema-validated YAML with IDE autocompletion.

While NGINX Ingress Controller still supports annotations for common settings, CRDs unlock capabilities that annotations cannot express:

• Schema validation: Kubernetes validates CRD fields at apply time, catching misconfigurations before they reach NGINX
• Structured configuration: nested YAML objects replace long annotation strings, making complex routing, traffic splitting, and security policies readable and maintainable
• Reusability: Policies (rate limiting, auth, WAF) are defined once and attached to any number of routes
• Layer 4 support: TransportServer CRDs handle TCP/UDP workloads that annotations cannot express
• IDE and tooling support: CRD schemas enable autocompletion, linting, and documentation in editors and CI pipelines

Phased migration strategy

Rather than performing a "big bang" cutover, F5 recommends a phased migration that allows you to validate each workload before decommissioning the community controller. Both controllers can run side-by-side in the same cluster using separate IngressClass resources.

1. Deploy side-by-side: install NGINX Ingress Controller alongside the community controller using a distinct IngressClass such as nginx-nic (see Install alongside the community controller). Existing traffic is unaffected.
2. Migrate service-by-service: update each Ingress resource's ingressClassName to point to the new controller. Convert annotations as described in the reference guide, validate routing and TLS behavior, and promote to production before moving on to the next service.
3. Decommission: after all workloads have been migrated and validated, remove the community controller deployment, its IngressClass, and any unused ConfigMaps.

Install alongside the community controller

Both Helm charts name their class nginx by default, and an IngressClass name can belong to only one controller. Give NGINX Ingress Controller its own class:

helm install nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress \
  --set controller.ingressClass.name=nginx-nic \
  --set controller.config.name=nginx-config \
  --set controller.enableSnippets=true \
  --set controller.enableTLSPassthrough=true

Keep only the flags your Ingresses need:

• controller.config.name: the examples on this page write the ConfigMap nginx-config, the name the manifests install. The chart names it after the release instead (nginx-ingress for this command) unless this is set, and NGINX Ingress Controller reads only the ConfigMap its -nginx-configmaps flag names, so keys written to any other one are silently unused.
• controller.enableSnippets: off by default. With it off, NGINX Ingress Controller rejects any resource that carries a snippet, so configuration-snippet, server-snippet and every mapping that becomes a snippet fail. Snippets are copied as written: directives from modules the community image included, such as more_set_headers (headers-more) and Lua, do not exist in NGINX Ingress Controller and fail the configuration reload.
• controller.enableTLSPassthrough: off by default. ssl-passthrough becomes a TransportServer on the built-in tls-passthrough listener, which exists only with this flag.
• controller.enableCertManager: off by default. cert-manager HTTP-01 challenges for a VirtualServer's host pass its HTTPS redirect and authentication only with this flag (v5.7.0 and later); on an Ingress they do without it. The community controller exempted /.well-known/acme-challenge by default.
• controller.enableTopologyAwareRouting: off by default, like the community controller's --enable-topology-aware-routing, and new in v5.7.0. With it on, each controller pod sends traffic to the endpoints in its own zone, or on its own node, when the Service sets spec.trafficDistribution (or the older service.kubernetes.io/topology-mode: auto), falling back to every ready endpoint otherwise.

Defaults that change

A setting you never configured still changes if the two controllers default it differently. Set the NGINX Ingress Controller value in the nginx-config ConfigMap, or per resource, wherever the old default matters to you.

Gateway API

The community project recommends that new users adopt a Gateway API implementation. NGINX Gateway Fabric is the NGINX implementation of the Gateway API, and ingress2gateway converts Ingress resources to it (--providers=ingress-nginx for community annotations). This tool covers the move to NGINX Ingress Controller, which keeps the Ingress API.

CRDs summary

NGINX Ingress Controller uses Custom Resource Definitions (CRDs) to extend Kubernetes with NGINX-specific configuration. CRDs provide type-safe, validated configuration that goes beyond what standard Ingress annotations can offer.

Installing CRDs

CRDs can be installed via Helm or manually using manifests, depending on your deployment method. See the NGINX Ingress Controller installation docs for full instructions.

helm install nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 2.8.0 --set controller.enableCustomResources=true

kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v5.7.0/deploy/crds.yaml

Migration checklist

• Install CRDs via Helm (controller.enableCustomResources=true) or manifests (deploy/crds.yaml)
• Install with its own IngressClass (controller.ingressClass.name=nginx-nic), and turn on controller.enableSnippets or controller.enableTLSPassthrough if your Ingresses need them
• Review the defaults that change (response buffering, HTTP/2, HSTS, keepalive, timeouts, load balancing) and set the ones that matter in nginx-config
• Review annotation mappings: not all nginx.ingress.kubernetes.io/ annotations have a direct nginx.org/ equivalent (see NGINX mappings)
• Map rewrite-target annotation to nginx.org/rewrite-target (not nginx.org/rewrites)
• Migrate ConfigMap keys that differ between controllers (see ConfigMap mappings)
• Convert HSTS ConfigMap keys to nginx.org/hsts annotations for per-Ingress control, or an hsts Policy on a VirtualServer (v5.6.0+)
• Convert server-tokens ConfigMap key to nginx.org/server-tokens annotation
• Convert access control annotations to Policy CRD (accessControl)
• Convert authentication annotations to Policy CRD (apiKey, basicAuth, externalAuth, jwt, oidc, oidcNative)
• Convert canary/traffic splitting to VirtualServer splits/matches
• Convert mTLS annotations to ingressMTLS/egressMTLS policies
• Convert CORS annotations to the cors Policy CRD via nginx.org/policies (v5.4.0+), falling back to snippets only where needed
• Convert custom error pages to nginx.org/custom-http-errors with a spec.defaultBackend (v5.6.0+), or VirtualServer errorPages
• Convert header manipulation to VirtualServer requestHeaders/responseHeaders
• Convert rate limiting annotations to Policy CRD (rateLimit)
• Convert redirect annotations to VirtualServer action.redirect
• Convert session affinity annotations to VirtualServer upstream sessionCookie
• Convert SSL passthrough to TransportServer CRD
• Convert TCP/UDP services to TransportServer CRD
• Replace ssl-redirect with nginx.org/ssl-redirect (not the deprecated ingress.kubernetes.io/ssl-redirect)
• Verify snippets (configuration-snippet, server-snippet) use only directives NGINX Ingress Controller ships, with no more_set_headers or Lua
• Test in staging environment
• Update monitoring and alerting

Command line tool

The analyzer on this page works on what you paste. nic-migrate runs the same engine from a terminal, across every Ingress in a directory or read straight from a running cluster. It loads the mapping database out of this site's own source rather than keeping a second copy, so it cannot drift from the tables in the reference guide. It is not distributed as a download; clone the repository for this site and run it with Node 18 or newer, with nothing to install.

node tools/nic-migrate/nic-migrate.js report -f ./manifests

node tools/nic-migrate/nic-migrate.js convert -f ./manifests --validate

Neither command drops anything silently: where a construct has no equivalent on the target you choose, it is named rather than omitted. Read the notes each run prints, keep --validate on so the output is checked against a live cluster with kubectl apply --dry-run=server, and see the full option reference and known limitations.

Additional resources

• NGINX Ingress Controller documentation
• VirtualServer Reference
• Policy reference
• TransportServer Reference
• GitHub repository
• Contribute to This Tool