nginx/kubernetes-ingress: the NGINX-maintained Ingress Controller for Kubernetes

What nginx/kubernetes-ingress actually does

A Kubernetes Ingress resource is only a declaration. Something has to watch it and rewrite a real load balancer's configuration. This repository is that something for NGINX.

Out of the box it handles what the standard Ingress resource supports: host-based routing, path-based routing and TLS termination per hostname. Beyond that it exposes NGINX and NGINX Plus features through annotations on Ingress resources and through a ConfigMap. The README points at two documentation pages for that surface, one for the ConfigMap resource and one for advanced configuration with annotations.

It also goes past HTTP. The README says it routes HTTP, HTTPS, TCP, UDP and gRPC traffic to your services. The audience is platform teams that already understand NGINX and do not want to relearn routing semantics in a different proxy. If you have never written an nginx.conf and have no intention of starting, the annotation surface will feel like a second configuration language layered on top of Kubernetes.

VirtualServer, VirtualServerRoute and TransportServer as the escape hatch from Ingress

The Ingress resource has a ceiling. The project's answer is two custom resources, VirtualServer and VirtualServerRoute, which the README lists for traffic splitting, A/B testing and canary deployments.

For non-HTTP traffic there is a third resource, TransportServer, documented for TCP and UDP load balancing. That is a meaningful architectural split: three resource types, three configuration paths, one controller process watching all of them. The cost is that a team moving from another controller has to decide per route which resource type to use, and custom resources mean CRDs installed in the cluster before anything referencing them will apply.

The design choice here is defensible but not free. Annotations on Ingress keep you inside a portable Kubernetes API at the price of string-typed configuration. VirtualServer gives you a typed schema at the price of a resource that only this controller understands. Pick per workload, not per cluster.

Installing NGINX Ingress Controller and routing a first request

The README's Quick Start gives two installation routes, Helm (recommended) or the Kubernetes manifests, with the commands inline and a full installation guide on docs.nginx.com. It recommends the latest stable release, 5.7.0, for production use.

The repository ships a charts/ directory and a deploy/ directory, consistent with those two paths. The README links the Helm chart at charts/nginx-ingress and gives the install command `helm install <RELEASE_NAME> oci://ghcr.io/nginx/charts/nginx-ingress --version 2.8.0`.

After the release settles, the controller pod should be running in the namespace you installed into, and the chart's Service should have an external address on a cluster that can provision one. The next step is a workload to route to. The README points at the Cafe example under examples/ingress-resources/complete-example.

Once an Ingress exists that selects your Service, requests to the host you declared should reach the backend. If they do not, the first thing to check is whether the controller is watching the Ingress class you set. Treat the class field as something to confirm rather than assume.

Where this controller is the wrong choice

The README carries a note for users coming from the community-supported kubernetes/ingress-nginx controller, pointing them to the NGINX Kubernetes Hub for details on how to migrate. Two projects, both called some variant of NGINX Ingress Controller, and moving between them is treated as a migration, so do not assume configuration written for the other one carries over.

The second limitation is the NGINX Plus split. Several features are Plus-only, and the README links to a separate page about NGINX Ingress Controller with NGINX Plus. The Makefile confirms the build is parameterised between NGINX OSS and NGINX Plus, with NGINX_OSS_VERSION and NGINX_PLUS_VERSION as separate variables and separate package repositories. If you read a feature in the docs and cannot find it in your OSS deployment, that is usually why.

The third is operational weight. You are running NGINX, not a purpose-built Go proxy. That is the point, but it means your debugging surface includes nginx.conf as generated by the controller, and the controller's own logs. Teams that want a single log stream and no proxy config to reason about will find this heavier than they want.

How it differs from the Kubernetes community ingress-nginx controller

The obvious alternative is kubernetes/ingress-nginx, the community controller the README explicitly distinguishes this project from. The difference is not feature parity, it is governance and configuration model.

The community controller is a Kubernetes project. This one is built and released by the people behind NGINX, ships an LTS release line (2026-lts-r9 sits alongside v5.7.0 in the recent releases), and offers commercial support, which the README lists as available for NGINX Plus users. That LTS line is the concrete difference for an operations team: a version you can pin for a long window rather than tracking minor releases.

The configuration model differs too. This project adds VirtualServer, VirtualServerRoute and TransportServer as first-class resources. A controller that only speaks Ingress cannot express traffic splitting without annotation gymnastics or a service mesh. If your routing needs stop at host and path, the extra resource types are unused surface area; if they do not, they are the reason to pick this one.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived and the last push was on 2026-11-01. Releases are frequent: v5.7.0 and 2026-lts-r9 both landed on 2026-10-14, after v5.6.3 on 2026-09-16.

The licence is Apache-2.0, which covers the controller code in this repository. It does not cover NGINX Plus, which is a commercial product sold separately, nor the NGINX App Protect modules referenced in the Makefile variables. Running the OSS build is an Apache-2.0 exercise; running the Plus build brings a subscription into the picture. That is a distinction worth confirming with whoever holds the budget, not something to infer from the repository licence file.

Upgrade cost is dominated by the annotation and ConfigMap surface, which is versioned alongside the controller rather than being a stable Kubernetes API. The repository's test markers in pyproject.toml list a long tail of feature areas (appprotect, policies, oidc, rewrite, upgrade among them), which tells you how much behaviour is covered by the project's own test suite and, by extension, how much can shift between releases. The 2026-lts line exists precisely so you do not have to absorb that drift continuously.

Editorial conclusion

Adopt it if you already run NGINX or NGINX Plus, need TCP or UDP load balancing, or want VirtualServer traffic splitting that plain Ingress cannot express. Do not adopt it if you have standardised on Gateway API or want a controller with no vendor support contract behind it. Before you commit, verify which release line you are pinning (v5.7.0 or 2026-lts-r9), confirm your cluster's Kubernetes version against the release you pick, and read the Helm chart values rather than assuming defaults.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. nginx/kubernetes-ingress on GitHub
3. Project website
4. README
5. Releases