As Kubernetes prepares to retire Ingress-NGINX in March 2026, many teams are planning their migration. However, this widely-used Ingress controller has several surprising default behaviors that can cause unexpected outages if not accounted for. This Q&A explores key quirks, focusing on regex matching quirks, comparison with Gateway API, and essential migration tips. Whether you're moving to Gateway API or another controller, understanding these behaviors helps ensure a smooth transition.
Why is Ingress-NGINX being retired and what does it mean for my cluster?
Kubernetes announced in November 2025 that Ingress-NGINX will be retired in March 2026. This means the community will stop maintaining and supporting this Ingress controller. While your existing clusters will continue to run, you will no longer receive security patches, bug fixes, or updates. Migrating to an alternative like Gateway API or another Ingress controller is strongly recommended to avoid running unsupported software. The retirement does not affect NGINX Ingress by F5, which is a separate product. Plan your migration now to ensure continued compliance and security.
What is the difference between Ingress-NGINX and NGINX Ingress?
Despite similar names, Ingress-NGINX and NGINX Ingress are distinct controllers. Ingress-NGINX is maintained by the Kubernetes community and is the one being retired. NGINX Ingress is a commercial product by F5. Both use NGINX as their data plane, but their codebases, configurations, and support are unrelated. Confusing them can lead to migration mistakes. Always verify which controller your cluster uses by checking the IngressClass resource or the controller pod's image name. This distinction is critical when evaluating replacement options.
How does regex path matching work in Ingress-NGINX?
Ingress-NGINX regex matches are prefix-based and case-insensitive. For example, if you define a pattern /[A-Z]{3} with the annotation nginx.ingress.kubernetes.io/use-regex: "true", the controller will match any path that starts with three letters (case insensitive), such as /ABC, /abc, or even /abcd. This is likely unintended if you require an exact match. The pathType must be ImplementationSpecific to enable regex. This behavior often surprises users migrating from other systems where regex implies full match. Always test your patterns with real requests to catch unexpected routing.
What are the risks of Ingress-NGINX regex quirks during migration?
The main risk is unexpected routing that causes outages. Suppose your regex is meant to match only /ABC but it inadvertently matches /ABCDEF or /abc. If clients or internal services send requests to paths like /uuid (as in the httpbin example), they may be incorrectly routed to a different backend. This can lead to data exposure, incorrect responses, or service disruption. During migration, a seemingly correct translation to Gateway API may fail because Gateway API typically performs full, case-sensitive regex matches. Without accounting for Ingress-NGINX's prefix and case-insensitive behavior, your new rules may break existing traffic patterns.
How does Gateway API handle regular expression path matching?
Gateway API uses a RegularExpression match type for HTTP path matching. Unlike Ingress-NGINX, this is implementation-specific. Popular Envoy-based Gateways like Istio, Envoy Gateway, and Kgateway perform a full, case-sensitive match by default. This means a pattern /[A-Z]{3} will only match exactly three uppercase letters at the start of the path, not longer paths or lowercase. When migrating, you must adjust your regex patterns to be explicit about prefix if needed (e.g., by adding .* for remaining path). Always consult your Gateway implementation's documentation to confirm matching semantics.
What is the recurring risk pattern when migrating away from Ingress-NGINX?
The recurring pattern is that a seemingly correct translation of Ingress rules into Gateway API can still cause outages if it ignores Ingress-NGINX's unique behavior. Each quirk—whether regex, annotation handling, or default settings—needs to be consciously evaluated. The solution is to systematically test every rule in isolation, using tools like curl against a staging environment. Document which Ingress-NGINX behaviors your applications depend on, then recreate them in the new controller using its own features (e.g., dedicated filters or rewrite rules). This mindful migration avoids hidden failures.
Can I preserve Ingress-NGINX behavior in Gateway API?
Yes, but it requires deliberate configuration. For regex, you can emulate prefix-based matching by appending .* to your pattern and ensuring case-insensitivity if supported by your Gateway implementation. Some Gateways offer custom filters or Envoy extensions to modify match behavior. However, the best practice is to rethink your routing logic rather than blindly copying quirks. Ingress-NGINX's default behaviors were often side effects, not design choices. By migrating, you have an opportunity to simplify your routing rules. Start by listing the actual requirements (e.g., "route paths starting with /abc") and write clean rules accordingly.