# ingress-nginx — Kubernetes NGINX Ingress Controller

> ingress-nginx is the community Kubernetes ingress controller built on NGINX, turning Ingress and Gateway API resources into production-ready HTTP/S and TCP load-balancer configuration.

## Install

Save in your project root:

# ingress-nginx — Kubernetes NGINX Ingress Controller

## Quick Use
```bash
# Install with the official Helm chart
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx 
  -n ingress-nginx --create-namespace

# A minimal Ingress routing example.com to a ClusterIP service
kubectl apply -f - <<YAML
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web
            port: {number: 80}
YAML
```

## 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/


---
Source: https://tokrepo.com/en/workflows/52fdb775-38ce-11f1-9bc6-00163e2b0d79
Author: AI Open Source