NGINX Ingress Controller: Configuration, TLS & Annotations

DodaTech 2 min read

In this tutorial, you'll learn about NGINX Ingress Controller: Configuration, TLS & Annotations. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The NGINX Ingress Controller is the most widely used Kubernetes ingress solution, offering advanced traffic routing through annotations, configuration snippets, and custom templates.

What You'll Learn

This tutorial covers NGINX Ingress Controller deployment, advanced annotations, TLS certificate management with cert-manager, canary deployments, custom error pages, and performance tuning.

Why It Matters

Production clusters rely on Ingress Controllers for 80 percent of external traffic. Misconfigured ingress causes SSL errors, slow page loads, and routing failures that affect thousands of users.

Real-World Use

Slack and Shopify use NGINX Ingress Controller with custom annotations for Rate Limiting, OAuth authentication, and A B testing at the edge, handling millions of requests per minute.

Deploying NGINX Ingress Controller

Deploy the controller using Helm or manifests.

# Deploy with Helm
helm upgrade --install ingress-nginx ingress-nginx \
  --repo https://kubernetes.github.io/ingress-nginx \
  --namespace ingress-nginx --create-namespace

# Check deployment
kubectl -n ingress-nginx get pods

Advanced Annotations

Annotations customize ingress behavior without modifying the controller configuration.

Rewrite Targets

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /api(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80

Rate Limiting

annotations:
  nginx.ingress.kubernetes.io/limit-rps: "10"
  nginx.ingress.kubernetes.io/limit-burst-multiplier: "5"
  nginx.ingress.kubernetes.io/limit-whitelist: "10.0.0.0/8"

CORS Configuration

annotations:
  nginx.ingress.kubernetes.io/enable-cors: "true"
  nginx.ingress.kubernetes.io/cors-allow-origin: "https://app.example.com"
  nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT"

TLS Certificate Management

Manage TLS certificates using cert-manager for automatic renewal.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
    - http01:
        ingress:
          class: nginx
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: secure-app
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - app.example.com
    secretName: app-tls
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80

Canary Releases with NGINX Ingress

The controller supports canary deployments through the canary annotation.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-canary
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "10"
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-service-canary
            port:
              number: 80

Custom Error Pages

Replace default 404 and 502 pages with branded content using a custom backend.

annotations:
  nginx.ingress.kubernetes.io/custom-http-errors: "404,502,503"
  nginx.ingress.kubernetes.io/error-backend: custom-errors

Configuration Snippet for Advanced Rules

Inject raw NGINX configuration using snippets.

annotations:
  nginx.ingress.kubernetes.io/configuration-snippet: |
    if ($host = 'legacy.example.com') {
      rewrite ^ https://app.example.com$request_uri permanent;
    }
    sub_filter 'http://' 'https://';
    sub_filter_once off;

Configuring Proxy Timeouts

annotations:
  nginx.ingress.kubernetes.io/proxy-connect-timeout: "10"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
  nginx.ingress.kubernetes.io/proxy-send-timeout: "120"
  nginx.ingress.kubernetes.io/proxy-body-size: "50m"

Practice Questions

What annotation enables canary deployments with NGINX Ingress? nginx.ingress.Kubernetes.io/canary: "true" with canary-weight for traffic percentage.
How does cert-manager integrate with NGINX Ingress? cert-manager uses the cert-manager.io/cluster-issuer annotation to automatically issue and renew TLS certificates.
What does the rewrite-target annotation do? It rewrites the request path before forwarding to the backend service.
How do you limit requests per second on an ingress? Use limit-rps and limit-burst-multiplier annotations.
What is the purpose of configuration-snippet? It injects raw NGINX configuration directives into the generated NGINX config.

← Previous Kubernetes Deployment Strategies: Rolling, Blue-Green & Canary Next → Helm Charts: Package Management for Kubernetes

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Kubernetes