ingress-nginx — Kubernetes NGINX Ingress Controller

Introduction

ingress-nginx is one of the oldest and most widely deployed Kubernetes ingress controllers. Maintained by Kubernetes SIG Network, it takes the declarative Ingress API and turns it into a carefully tuned, hot-reloadable NGINX configuration, giving clusters TLS termination, path-based routing, rate limiting, and observability with almost zero bespoke glue.

What ingress-nginx Does

• Watches Ingress, Service, Secret, and Gateway API objects and renders them into NGINX configuration.
• Terminates TLS using Kubernetes Secrets (and cert-manager issuers) and supports SNI, ALPN, and HTTP/2.
• Enforces rate limits, IP allow-lists, basic/external auth, CORS, and canary traffic splits via annotations.
• Exposes rich Prometheus metrics and structured access logs for every request.
• Integrates with external load balancers (cloud LB, MetalLB, host-network) via a single type=LoadBalancer Service.

Architecture Overview

The controller runs as a Deployment or DaemonSet of Go processes that embed a full NGINX (or OpenResty + Lua) binary. A Kubernetes informer stack watches relevant API resources; on change the Go side reconciles an in-memory model, renders nginx.conf via Go templates, and triggers NGINX''s live reload. Lua modules handle dynamic endpoints and canary routing without reload storms when only Pod IPs change.

Self-Hosting & Configuration

• Deploy via Helm, the deploy.yaml manifest, or any GitOps tool; one controller per IngressClass is typical.
• Tune NGINX directives cluster-wide through a ConfigMap (proxy-body-size, worker-processes, TLS protocols).
• Expose via Service: LoadBalancer, NodePort, or host-network DaemonSet depending on your platform.
• Enable the ServiceMonitor for Prometheus and ship JSON logs to Loki or Elastic for debugging.
• Restrict which namespaces the controller watches with --watch-namespace for multi-tenant isolation.

Key Features

• Gateway API v1 support alongside the classic Ingress resource.
• Dynamic Lua-based load balancing without full NGINX reloads on endpoint churn.
• First-class mTLS, OCSP stapling, and HSTS configuration via annotations.
• Built-in support for canary, blue/green, and weighted traffic splitting.
• Battle-tested by thousands of production clusters; strong CVE response history.

Comparison with Similar Tools

• Traefik — Go-native ingress with slicker dashboard and Let''s Encrypt built-in; ingress-nginx is more NGINX-feature-rich.
• HAProxy Ingress — excellent TCP/UDP and latency story; smaller community than ingress-nginx.
• Envoy-based (Contour/Emissary/Istio) — xDS-driven, great for service mesh integration; more moving parts.
• Kong Ingress — API-gateway-first with plugins/auth; heavier footprint for simple HTTP routing.
• NGINX Inc. nginx-ingress — a separate, commercially-backed controller (often called “kic”); different annotation set.

FAQ

Q: Is this the same as NGINX Inc.''s controller? A: No. This is the Kubernetes-community project; NGINX Inc. ships a different controller (nginxinc/kubernetes-ingress).

Q: Does it support TCP/UDP services? A: Yes, via a separate ConfigMap (tcp-services / udp-services) that maps ports to namespaced Services.

Q: How do I add Let''s Encrypt certificates? A: Pair it with cert-manager; use a ClusterIssuer and add a tls: block plus the cert-manager.io/cluster-issuer annotation.

Q: Should I use Gateway API or Ingress? A: For new clusters, Gateway API offers cleaner route composition. Ingress remains fully supported and well-documented.

Sources

• https://github.com/kubernetes/ingress-nginx
• https://kubernetes.github.io/ingress-nginx/