Deploying and Configuring the ingress-nginx Ingress Controller on Kubernetes

The ingress-nginx controller translates Ingress resources into Nginx configuration files; when any relevant object changes, it rebuilds the model and reloads Nginx using a Lua module to avoid unnecessary reloads.

Operation principle – The controller watches Ingress, Service, Endpoints, Secret, ConfigMap, etc., rebuilds nginx.conf on changes, and reloads Nginx only when the model differs, using Lua for dynamic upstream handling.

Installation – The controller is typically installed with Helm. Example commands:

# Add repo and update
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
# Install chart
helm upgrade --install ingress-nginx . -f ./ci/daemonset-prod.yaml --namespace ingress-nginx

After installation, verify the controller pod and view the generated nginx.conf to see the assembled server blocks.

First example – Deploy a simple Nginx application and expose it via an Ingress:

# my-nginx.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-nginx
spec:
  selector:
    matchLabels:
      app: my-nginx
  template:
    metadata:
      labels:
        app: my-nginx
    spec:
      containers:
      - name: my-nginx
        image: nginx
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: my-nginx
spec:
  ports:
  - port: 80
    targetPort: 80
    name: http
  selector:
    app: my-nginx
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-nginx
spec:
  ingressClassName: nginx
  rules:
  - host: ngdemo.qikqiak.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-nginx
            port:
              number: 80

Apply the manifest and verify the Ingress is reachable at the specified host.

Basic Auth – Create an htpasswd file, store it in a Secret, and add annotations to the Ingress:

# Create secret
kubectl create secret generic basic-auth --from-file=auth
# Ingress with auth annotations
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-with-auth
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: basic-auth
    nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required - foo'
spec:
  ingressClassName: nginx
  rules:
  - host: bauth.qikqiak.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-nginx
            port:
              number: 80

Requests without credentials receive a 401 response; providing the correct user:password authenticates successfully.

URL Rewrite – Use the nginx.ingress.kubernetes.io/rewrite-target annotation to strip or replace path prefixes, e.g., mapping /gateway to the root of the service.

Canary / Gray‑release – Enable traffic splitting with annotations such as nginx.ingress.kubernetes.io/canary , canary-weight , canary-by-header , and canary-by-cookie . Example weight‑based split:

# canary-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: canary
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "30"
spec:
  ingressClassName: nginx
  rules:
  - host: echo.qikqiak.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: canary
            port:
              number: 80

Header‑ or cookie‑based rules can direct specific users to the canary version.

HTTPS – Generate a self‑signed certificate with openssl , store it in a TLS Secret, and reference it in the Ingress tls section.

TCP/UDP Services – Define a ConfigMap (e.g., tcp-services ) mapping external ports to ClusterIP services, and enable the controller flags --tcp-services-configmap and --udp-services-configmap . Example exposing MongoDB:

# tcp-services ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: tcp-services
  namespace: ingress-nginx
data:
  "27017": "default/mongo:27017"

After updating the Helm values, the controller creates a stream block in nginx.conf that proxies the TCP port.

Global Configuration – Set controller‑wide Nginx directives via the controller ConfigMap (e.g., client-max-body-size , keep-alive , gzip , etc.) and persist them through Helm values.

Node Kernel Tuning – Use an initContainer to apply sysctl settings (e.g., net.core.somaxconn , fs.file-max ) before the controller starts, improving performance under high load.