Before You Migrate: Five Surprising Ingress-NGINX Behaviors You Need to Know

Summary

Kubernetes is retiring the Ingress-NGINX controller in March 2026, requiring a migration to alternative solutions such as the Gateway API. This transition is high-risk because Ingress-NGINX utilizes non-standard behaviors—including case-insensitive prefix regex matching and global annotation effects—that are not natively replicated by Gateway API implementations.

Key Points

• Ingress-NGINX is scheduled for retirement in March 2026.
• In Ingress-NGINX, regular expression matches are implemented as case-insensitive prefix matches rather than full-string matches.
• The nginx.ingress.kubernetes.io/use-regex: "true" annotation applies to all paths for a specific host across all Ingress resources sharing that host.
• The nginx.ingress.kubernetes.io/rewrite-target annotation implicitly enables the use-regex behavior for all paths associated with that host.
• Gateway API implementations, such as Istio, Envoy Gateway, and Kgateway, typically perform full, case-sensitive regular expression matching.

Technical Details

In Ingress-NGINX, the nginx.ingress.kubernetes.io/use-regex annotation triggers a side effect where all paths for a specific host are treated as regular expressions across all Ingress resources for that host. This means that even if an Ingress resource uses pathType: Exact, it may be interpreted as a case-insensitive prefix match if another Ingress resource for the same host has the regex annotation enabled. Similarly, applying nginx.ingress.kubernetes.io/rewrite-target silently activates the use-regex functionality, causing all paths for that host to behave as case-insensitive prefix patterns.

When migrating to the Gateway API, these behaviors must be explicitly reconstructed. Because Envoy-based Gateway API implementations use strict, case-sensitive matching, a direct translation of a regex pattern like /[A-Z]{3} will fail to match paths like /uuid. To preserve the original Ingress-NGINX logic, developers must use the RegularExpression match type with explicit character classes (e.g., /[a-zA-Z]{3}.*) or utilize the (?i) flag (e.g., (?i)/[a-z]{3}.*) to re-enable case-insensitivity and prefix matching.

Impact / Why It Matters

Improperly translated routing rules during the migration from Ingress-NGINX to Gateway API can cause significant production outages, specifically 404 Not Found errors, due to the shift from implicit prefix matching to strict exact matching. Developers must audit all existing Ingress annotations to ensure that regex and rewrite behaviors are explicitly defined in the new HTTPRoute configurations.