Traefik Migration from Nginx — The Complete Kubernetes Guide

What Is Traefik?

Traefik (pronounced traffic) is a cloud-native reverse proxy and load balancer written in Go, purpose-built for container orchestration environments. Unlike Nginx — a high-performance web server originally designed for static content that was later wrapped into a Kubernetes Ingress Controller — Traefik was designed from day one around the idea that infrastructure is dynamic and that routing config should never require a process restart.

The core proposition is simple: Traefik watches your infrastructure and auto-configures itself. No manual config reloads. No annotation soup. When a new Kubernetes Service appears or an IngressRoute is updated, Traefik detects it, builds the routing rule, and starts forwarding traffic — without a restart, without regenerating a config file, without dropping active connections.

Originally released in 2015 by Containous (now Traefik Labs), Traefik ships as a single Go binary with no external dependencies, is deployed as a Kubernetes Deployment or DaemonSet, and as of v3 (current stable) natively supports HTTP, HTTPS, TCP, UDP, gRPC, and WebSockets routing — all declaratively configured via Kubernetes CRDs.

How Traefik Works — The Request Pipeline

Understanding Traefik's internal pipeline is what separates operators who "just apply the Helm chart" from those who can actually debug it when something breaks. Every request Traefik handles passes through a fixed, ordered pipeline. Click each stage below to understand exactly what happens at that layer:

1. Entrypoints

Entrypoints are static listeners defined at startup — a port and protocol Traefik binds to. Common examples: :80 (web), :443 (websecure), :8080 (dashboard). These are the only things in Traefik that require a restart to change. Everything downstream is fully dynamic and hot-reloaded.

2. Routers

Routers are the decision layer. They match incoming requests against rules using Traefik's rule syntax: Host(`api.example.com`), PathPrefix(`/api`), Headers(`X-Custom`, `value`), or any combination using && and ||. Each Router is bound to one or more Entrypoints and connects to a Service — optionally through a named Middleware chain. Routers are defined in IngressRoute CRDs or standard Ingress annotations.

3. Middlewares

Middlewares transform requests or responses before they reach the backend. They are first-class Kubernetes objects (Middleware CRD), composable, and reusable across any number of Routers. Built-in middlewares cover: rate limiting, authentication (BasicAuth, ForwardAuth), CORS, circuit breakers, retry logic, redirect schemes, request body size limits, strip prefix, and header manipulation. Define them once, reference them by name everywhere — this is what kills the annotation sprawl.

4. Services

Services define where traffic lands after routing. A Traefik Service maps to a Kubernetes Service (via ClusterIP) and supports load balancing strategies — round-robin by default, or weighted backends for canary and blue/green deployments. You shift traffic between versions by changing a weight in Git. No kubectl patch, no imperative commands.

5. Providers

The Kubernetes provider bridges Traefik and your cluster. It continuously watches the Kubernetes API server — Ingress objects, IngressRoute CRDs, Services, and Endpoints — using informers, and reflects changes into Traefik's routing table instantly. This is what makes Traefik fundamentally different from Nginx: the routing config is not a file that gets rewritten and reloaded — it is a live in-memory data structure that updates without touching active connections.

Traefik Architecture in Kubernetes

In a Kubernetes cluster, Traefik runs as a Deployment (or DaemonSet on edge nodes), sits at the data plane edge, and bridges external traffic to internal Services. It registers either as a standard Kubernetes Ingress Controller for compatibility, or via its own IngressRoute CRDs for full capability.

Traefik Ingress Architecture — Full Stack

Figure 1 — External traffic arrives at Traefik's Entrypoints. IngressRoute CRDs define which Routers handle which hostnames and paths. Middleware chains apply rate limiting, auth, and headers before traffic reaches Kubernetes Services. TLS is terminated natively via built-in ACME. The Traefik Dashboard provides real-time observability of the full routing table.

Core Architecture Components

IngressRoute CRDs vs Standard Kubernetes Ingress

Traefik supports two configuration modes. Standard Ingress objects work for drop-in compatibility — useful if you have Helm charts that generate Ingress manifests you don't control. Traefik's native IngressRoute CRDs unlock the full feature set: explicit Middleware chaining, TCP and UDP routing, advanced load balancing, and priority-based routing. For any service you control, always use IngressRoute.

Traefik vs Nginx Ingress — Honest Production Comparison

This is not "Traefik wins everything." Here's an honest breakdown of what actually matters in a production cluster:

Production Example: Replacing Nginx Ingress with Traefik

The scenario: a production cluster running two services (api-service and frontend-service) with TLS, currently on Nginx Ingress Controller with cert-manager. Goal: migrate to Traefik with zero downtime by running both controllers in parallel and cutting over service by service.

Before vs After — Nginx to Traefik Migration

Figure 2 — Before: Nginx controller translates annotation-heavy Ingress objects into nginx.conf and reloads on every change. After: Traefik watches IngressRoute CRDs directly, updates its in-memory routing table with zero reloads, no dropped connections, and no cert-manager dependency.

# Add Traefik Helm repo
helm repo add traefik https://traefik.github.io/charts
helm repo update

# Install Traefik — NOT as the default IngressClass yet
helm install traefik traefik/traefik \
  --namespace traefik \
  --create-namespace \
  --set deployment.replicas=2 \
  --set ports.websecure.tls.enabled=true \
  --set providers.kubernetesCRD.enabled=true \
  --set providers.kubernetesIngress.enabled=true \
  --set ingressClass.enabled=true \
  --set ingressClass.isDefaultClass=false \
  --set logs.access.enabled=true \
  --set metrics.prometheus.enabled=true

# Verify Traefik pods are running
kubectl get pods -n traefik
# NAME                       READY   STATUS    RESTARTS
# traefik-7d9b8f6c4d-2xkpv   1/1     Running   0
# traefik-7d9b8f6c4d-9rqnm   1/1     Running   0

# ── BEFORE: nginx-ingress.yaml ──────────────────────────────────────────────
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  namespace: production
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/limit-rps: "100"
    nginx.ingress.kubernetes.io/limit-connections: "20"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    # ...and 10 more annotations you've forgotten the meaning of
spec:
  tls:
    - hosts: ["api.example.com", "app.example.com"]
      secretName: app-tls-secret
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend-service
                port:
                  number: 80

# ── traefik-middlewares.yaml ────────────────────────────────────────────────
---
# HTTPS redirect — applied to all HTTP entrypoint routes
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: redirect-https
  namespace: production
spec:
  redirectScheme:
    scheme: https
    permanent: true
---
# Rate limiting — 100 req/min average, burst of 200
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: rate-limit
  namespace: production
spec:
  rateLimit:
    average: 100
    burst: 200
    period: 1m
---
# Request body size limit (replaces proxy-body-size annotation)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: body-limit
  namespace: production
spec:
  buffering:
    maxRequestBodyBytes: 52428800   # 50MB
---
# Security headers — applied globally to all routes
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: secure-headers
  namespace: production
spec:
  headers:
    frameDeny: true
    browserXssFilter: true
    contentTypeNosniff: true
    stsSeconds: 31536000
    stsIncludeSubdomains: true

# Apply: kubectl apply -f traefik-middlewares.yaml

# ── traefik-ingressroutes.yaml ──────────────────────────────────────────────
---
# API service — HTTPS with rate limiting, body limit, and security headers
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: api-route
  namespace: production
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`api.example.com`)
      kind: Rule
      middlewares:
        - name: rate-limit
          namespace: production
        - name: body-limit
          namespace: production
        - name: secure-headers
          namespace: production
      services:
        - name: api-service
          port: 8080
  tls:
    certResolver: letsencrypt     # Traefik handles this — no cert-manager needed
---
# Frontend — HTTPS with rate limiting and security headers
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: frontend-route
  namespace: production
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`app.example.com`)
      kind: Rule
      middlewares:
        - name: rate-limit
          namespace: production
        - name: secure-headers
          namespace: production
      services:
        - name: frontend-service
          port: 80
  tls:
    certResolver: letsencrypt
---
# HTTP catch-all redirect to HTTPS
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: redirect-http
  namespace: production
spec:
  entryPoints:
    - web
  routes:
    - match: HostRegexp(`{host:.+}`)
      kind: Rule
      priority: 1
      middlewares:
        - name: redirect-https
          namespace: production
      services:
        - name: noop@internal
          kind: TraefikService

# ── traefik-values.yaml (Helm override) ─────────────────────────────────────
additionalArguments:
  - "[email protected]"
  - "--certificatesresolvers.letsencrypt.acme.storage=/data/acme.json"
  - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
  # Test with staging first:
  # - "--certificatesresolvers.letsencrypt.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

persistence:
  enabled: true          # CRITICAL — without this, acme.json is lost on pod restart
  size: 128Mi
  storageClass: "local-path"

deployment:
  replicas: 2

resources:
  requests:
    cpu: 200m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

# Apply the updated release:
# helm upgrade traefik traefik/traefik -n traefik -f traefik-values.yaml

# ── Validate before touching DNS ────────────────────────────────────────────

# Check Traefik pods are healthy with 0 restarts
kubectl get pods -n traefik

# Verify IngressRoutes are registered
kubectl get ingressroute -n production
# NAME              AGE
# api-route         2m
# frontend-route    2m
# redirect-http     2m

# Access Traefik dashboard — verify all routers show as green
kubectl port-forward -n traefik \
  $(kubectl get pod -n traefik -l app.kubernetes.io/name=traefik -o name | head -1) \
  9000:9000
# Open: http://localhost:9000/dashboard

# Test routing BEFORE DNS cutover — curl against Traefik's external IP directly
TRAEFIK_IP=$(kubectl get svc -n traefik traefik -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

curl --resolve "api.example.com:443:${TRAEFIK_IP}" \
     https://api.example.com/healthz -k -w "%{http_code}\n"
# Expected: 200

curl --resolve "app.example.com:443:${TRAEFIK_IP}" \
     https://app.example.com/ -k -w "%{http_code}\n"
# Expected: 200

# ── All good? Do the cutover ─────────────────────────────────────────────────

# Scale down Nginx Ingress Controller
kubectl scale deployment ingress-nginx-controller \
  -n ingress-nginx --replicas=0

# Get Traefik external IP and update your DNS A records / LoadBalancer selector
echo "Point DNS to: ${TRAEFIK_IP}"

# Set Traefik as the new default IngressClass
kubectl patch ingressclass traefik \
  -p '{"metadata":{"annotations":{"ingressclass.kubernetes.io/is-default-class":"true"}}}'

Observability — Dashboard and Prometheus Metrics

Traefik ships with a built-in dashboard on :8080/dashboard and exposes Prometheus metrics on :8080/metrics by default. If you're running kube-prometheus-stack, add a ServiceMonitor to scrape Traefik automatically:

# manifests/monitoring/traefik-servicemonitor.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: traefik-metrics
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: traefik
  namespaceSelector:
    matchNames: [traefik]
  endpoints:
    - port: metrics
      path: /metrics
      interval: 30s

# ── Key metrics to monitor and alert on ─────────────────────────
#
# traefik_router_requests_total              — RPS per router (rate)
# traefik_router_request_duration_seconds    — P50/P95/P99 latency per router
# traefik_service_requests_total             — Requests reaching backends
# traefik_service_server_up                 — Backend health (0=down, 1=up)
# traefik_tls_certs_not_after               — Certificate expiry (Unix timestamp)
#
# Alert rule example — cert expiry under 7 days:
# alert: TraefikCertExpiringSoon
#   expr: (traefik_tls_certs_not_after - time()) / 86400 < 7
#   labels:
#     severity: warning

This Isn't Optional Anymore — Ingress NGINX Is End-of-Life in March 2026

The retirement wasn't a surprise — it was years in the making. The project was maintained by one or two volunteers working evenings and weekends against an "endless flood of bugs and feature requests." The flexibility that made Ingress NGINX popular — arbitrary NGINX config directives via snippet annotations — became its biggest security liability. CVE-2025-1974 in 2025 underscored exactly how dangerous an under-resourced edge controller is. The responsible decision was to set a hard EOL date rather than pretend the project was sustainable.

The official recommendation from Kubernetes SIG Network is to migrate to either the Gateway API (the modern, long-term replacement) or a maintained alternative Ingress controller. Traefik is explicitly listed as a recommended migration target — with native Gateway API support already built into v3, meaning you can migrate to Traefik now and adopt Gateway API resources at your own pace without a second migration.

When Should You Switch to Traefik? (Hint: Now)

The question used to be "should we switch?" The EOL announcement changes that entirely. The question is now "which controller do we switch to, and what is our timeline?" Here is how to frame that decision:

Conclusion: Routing Config That Actually Belongs in Git

The fundamental difference between Nginx Ingress and Traefik is not performance — it is model. Nginx Ingress is a static config system bolted onto Kubernetes via annotation accumulation. Traefik is a dynamic routing system that treats Kubernetes CRDs as its native language, built for environments where services appear, disappear, and change constantly.

For teams running GitOps workflows, the operational gap is real. IngressRoute CRDs produce meaningful diffs in pull requests. Middlewares are explicit, named, and reusable without duplication. TLS is handled without a separate operator. And routing updates propagate without a single dropped connection.

The migration itself is low-risk when done in parallel: run both controllers simultaneously using separate IngressClasses, migrate service by service, validate with curl before touching DNS, then cut over. For a cluster with a dozen services, the migration is typically an afternoon — most of that time is reading Traefik's documentation for the first time. The CRD model is simpler than it looks.

"Nginx was built to serve files. Traefik was built to route services. At scale in Kubernetes, that design difference shows up in every config change, every deployment, and every incident at 2 AM."

Running Traefik on your RKE2 or on-prem clusters? Migrating from Nginx Ingress? Share your experience in the comments below, or reach out to the ClusterCraftOPS team.