NGINX Ingress Controller Version 2.0: What You Need to Know

Brian Ehlert Thumbnail
Brian Ehlert
Published December 27, 2021

In October, we launched F5 NGINX Ingress Controller version 2.0 (nginxinc/kubernetes-ingress), adding support for Kubernetes 1.22 and version 1 of the Ingress API ( You might be wondering – so what?

That “so what” is nuanced and we’ll answer it by answering three interrelated questions:

Read on for the answers and tune in for Your Battle Plan for When Kubernetes Versions Attack on January 11, 2022.

Why Are Kubernetes Releases a Big Deal?

The answer to this question is simple yet complicated. Compatibility management for Kubernetes is challenging because Kubernetes operators have to manage three categories of versioning:

  1. The Kubernetes platform itself – At each new release, the Kubernetes team stops maintaining an older version. Continuing to use such a version is problematic for your risk management strategy and makes troubleshooting harder because help from the Kubernetes team is no longer available. At present, the Kubernetes project maintains release branches for the most recent three minor releases (1.20, 1.21, and 1.22). Kubernetes 1.19 and later receive approximately 1 year of patch support, while 1.18 and earlier received approximately 9 months of patch support. (The shorter timespan for 1.18 and earlier is because Kubernetes used to release four times per year, rather than the current three).

  2. The Kubernetes APIs – New APIs are born and obsolete ones deprecated at each Kubernetes release, and the changes to APIs impact corresponding resources and tools. When you upgrade your Kubernetes platform, you may have to upgrade APIs as well.

  3. The tools you’ve deployed in Kubernetes – A major change to Kubernetes or its APIs can affect whether your tools – such as an Ingress controller – and corresponding resources continue to function properly.

So you need to track three timelines – one for Kubernetes, one for the Ingress API, and one for NGINX Ingress Controller. To avoid breaking Kubernetes, you have to find the sweet spot where the Kubernetes version is compatible with the APIs and NGINX Ingress Controller. Upgrading any one of the three components without checking for compatibility can have drastic consequences. If all three components aren’t compatible with each other … congratulations, you’ve broken your apps!

What Is the Ingress API and Why Does Matter?

The Ingress API makes it possible for an Ingress controller to safely expose your Kubernetes apps. The API (a.k.a. Ingress API v1) was introduced with Kubernetes 1.19. At that time, Kubernetes supported both v1beta1 and v1 – and automatically presented one version as the other. This “under the covers” compatibility of API versions benefits you operationally but can hinder your planning efforts.

With the release of Kubernetes 1.22, v1 became the only version of the Ingress API. This is significant because as Ingress API v1 becomes “the one”, all beta versions (extensions/v1beta1 and become deprecated. While that’s disruptive for organizations that haven’t yet adopted Ingress API v1, at NGINX we see this change as a good sign. The promotion of the Ingress API out of beta signals graduation to a mature and fully realized API. Now, why does this change matter? Well, that relates back to version management. Let’s say you upgrade an existing cluster to Kubernetes 1.22, but keep using v1beta1 Ingress‑related resources … congratulations, you’ve broken your Ingress resources!

How Does NGINX Ingress Controller 2.0 Affect Current Customers?

Because NGINX Ingress Controller is tightly coupled to the Ingress API, the release of v1 significantly impacted us as a product – and also you as our customers – which is why we have jumped the NGINX Ingress Controller version number from 1.x to 2.x. We rearchitected NGINX Ingress Controller 2.0 to leverage Ingress API v1, making it fully compatible with Kubernetes 1.22.

If you use NGINX Ingress Controller, you need to take some version‑dependent actions immediately to avoid breaking Kubernetes, your Ingress resources, or NGINX Ingress Controller:

  • Kubernetes 1.18 and earlier:

    • Ensure you’re using NGINX Ingress Controller 1.12 so you can take advantage of the fullest feature set available. (When you upgrade to NGINX Ingress Controller 2.0, you’ll also need to upgrade to Kubernetes 1.19 or later.)

    • Make a plan for migrating to a newer version of Kubernetes (and NGINX Ingress Controller) within the coming months, as Kubernetes 1.18 won’t be supported after the next Kubernetes release.

  • Kubernetes 1.19–1.21:

    • Upgrade to NGINX Ingress Controller 2.0.

    • If you haven’t yet migrated your Ingress‑related resources to (see the NGINX Ingress Controller 2.0 release notes), create your plan now. Kubernetes 1.19–1.21 supports all current versions of the Ingress API (both the v1beta1s and v1), giving you the opportunity to convert in place.

    • If you haven’t already done so, immediately move your Ingress and IngressClass resources to

      • If you are using the deprecated annotation in your Ingress resources, we recommend switching to the ingressClassName field.

      • Use our documentation and examples (available with and the ingressClassName field of the Ingress resource) to plan your updates.

  • Kubernetes 1.22:

    • Ensure you are already running NGINX Ingress Controller 2.0, as previous versions of NGINX Ingress Controller are not compatible with Kubernetes 1.22 and don’t support Ingress API v1.

A (Not So) Brief History of the NGINX Ingress Controller

Since its first release in 2016, NGINX Ingress Controller has grown from a nascent tool to a powerhouse for Kubernetes networking. Here’s a look at its evolution from launch to present.

2016 (v0.5.0)

NGINX engineer Michael Pleshakov publishes the first entry in our GitHub repo (nginxinc/kubernetes-ingress), making it possible to use NGINX and F5 NGINX Plus as a Kubernetes Ingress controller (KIC).

NGINX Ingress Controller makes its first public appearance, at KubeCon EU 2016. Check out the recording: Day 1, Creating an Advanced Load Balancing Solution for Kubernetes with NGINX; KubeCon EU 2016.

2017 (v1.0.0)

The project achieves production‑readiness, including key support for JSON Web Tokens (JWTs) in the NGINX Plus-based version.

At NGINX Conf 2017, Michael Pleshakov demonstrates production capabilities including advanced load balancing in Using NGINX Plus as an Ingress Controller for Load Balancing Applications on Kubernetes.


NGINX Ingress Controller sees big enhancements in the areas of visibility, ease of use, and flexibility:

At NGINX Conf 2018, Michael Pleshakov takes the stage for Using NGINX as a Kubernetes Ingress Controller, where he shares how to deploy NGINX Ingress Controller with Helm, configure HTTP and TCP/UDP load balancing, monitor with Prometheus, and troubleshoot.


We debut our alternative to standard Kubernetes Ingress resources, making it easier and more reliable to execute advanced capabilities.

In The Next Generation of NGINX Ingress Controller, Michael Pleshakov returns to NGINX Conf 2019 to demonstrate VS/VSR for use cases including blue‑green deployments and A/B testing.


In addition to numerous enhancements to NGINX Ingress resources, the main theme this year is integration with ecosystem tools and NGINX products.

In Secure Production Apps with NGINX and OpenShift, Technical Marketing Engineer Amir Rawdat demonstrates how to use the NGINX Ingress Operator, leverage roleૹbased access control (RBAC) for cross‑functional provisioning, secure containerized apps with NGINX App Protect, and validate clients with JWTs.


Security is a main theme, along with more ecosystem integrations.

In his NGINX Sprint 2.0 session, Master Microservices with End-to-End Encryption, Software Engineer Aidan Carson demonstrates how to secure the edge with NGINX Ingress Controller, set up secure access control between services with NGINX Service Mesh, and use both products to secure egress traffic with mTLS.

Next Step: Try NGINX Ingress Controller

If you’ve decided that an open source Ingress controller is the right choice for your apps, then you can get started quickly with the NGINX Open Source‑based NGINX Ingress Controller at our GitHub repo.

For large production deployments, we hope you’ll try our commercial NGINX Ingress Controller based on NGINX Plus. It’s available for a free 30-day trial that includes NGINX App Protect.

"This blog post may reference products that are no longer available and/or no longer supported. For the most current information about available F5 NGINX products and solutions, explore our NGINX product family. NGINX is now part of F5. All previous links will redirect to similar NGINX content on"