Traefik to NGINX Ingress Migration Tool (Beta)

Beta: The Traefik migration tool is new and under active development. Its mappings and the resources the analyzer generates may still change, so review the output before applying it to a cluster, and report anything it gets wrong.
Migrating from Traefik? Traefik Proxy is an actively maintained project — this guide is for teams standardizing on the NGINX data plane. It translates Traefik's IngressRoute + Middleware model into the NGINX Ingress Controller's VirtualServer + Policy model, resource by resource.
Version reference: This tool is based on Traefik Proxy v3.7.17 and NGINX Ingress Controller v5.7.0.

Overview

This interactive guide helps you migrate from Traefik Proxy (traefik/traefik) to the NGINX Ingress Controller (nginx/kubernetes-ingress). It covers all 24 HTTP middlewares of Traefik's open source edition, the traefik.ingress.kubernetes.io/ Ingress annotations, Traefik's Kubernetes CRDs (IngressRoute, TraefikService, TLSOption, TLSStore, ServersTransport, and the TCP/UDP variants), and static-configuration translation across three tabs:

  • Getting started — Why teams migrate, NGINX Ingress Controller CRD overviews, installation, and a migration checklist
  • Traefik config analyzer — Paste IngressRoute, Middleware, or annotated Ingress manifests and get automatic migration suggestions with ready-to-use YAML
  • Reference guide — Complete middleware, annotation, and CRD mapping tables with side-by-side examples

Why migrate?

Unlike migrations forced by a project sunset, moving off Traefik is a choice — Traefik Proxy is actively maintained. Teams that migrate usually do it to consolidate:

  • Standardize on the NGINX data plane — One proxy technology across VMs, containers, and Kubernetes means one set of operational knowledge, one config language to debug, and consistent performance characteristics everywhere
  • Battle-tested NGINX core — The NGINX Ingress Controller configures stock NGINX (NGINX Open Source or NGINX Plus), so decades of NGINX tuning knowledge, modules, and monitoring practices apply directly
  • Flatter resource graph — An IngressRoute plus a chain of Middleware objects becomes one VirtualServer plus reusable Policies: schema-validated CRDs with fewer cross-resource references to trace
  • NGINX Plus upgrade path — JWT, OIDC, WAF, and active health checks are available as NGINX Plus policies without switching to a different commercial product family (API-key auth maps to the NGINX Ingress Controller apiKey Policy, which needs no NGINX Plus)
  • Commercial support from F5 — Enterprise support contracts cover the controller and the data plane together

The two controllers structure configuration differently, and knowing the mental model makes the mappings obvious:

  • Traefik attaches chainable Middleware objects to routers, terminates TLS with a built-in ACME client, and splits configuration between static entryPoints and dynamic providers
  • NGINX Ingress Controller attaches reusable Policy objects to VirtualServers (or Ingress resources via nginx.org/policies), integrates with cert-manager for certificates, and keeps global settings in one ConfigMap
Fair warning: a few Traefik conveniences work differently on NGINX Ingress Controller — the built-in Let's Encrypt client is replaced by cert-manager, the dashboard by Prometheus/Grafana, and per-router observability toggles by global settings. The Key Differences table covers these head-on.

Phased migration strategy

Rather than performing a "big bang" cutover, F5 recommends a phased migration that validates each application before decommissioning Traefik. Because Traefik's CRDs (traefik.io) and NGINX Ingress Controller's CRDs (k8s.nginx.org) are separate API groups, both controllers coexist in one cluster without touching each other's resources — the migration is additive translation, not in-place mutation.

  1. Deploy side-by-side — Install the NGINX Ingress Controller alongside Traefik. Existing IngressRoutes are untouched; plain Ingress resources stay with Traefik until you flip their ingressClassName.
  2. Translate service-by-service — Create the VirtualServer, Policy, and TransportServer resources for one application at a time (the Config analyzer generates first drafts). Validate against the NGINX Ingress Controller LoadBalancer IP with curl --resolve app.example.com:443:<NGINX-IP>, then flip that host's DNS record. Plain-Ingress users instead switch ingressClassName from traefik to nginx after converting annotations.
  3. Decommission — After every host has been cut over and validated, remove the Traefik Deployment, its IngressClass, the traefik.io CRDs, and the Middleware/TraefikService objects they managed.

Defaults that change

A setting you never configured still changes if the two controllers default it differently. Set the NGINX Ingress Controller value in the nginx-config ConfigMap, or per resource, wherever the old default matters to you.

SettingTraefik ProxyNGINX Ingress ControllerWhat to check
Request body sizeNo limit1m (client-max-body-size)Uploads over 1 MB get 413. Set client-max-body-size to the largest body you accept.
Response bufferingStreamed, flushed every 100msOn (proxy-buffering)Server-sent events and long polls need proxy-buffering: "false".
HTTP/2Offered over TLS (ALPN h2)Off (http2)Set http2: "true" to keep HTTP/2 for clients.
Upstream connect timeout30s (dialTimeout)60s (proxy-connect-timeout)Unreachable backends take twice as long to fail.
Upstream response timeoutNone (responseHeaderTimeout 0)60s (proxy-read-timeout)A backend silent for over 60s gets 504. Raise proxy-read-timeout for slow endpoints.
Client keep-alive idle timeout180s (idleTimeout)75s (keepalive-timeout)Clients reconnect sooner; match it if a load balancer in front keeps connections longer.
Load-balancing methodWeighted round robinrandom two least_conn (lb-method)Set lb-method: round_robin for Traefik's distribution.
Health checksNone unless configuredPassive: 1 failure in 10s (max-fails, fail-timeout)A server that fails once is skipped for 10s. Set max-fails: 0 for Traefik's behavior.
Plain HTTP on a TLS hostServed, unless a redirectScheme middleware redirects itRedirected with 301 (ssl-redirect)An Ingress with spec.tls redirects plain HTTP. Set nginx.org/ssl-redirect: "false" to keep serving it.
Server headerThe backend's ownNGINX and its version (server-tokens)Set server-tokens: "false" to hide the version.
Tip: Migrate certificates first. NGINX Ingress Controller has no built-in ACME client — install cert-manager and issue certificates for each host before the DNS cutover so the new controller serves valid TLS from the first request (Traefik's acme.json certificates are not Kubernetes Secrets and cannot be reused directly).

CRDs summary

The NGINX Ingress Controller uses Custom Resource Definitions (CRDs) to extend Kubernetes with NGINX-specific configuration. CRDs provide type-safe, validated configuration that goes beyond what standard Ingress annotations can offer.

VirtualServer CRD

The primary CRD for configuring HTTP/HTTPS load balancing. It replaces Ingress resources and provides advanced traffic management capabilities with full validation.

  • Traffic Splitting: Route percentages of traffic to different backends for canary/blue-green deployments
  • Content-Based Routing: Route based on headers, cookies, arguments, or variables
  • Path Rewriting: Modify request URIs with regex support before forwarding to backends
  • Error Pages: Custom responses for specific HTTP error codes
  • Request/Response Headers: Add, modify, or remove headers in transit
  • Health Checks: Active health monitoring of upstream servers
  • Session Persistence: Cookie-based sticky sessions

VirtualServerRoute CRD

Enables delegation of route configuration to different namespaces. Allows teams to manage their own routing rules while maintaining centralized control over the domain.

  • Cross-Namespace Routing: Reference services in different namespaces
  • Path Delegation: Delegate path prefixes to other teams/namespaces
  • Independent Updates: Teams update routes without modifying the parent VirtualServer
  • Access Control: Limit which namespaces can define routes for a host

Policy CRD

Reusable security and traffic policies that can be attached to VirtualServers or specific routes. Policies enable consistent security controls across multiple applications.

  • Rate Limiting: Limit request rates by IP, header, or custom key
  • Access Control: IP allowlists and denylists
  • Basic Auth: Username/password authentication via htpasswd
  • JWT Validation: Validate JSON Web Tokens (Plus)
  • OIDC: Native OpenID Connect integration (Plus)
  • API Key Auth: Authenticate via API keys in headers/query
  • mTLS: Client certificate verification (ingress) and backend TLS (egress)
  • WAF: F5 WAF for NGINX web application firewall (Plus)

TransportServer CRD

Configures TCP/UDP load balancing for non-HTTP protocols. Essential for databases, message queues, gaming servers, and other Layer 4 applications.

  • TCP Load Balancing: MySQL, PostgreSQL, Redis, custom TCP services
  • UDP Load Balancing: DNS, RADIUS, gaming protocols
  • TLS Passthrough: Pass encrypted traffic directly to backends
  • Health Checks: TCP/UDP health monitoring
  • Session Persistence: IP hash-based session affinity

GlobalConfiguration CRD

Cluster-wide configuration for the NGINX Ingress Controller. Defines global listeners for TCP/UDP and TLS passthrough that TransportServers can reference.

  • TCP/UDP Listeners: Define ports for non-HTTP traffic
  • TLS Passthrough Listeners: Configure SNI-based routing
  • Global Settings: Controller-wide configuration options

Installing CRDs

CRDs can be installed via Helm or manually using manifests, depending on your deployment method. See the NGINX Ingress Controller installation docs for full instructions.

Helm (example)

If you install the NGINX Ingress Controller via Helm, CRDs are included automatically. To ensure they are enabled:

helm install nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 2.8.0 --set controller.enableCustomResources=true

The controller.enableCustomResources flag is true by default. If you previously disabled it, re-enable it to use CRD resources. See the Helm installation guide for details.

Manifests (example)

If you deploy using manifests, install CRDs manually before deploying the controller:

kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v5.7.0/deploy/crds.yaml

Replace the version number with your target controller version. See the manifest installation guide for the full step-by-step process.

Note: The crds.yaml file contains all CRDs (VirtualServer, VirtualServerRoute, Policy, TransportServer, GlobalConfiguration) in a single manifest.
Note: Replace version numbers with your target controller version.

Migration checklist

Progress is saved in your browser.
  • Install NGINX Ingress Controller CRDs via Helm (controller.enableCustomResources=true) or manifests (deploy/crds.yaml)
  • Inventory Traefik resources cluster-wide: kubectl get ingressroutes,ingressroutetcps,ingressrouteudps,middlewares,middlewaretcps,traefikservices,tlsoptions,tlsstores,serverstransports,serverstransporttcps -A
  • Audit entryPoints and map custom ports to GlobalConfiguration listeners or nginx.org/listen-ports
  • Replace Let's Encrypt certResolvers with cert-manager Issuers (or pre-provisioned Secrets) before cutover — acme.json certificates cannot be reused
  • Convert IngressRoute match rules to VirtualServer host/routes[].path/matches
  • Convert basicAuth middlewares to the basicAuth Policy — re-create Secrets as type nginx.org/htpasswd (key htpasswd)
  • Convert forwardAuth middlewares to the externalAuth Policy (v5.5.0+)
  • Convert ipAllowList middlewares to the accessControl Policy (configure set-real-ip-from when behind a proxy)
  • Convert rateLimit middlewares to the rateLimit Policy — convert average/period to r/s or r/m and review burst semantics
  • Convert headers middlewares — CORS to the cors Policy, HSTS to nginx.org/hsts*, custom headers to VirtualServer requestHeaders/responseHeaders
  • Convert stripPrefix/addPrefix/replacePath chains to VirtualServer action.proxy.rewritePath or nginx.org/rewrites
  • Convert errors middlewares to VirtualServer errorPages (explicit status codes — no ranges)
  • Convert redirectScheme/redirectRegex to nginx.org/redirect-to-https or VirtualServer action.redirect
  • Convert weighted TraefikServices to VirtualServer splits; mirroring is snippet-based (no native field — and percent sampling has no equivalent)
  • Convert sticky sessions (sticky.cookie) to VirtualServer upstream sessionCookie
  • Convert IngressRouteTCP/UDP and TLS passthrough (HostSNI) to TransportServer + GlobalConfiguration listeners
  • Convert TLSOptions to ConfigMap ssl-protocols/ssl-ciphers; move clientAuth to ingressMTLS policies
  • Convert ServersTransports to egressMTLS policies and VirtualServer upstream TLS/timeout settings
  • Audit Traefik Hub middlewares (JWT, OIDC, WAF) and map them to NGINX Plus policies; the Hub API-key middleware maps to the NGINX Ingress Controller apiKey Policy, which needs no NGINX Plus
  • Recreate observability — Prometheus scrape target (-enable-prometheus-metrics), log-format, OTel ConfigMap keys; replace Traefik dashboard views with Grafana
  • Test in staging environment
  • Cut over DNS host-by-host, update monitoring and alerting, then decommission the Traefik Deployment, IngressClass, and CRDs

Command line tool

Beta: nic-migrate is new and under active development. Review its output before applying anything to a cluster — command names, flags, and the manifests it generates may still change.

The analyzer on this page works on one paste at a time. nic-migrate runs the same engine from a terminal with --source traefik, across a directory of manifests or read straight from a running cluster. It loads the mapping database out of this site's own source rather than keeping a second copy, so it cannot drift from the tables in the reference guide. It is not distributed as a download — clone the repository for this site and run it with Node 18 or newer, with nothing to install.

Review what would change

Reads the CRs Traefik keeps its configuration in — IngressRoute and its TCP and UDP forms, Middleware, TraefikService, TLSOption, TLSStore and ServersTransport — as well as annotated Ingress objects, and prints the annotation swaps, the Policies and CRDs required, and anything the analyzer cannot express on its own, graded blocking, review, or note. Traefik's static configuration is not included: it is command-line flags or a traefik.yml, not a Kubernetes object, so only the tables on this page cover it.

node tools/nic-migrate/nic-migrate.js report --source traefik --whole-input -f ./manifests

Generate manifests

Merges those results into resources you can apply: one VirtualServer per host carrying every route and backend, with Policies referenced, TLS preserved, and the namespace kept. --target ingress instead keeps your Ingress resources and rewrites their annotations. Pass --class to set NGINX Ingress Controller's IngressClass — a class naming Traefik is left off the output, because NGINX Ingress Controller ignores a resource claiming a class it does not own, and does so without erroring.

node tools/nic-migrate/nic-migrate.js convert --source traefik --class nginx -f ./manifests --validate

Use --whole-input for Traefik. A Middleware is a separate object from the IngressRoute that references it, and by default each document is analyzed on its own — so every reference is reported as unresolved and the middlewares contribute nothing. --whole-input analyzes the input as one unit, the way this page treats a paste, and a rate-limit Middleware becomes a rateLimit Policy while a headers Middleware becomes the HSTS annotations. The trade is that the engine keeps one host, one service and one path across the whole input, and reports the rest as dropped.

Neither command drops anything silently: where a construct has no equivalent on the target you choose, it is named rather than omitted. Read the notes each run prints, keep --validate on so the output is checked against a live cluster with kubectl apply --dry-run=server, and see the full option reference and known limitations.

Additional resources