We are happy to announce release 1.6.0 of the NGINX Ingress Controller for Kubernetes. This release builds upon the development of our supported solution for Ingress load balancing on Kubernetes platforms, including Amazon Elastic Container Service for Kubernetes (EKS), the Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), Red Hat OpenShift, IBM Cloud Private, Diamanti, and others.
In release 1.6.0, NGINX Ingress resources – a configuration approach introduced earlier this year as “custom resources” – are now enabled by default and ready for production use.
NGINX Ingress resources are an alternative to the standard Kubernetes Ingress resource. They provide a richer and safer way to define complex ingress rules, and they support additional use cases. You can use NGINX Ingress resources at the same time as standard Kubernetes Ingress resources, which gives you the freedom to define each service using the most appropriate approach.
Release 1.6.0 also includes:
- Improvements to NGINX Ingress resources, adding support for richer load‑balancing behavior, more sophisticated request routing, redirects, direct responses, and blue‑green and circuit breaker patterns
- Support for OpenTracing, helping you to monitor and debug complex transactions
- An improved security posture, with support to run the Ingress Controller as a non‑
With this release, we are also pleased to make the documentation available at a new site, docs.nginx.com/nginx-ingress-controller.
The documentation includes the complete changelog, detailing bug fixes, improvements, and changes.
What Is the NGINX Ingress Controller for Kubernetes?
The NGINX Ingress Controller for Kubernetes is a daemon that runs alongside either NGINX Open Source or NGINX Plus instances within a Kubernetes environment. This daemon monitors both standard Kubernetes Ingress resources and NGINX Ingress resources to discover requests for services that require ingress load balancing. It then automatically configures NGINX or NGINX Plus to route and load balance traffic to these services.
Multiple NGINX Ingress controller implementations are available. The official NGINX implementation is high‑performance, production‑ready, and suitable for long‑term deployment. We focus on providing stability across releases, with features that can be deployed at enterprise scale. We provide full technical support to NGINX Plus subscribers at no additional cost, and NGINX Open Source users benefit from our focus on stability and supportability.
Introducing NGINX Ingress Resources
In release 1.5.0, we previewed a new approach to configuration of request routing and load balancing, called “custom resources”. In release 1.6.0, these resources, now called NGINX Ingress resources, are enabled by default and suitable for production use.
We took advantage of how the Kubernetes API can be extended using custom resources and created a set of alternative resources with the following goals:
- To support a wider range of real use cases. NGINX provides rich functionality, including load balancing, advanced request routing, split‑clients routing, and direct responses. With NGINX Ingress resources, we make it easy for application teams to access these features when defining how to route traffic to their services.
- To reduce complexity by eliminating the dependency on annotations for advanced features and fine‑tuning. Annotations are a general‑purpose extension mechanism for all Kubernetes resources, but they are not suited for expressing complex configuration rules and they lack type safety. With NGINX Ingress resources, all features and tuning options are part of the formal specification.
- To provide a familiar, Kubernetes‑native user experience. NGINX Ingress resources follow the Kubernetes API style, making them easy to work with and to automate.
- To support RBAC and self‑service use cases in a scalable and predictable manner. An administrator or superuser can delegate part of the NGINX Ingress Resource configuration to other teams (in their namespaces), enabling those teams to take responsibility for their own applications and services, safely and securely.
Improvements to NGINX Ingress Resources
At the core of the NGINX Ingress resources is the VirtualServer resource. It is used to define:
- The host‑level parameters used to publish one or more Kubernetes Services for external access, such as the
Hostheader and TLS parameters
- The upstreams (Kubernetes Services) that implement the externally accessible services
- The routes that match requests and assign them to the upstreams
The NGINX Ingress Controller can manage multiple VirtualServer resources at the same time. When it receives a request, it uses the host‑level parameters to determine which VirtualServer resource handles that request.
The NGINX Ingress Controller then processes the routes in the resource to determine the action for the request. Commonly, the action selects an upstream, and the NGINX Ingress Controller load balances the request across the Kubernetes Pods in that upstream.
For RBAC purposes, a route and upstream may be delegated to a separate VirtualServerRoute resource, located in a different Kubernetes namespace. This grants fine‑grained control of upstream definitions and routing rules to other application teams in a safe and secure manner.
Routing rules are contained in a Route configuration, which contains a list of path matches and the corresponding rules for handling requests that match the path.
Patch matches can use either prefix matches or regular expressions (new in release 1.6.0).
The routing rules that select how a request is handled are particularly rich. Prior to release 1.6.0, the rule simply defined which upstream handled the request.
Release 1.6.0 adds the following enhancements:
- Action – The rule may immediately select a single action that defines several ways to handle the request. See Action Configuration below.
- Enhanced conditional matches – The Match configuration defines a set of complex matches, based on headers, cookies, query string parameters and NGINX variables, used to select the appropriate action. With release 1.6.0, it is now possible to define several independent sets of matches, where the first set that matches successfully “wins” and selects an action.
- Improved traffic splitting – The Split configuration selects one of several different actions at random, with user‑defined weights. This makes it possible to configure canary releases and to automate blue‑green deployments.
In release 1.6.0, a conditional match can select a Split configuration, making it possible to create complex rules such as:
- For test traffic identified with a ‘debug’ cookie, always forward traffic to upstream-v3
- For all other production traffic, perform a canary test, routing 1% of traffic to upstream-v2 and the remainder to upstream-v1
Each routing rule ultimately selects an Action configuration. This is a terminal operation that defines how to handle the request.
Prior to release 1.6.0, the only supported action was to select an upstream group (defined in an Upstream configuration) and load balance the request to the service instances in that group:
- Pass – Handle the request using the named upstream group. The NGINX Ingress Controller uses the parameters in the Upstream configuration to determine how to load balance the request and handle any errors from the selected service instance.
Two additional actions are new in release 1.6.0:
- Redirect – Issue a user‑defined redirect, telling the client to request a different URL. The URL can be either fixed or constructed dynamically using parameters from the request.
- Respond – Send a response directly to the client. The response can be either a fixed, static value or constructed dynamically using parameters from the request.
The Upstream configuration defines one or more upstream groups, each identified by a name. An upstream group references the Kubernetes Service. When an upstream group is selected by the routing rules and actions, the NGINX Ingress Controller load balances the request across the Pods that are members of that Service.
In release 1.6.0, you can use labels to select a subset of the Pods of a Service. Additionally, for NGINX Plus you can use a Service of type ExternalName.
Release 1.6.0 also provides much richer control over how NGINX forwards and load balances requests. You gain more control over load balancing, keepalive and timeout settings, request retries, buffering and performance tuning, as well as support for WebSocket and NGINX Plus’ slow‑start capability. When using the Ingress Controller with NGINX Plus, you can also configure request queuing, upstream health checks, and session persistence.
Release 1.6.0 brings a number of additional improvements to stability, performance, and security, detailed in the Release Notes.
Of particular note is the change to enable running the NGINX Ingress Controller container as a non‑
Running containers as non‑
root users is a best practice. Prior to release 1.6.0, the NGINX Ingress Controller daemon and the NGINX master processes ran as
root, while the NGINX worker processes used the unprivileged user
nginx. In release 1.6.0, all processes inside the NGINX Ingress Controller container run as the
nginx user. The
securityContext field in the Pod template in the installation manifests has been updated to add the
NET_BIND_SERVICE capability, so that the NGINX master process can continue to bind to privileged ports (80 and 443).
Finally, the NGINX Ingress Controller documentation has been moved from GitHub to a new location on docs.nginx.com. Improving the documentation is a work in progress, and we’d welcome any feedback through the GitHub project page.