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 (
networking.k8s.io/v1). You might be wondering – so what?
That “so what” is nuanced and we’ll answer it by answering three interrelated questions:
- Why are Kubernetes releases a big deal?
- What is the Ingress API and why does the upgrade to
- How does NGINX Ingress Controller 2.0 impact current customers?
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:
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).
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.
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
The Ingress API makes it possible for an Ingress controller to safely expose your Kubernetes apps. The
networking.k8s.io/v1 API (a.k.a. Ingress API v1) was introduced with Kubernetes 1.19. At that time, Kubernetes supported both
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 (
networking.k8s.io/v1beta1) 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.
Upgrade to NGINX Ingress Controller 2.0.
If you haven’t yet migrated your Ingress‑related resources to
networking.k8s.io/v1(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
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
kubernetes.io/ingress.classannotation in your Ingress resources, we recommend switching to the
Use our documentation and examples (available with
ingressClassNamefield of the Ingress resource) to plan your updates.
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.
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.
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:
- May (v1.2.0) – The project adopts the new NGINX Plus API and the nginx-ingress images move to the official NGINX Docker Hub. This version debuts support for gRPC, passive health checks, Helm charts, and Prometheus.
- August (v1.3.0) – NGINX Plus customers can now export metrics to Prometheus and take advantage of active health checks, and everyone benefits from improvements to Helm charts, mergeable Ingress resources, and easier management of custom templates (see Announcing NGINX Ingress Controller for Kubernetes Release 1.3.0).
- November (v1.4.0) – Support for TCP/UDP is added, making Layer 4 traffic management possible. Other features include easier development of custom annotations and support for the Random with Two Choices load‑balancing algorithm (see Announcing NGINX Ingress Controller for Kubernetes Release 1.4.0).
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.
- May (v1.5.0) – VirtualServer and VirtualServerRoute (VS/VSR) resources are introduced as a new configuration approach. VS/VSR are the first NGINX Ingress resources, providing a native, type‑safe, and indented configuration style which simplifies implementation of Ingress load balancing (see Announcing NGINX Ingress Controller for Kubernetes Release 1.5.0).
- December (v1.6.0) – Documentation is established on docs.nginx.com. VS/VSR resources add richer load balancing support and reach production‑readiness. OpenTracing support is added for better monitoring and debugging use cases, and the ability to run as a non‑
rootuser is added to improve security (see Announcing NGINX Ingress Controller for Kubernetes Release 1.6.0).
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.
- April (v1.7.0) – We release the NGINX Ingress Operator to provide a fast, easy, and certified way to deploy NGINX Ingress Controller in OpenShift 4.x environments. NGINX Ingress resources continue to grow with support for additional protocols, circuit breakers, and improved validation and reporting (see Announcing NGINX Ingress Controller for Kubernetes Release 1.7.0).
- July (v1.8.0) – Integration with F5 NGINX App Protect WAF allows customers to deploy a lightweight, flexible WAF in the same container as the Ingress controller. Customization of NGINX Ingress resources via snippets or custom templates is added, and features including URI rewrites and access control lists provide more granular control (see Announcing NGINX Ingress Controller for Kubernetes Release 1.8.0).
- October (v1.9.0) – Integration with F5 NGINX Service Mesh makes it possible to manage north‑south and east‑west traffic in the same configuration. Grafana dashboards are added for easy visualization of historic data (see Announcing NGINX Ingress Controller Release 1.9.0).
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.
- February (v1.10.0) – OpenID Connect (OIDC) authentication is the major addition, making it easy to use JWT authentication to provide a robust single sign‑on (SSO) option (see Easy and Robust Single Sign‑On with OpenID Connect and NGINX Ingress Controller).
- March (v1.11.0) – Major enhancements to the WAF and load‑balancing policies provide additional power and flexibility, including health checks and status reporting (see Enhanced TCP/UDP Load Balancing and WAF Configuration with NGINX Ingress Controller).
- July (v1.12.0) – The highlights for this release are all about ease of deployment. In addition to purchase via the AWS Container Marketplace, we make it possible to pull prebuilt images from the F5 Container Registry (see NGINX Is Available in AWS Marketplace for Containers).
- October (v2.0.3) – Though not a major milestone in terms of capabilities, this release represents a milestone for interoperation with the Kubernetes API and the evolution of the Ingress object. This change means NGINX Ingress Controller 2.0 (and later) is compatible with Kubernetes 1.19 and later. NGINX Ingress Controller 2.0 is also the only version you can deploy with Kubernetes 1.22 and later.
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.