Traefik to NGINX Ingress Migration Tool (Beta)
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
apiKeyPolicy, 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
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.
- 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. - 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 switchingressClassNamefromtraefiktonginxafter converting annotations. - Decommission — After every host has been cut over and validated, remove the Traefik Deployment, its IngressClass, the
traefik.ioCRDs, 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.
| Setting | Traefik Proxy | NGINX Ingress Controller | What to check |
|---|---|---|---|
| Request body size | No limit | 1m (client-max-body-size) | Uploads over 1 MB get 413. Set client-max-body-size to the largest body you accept. |
| Response buffering | Streamed, flushed every 100ms | On (proxy-buffering) | Server-sent events and long polls need proxy-buffering: "false". |
| HTTP/2 | Offered over TLS (ALPN h2) | Off (http2) | Set http2: "true" to keep HTTP/2 for clients. |
| Upstream connect timeout | 30s (dialTimeout) | 60s (proxy-connect-timeout) | Unreachable backends take twice as long to fail. |
| Upstream response timeout | None (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 timeout | 180s (idleTimeout) | 75s (keepalive-timeout) | Clients reconnect sooner; match it if a load balancer in front keeps connections longer. |
| Load-balancing method | Weighted round robin | random two least_conn (lb-method) | Set lb-method: round_robin for Traefik's distribution. |
| Health checks | None unless configured | Passive: 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 host | Served, unless a redirectScheme middleware redirects it | Redirected with 301 (ssl-redirect) | An Ingress with spec.tls redirects plain HTTP. Set nginx.org/ssl-redirect: "false" to keep serving it. |
Server header | The backend's own | NGINX and its version (server-tokens) | Set server-tokens: "false" to hide the version. |
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.
crds.yaml file contains all CRDs (VirtualServer, VirtualServerRoute, Policy, TransportServer, GlobalConfiguration) in a single manifest.Migration checklist
- 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.jsoncertificates cannot be reused - Convert IngressRoute match rules to VirtualServer
host/routes[].path/matches - Convert basicAuth middlewares to the
basicAuthPolicy — re-create Secrets as typenginx.org/htpasswd(keyhtpasswd) - Convert forwardAuth middlewares to the
externalAuthPolicy (v5.5.0+) - Convert ipAllowList middlewares to the
accessControlPolicy (configureset-real-ip-fromwhen behind a proxy) - Convert rateLimit middlewares to the
rateLimitPolicy — convertaverage/periodtor/sorr/mand review burst semantics - Convert headers middlewares — CORS to the
corsPolicy, HSTS tonginx.org/hsts*, custom headers to VirtualServerrequestHeaders/responseHeaders - Convert stripPrefix/addPrefix/replacePath chains to VirtualServer
action.proxy.rewritePathornginx.org/rewrites - Convert errors middlewares to VirtualServer
errorPages(explicit status codes — no ranges) - Convert redirectScheme/redirectRegex to
nginx.org/redirect-to-httpsor VirtualServeraction.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 upstreamsessionCookie - Convert IngressRouteTCP/UDP and TLS passthrough (HostSNI) to TransportServer + GlobalConfiguration listeners
- Convert TLSOptions to ConfigMap
ssl-protocols/ssl-ciphers; moveclientAuthtoingressMTLSpolicies - Convert ServersTransports to
egressMTLSpolicies 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
apiKeyPolicy, 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
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
Traefik config analyzer
Paste Traefik Kubernetes resources — IngressRoute, Middleware, TraefikService, IngressRouteTCP/UDP, TLSOption, ServersTransport, or an Ingress with traefik.ingress.kubernetes.io/ annotations — to get migration suggestions for the NGINX Ingress Controller. Multiple YAML documents separated by --- are analyzed together, so include the Middlewares your IngressRoutes reference.
Key differences
| Aspect | Traefik Proxy | NGINX Ingress Controller |
|---|---|---|
| Repository | traefik/traefik | nginx/kubernetes-ingress |
| Data plane | Traefik (Go) | NGINX Open Source or NGINX Plus |
| Annotation prefix | traefik.ingress.kubernetes.io/ (router.* on the Ingress, service.* on the Service) | nginx.org/ or nginx.com/ or appprotect.f5.com/ |
| ConfigMap name | None: static configuration (entry points, providers, certificate resolvers) in a file, flags or Helm values | nginx-config |
| CRD support | IngressRoute, IngressRouteTCP, IngressRouteUDP, Middleware, MiddlewareTCP, ServersTransport, ServersTransportTCP, TLSOption, TLSStore, TraefikService (traefik.io/v1alpha1) | VirtualServer, VirtualServerRoute, Policy, TransportServer, GlobalConfiguration |
| Enterprise support | Traefik Hub (JWT, OIDC, API key, WAF, distributed rate limiting) | NGINX Plus (F5 WAF for NGINX, F5 DoS for NGINX, JWT, OIDC, active health checks, zone sync) |
| Per-route features | Middleware CRDs attached to routers, in order | Policy CRDs in VirtualServer policies[] or nginx.org/policies, and VirtualServer route fields |
| Listeners | Entry points (static configuration) | GlobalConfiguration listeners and nginx.org/listen-ports* |
| TLS certificates | Built-in ACME resolvers; TLSOption and TLSStore CRDs | Kubernetes Secrets, cert-manager (VirtualServer tls.cert-manager); TLS settings in the ConfigMap |
In NGINX Ingress Controller: nginx.org/proxy-http-version and a VirtualServer upstream's proxy-http-version set the HTTP version spoken to the backend, HTTP/2 included, where a snippet was needed before. nginx.org/http2 or spec.http2 turns HTTP/2 on per host. An Opaque Secret works wherever a CA, TLS, or htpasswd Secret did. The otel-trace-context ConfigMap key can continue an incoming trace, and the use-forwarded-headers key keeps the forwarded headers a proxy in front has set. least_time last_byte load balancing is now on NGINX Open Source. cert-manager HTTP-01 challenges pass the HTTPS redirect and authentication, and -enable-topology-aware-routing sends traffic to the endpoints in the controller pod's own zone when the Service asks for it.
For Traefik users: traefik.ingress.kubernetes.io/service.serversscheme: h2c maps to nginx.org/proxy-http-version: "2", or the same field on a VirtualServer upstream. Set otel-trace-context: propagate to continue an incoming trace, as Traefik does.
In NGINX Ingress Controller: nginx.org/custom-http-errors serves intercepted errors from the Ingress's spec.defaultBackend, and nginx.org/upstream-vhost sets the Host header sent upstream. The disable-forwarded-headers ConfigMap key stops the X-Forwarded-* headers. A new hsts Policy CRD sets HSTS on a VirtualServer, including preload on request. With NGINX Plus, the new oidcNative Policy runs OpenID Connect in the built-in module and attaches to an Ingress through nginx.com/policies.
For Traefik users: traefik.ingress.kubernetes.io/service.passhostheader: "false" maps to nginx.org/upstream-vhost on an Ingress. The errors middleware maps to nginx.org/custom-http-errors, which proxies the error page and keeps the status, as Traefik does.
In NGINX Ingress Controller: A new externalAuth Policy CRD sends each request to an external authentication service first. The egressMTLS, externalAuth, and ingressMTLS Policies attach directly to an Ingress, and so does waf (NGINX Plus, through nginx.com/policies). nginx.org/add-header (with nginx.org/add-header-inherit) adds response headers inline, and nginx.org/proxy-redirect-from / nginx.org/proxy-redirect-to rewrite the Location header.
For Traefik users: The externalAuth Policy replaces the forwardAuth middleware. A TLSOption's clientAuth and a ServersTransport map to Policies an Ingress can reference, so they need no VirtualServer.
In NGINX Ingress Controller: The accessControl and cors Policy CRDs attach directly to an Ingress through nginx.org/policies, with no VirtualServer.
For Traefik users: The ipAllowList middleware and a headers middleware's CORS fields map to Policies an Ingress can reference. Look for the (Recommended) tab in the mapping examples.
NGINX mappings
These features are available in both NGINX Open Source and NGINX Plus editions. Most Traefik rows are Middleware or IngressRoute fields, and the rest are annotations; a badge marks what each maps to (e.g. ConfigMap, Policy CRD, VirtualServer CRD). Traefik annotations use the traefik.ingress.kubernetes.io/ prefix; NGINX Ingress Controller annotations use nginx.org/.
- Middleware and annotation rows ▶: Direct mappings from a Traefik Middleware field or annotation to its NGINX Ingress Controller equivalent. Click to expand and see before/after YAML examples.
- CRD-based rows ▶: Rows that map to a CRD (VirtualServer, Policy, or TransportServer). Click to expand for full CRD examples with installation instructions.
- Grouped rows: Related settings that work together are grouped in a single expandable row, showing how they map to a unified configuration.
- NGINX Ingress Controller-only rows: Rows marked No direct equivalent on the left are features unique to NGINX Ingress Controller with no Traefik equivalent.
Access control
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware ipAllowList( sourceRange, ipStrategy, rejectStatusCode) |
Policy CRD accessControl + VirtualServer CRD policies[]— or —Policy CRD accessControl + nginx.org/policies New v5.4.0 |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerTrust only the proxy in front:
ipStrategy reads the client address from X-Forwarded-For. NGINX Ingress Controller does that globally (real-ip-header, set-real-ip-from), and only for connections from the addresses in set-real-ip-from: set it to the load balancer or proxy in front. Never set it to 0.0.0.0/0, or any client can write its own address into the header and pass the allow list.Note:
depth: 1 takes the rightmost address in X-Forwarded-For, as real-ip-recursive: "False" does; excludedIPs takes the rightmost address not listed, as real-ip-recursive: "True" does with those ranges in set-real-ip-from. A depth of 2 or more has no exact form: list the proxies between in set-real-ip-from and set real-ip-recursive to True. Several allow lists on one route admit only addresses in all of them, so they become one Policy named for the route. The accessControl Policy answers 403; rejectStatusCode has no equivalent. The deprecated ipWhiteList migrates the same way. | |
Middleware passTLSClientCert( pem, info) |
VirtualServer CRD action.proxy.requestHeaders.set + Policy CRD ingressMTLS |
Traefik ProxyNGINX Ingress ControllerNote: a client certificate exists only where the host asks for one: in Traefik a TLSOption with
clientAuth, in NGINX Ingress Controller the ingressMTLS Policy that TLSOption becomes, so paste both. The headers differ in form. pem: Traefik sends every certificate the client presented as bare base64, comma-separated; ${ssl_client_escaped_cert} is the client certificate alone, as URL-encoded PEM. info: Traefik builds the fields it lists, URL-encoded; NGINX has the whole subject and issuer DNs, in RFC 2253 order. A backend that parses these headers needs to accept NGINX's form. serialNumber, notBefore and notAfter are ${ssl_client_serial} (in hexadecimal; Traefik writes decimal), ${ssl_client_v_start} and ${ssl_client_v_end} (dates; Traefik writes Unix seconds), which can be added as headers; NGINX has no variable for the SANs. | |
Authentication
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware basicAuth |
Policy CRD basicAuth— or —nginx.org/basic-auth-realmnginx.org/basic-auth-secret |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerSecret must be converted: Traefik reads htpasswd lines from an
Opaque Secret under the key users; the NGINX Ingress Controller requires the Secret to have type: nginx.org/htpasswd with the htpasswd file under the key htpasswd. The file contents stay the same — re-create the Secret with the new type and key, in the same namespace as the Policy.Note: The
basicAuth Policy is not Ingress-attachable via nginx.org/policies — reference it from VirtualServer or VirtualServerRoute policies[]. On Ingress resources use the nginx.org/basic-auth-realm and nginx.org/basic-auth-secret annotations instead (see the Annotation Approach). Only the first basicAuth Policy reference is applied; subsequent references are ignored. headerField and removeHeader have no equivalent — the authenticated user is not forwarded to the backend and the Authorization header passes through unchanged. | |
Middleware forwardAuth |
Policy CRD externalAuth New v5.5.0 |
Traefik ProxyNGINX Ingress ControllerService-only target:
authServiceName must reference a Kubernetes Service (optionally namespace/service) — the NGINX Ingress Controller cannot send auth sub-requests to arbitrary external URLs. If your address points outside the cluster, front it with an in-cluster Service first. Related fields: authServicePorts defaults to the Service's first port, and sniName (default service.namespace.svc) can override the TLS server name when sslVerify is on.Behavior differences: All client request headers are always forwarded to the auth service —
authRequestHeaders has no equivalent (restrict headers only via authSnippets). The request body is never forwarded — forwardBody/maxBodySize have no equivalent. Auth-server response headers are not copied to the backend request — replicate authResponseHeaders/authResponseHeadersRegex with authSnippets (auth_request_set). addAuthCookiesToResponse has no equivalent — the controller does not copy the auth server's Set-Cookie headers onto the client response; surface auth-server session cookies via authSnippets (auth_request_set $sc $upstream_http_set_cookie; … add_header Set-Cookie $sc;), or use NGINX Ingress Controller's oauth2-proxy sign-in flow via authSigninURI/authSigninRedirectBasePath. tls.insecureSkipVerify maps directly to externalAuth.sslVerify: false; trustForwardHeader, headerField, and tls.certSecret (the controller never presents a client certificate to the auth server) have no equivalent, and preserveLocationHeader, preserveRequestMethod, and maxResponseBodySize likewise have no direct equivalent. authSnippets requires the controller to run with -enable-snippets. | |
Middleware digestAuth |
No direct equivalent (use basicAuth) |
Traefik ProxyNGINX Ingress ControllerNGINX has no digest-auth module, so NGINX Ingress Controller cannot terminate HTTP Digest authentication. Re-issue the credentials in htpasswd format ( htpasswd -c users.htpasswd <user>), store them in a Secret of type nginx.org/htpasswd under the key htpasswd, and reference it from a basicAuth Policy. | |
Backend transport
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
ServersTransport |
Policy CRD egressMTLS + VirtualServer CRD upstreams[] |
Traefik ProxyNGINX Ingress ControllerVerification polarity:
verifyServer defaults to false in NGINX Ingress Controller — Traefik's insecureSkipVerify: true is already the default polarity. When the ServersTransport set rootCAs/rootCAsSecrets, add verifyServer: true explicitly or upstream certificates will not be checked. ConfigMap-sourced rootCAs entries are not supported — re-create the CA bundle as a Secret of type nginx.org/ca (key ca.crt). read-timeout is the closest match for responseHeaderTimeout: NGINX times successive reads from the upstream, not just the response headers.Note: the Policy can also be attached to an Ingress via
nginx.org/policies (v5.5.0+). egressMTLS only ever sets proxy_ssl_* directives — it never switches the upstream to HTTPS on either path, so set the upstream scheme separately: on VirtualServer add upstreams[].tls.enable: true (shown above), and on Ingress use nginx.org/ssl-services. No equivalent exists for forwardingTimeouts.idleConnTimeout/readIdleTimeout/pingTimeout, disableHTTP2 (NGINX proxies backends over HTTP/1.1, gRPC excepted), peerCertURI, or spiffe (NGINX Ingress Controller's SPIFFE integration was NGINX Plus + NGINX Service Mesh only, and has been discontinued). | |
ServersTransportTCP( dialTimeout, proxyProtocol) |
TransportServer CRD upstreamParameters.connectTimeout + serverSnippets (proxy_protocol) |
Traefik ProxyNGINX Ingress ControllerNo backend TLS: a TransportServer has no field for
tls (serverName, rootCAs, certificatesSecrets). The stream proxy_ssl_* directives exist, but serverSnippets can name certificates only as files in the NGINX Ingress Controller pod, not as Secrets. dialKeepAlive and terminationDelay have no TransportServer field either. serverSnippets requires -enable-snippets. | |
Buffering & body size
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware buffering (maxRequestBodyBytes, maxResponseBodyBytes, memRequestBodyBytes, memResponseBodyBytes, retryExpression) |
VirtualServer CRD upstreams[].client-body-buffer-size + upstreams[].client-max-body-size— or —nginx.org/client-max-body-size |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: Convert byte counts to NGINX size strings (for example,
10485760 → 10m). The in-memory buffer size (memRequestBodyBytes) maps to the VirtualServer upstreams[].client-body-buffer-size field — see the CRD Approach tab.Note: The response-side caps (
maxResponseBodyBytes, memResponseBodyBytes) have no equivalent hard limit — NGINX does not enforce a maximum response body size. Tune response buffering with nginx.org/proxy-buffering, nginx.org/proxy-buffers, and nginx.org/proxy-buffer-size instead. retryExpression retries while it holds: IsNetworkError() is a 502 or 504 from the last try (Traefik's own answer to a connection failure or timeout, or the backend's), which next-upstream: "error timeout http_502 http_504" covers, and Attempts() < N counts the first try, as next-upstream-tries does. Other expressions (ResponseCode(), RequestMethod(), ||) are set by hand. | |
Compression
gzip directives in the ConfigMap http-snippets key. It applies globally to all traffic, not per-route like a Traefik middleware.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware compress( defaultEncoding, encodings, excludedContentTypes, includedContentTypes, minResponseBodyBytes) |
VirtualServer CRD routes[].location-snippets (gzip)— or —nginx.org/location-snippets |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: NGINX Ingress Controller has no compression field, so gzip goes in the location snippets of the routes that used the middleware, which keeps Traefik's per-router scope (snippets need
-enable-snippets). With no includedContentTypes, Traefik compresses every type but application/grpc: gzip_types *. minResponseBodyBytes defaults to 1024, as gzip_min_length is set here. gzip_types lists what to compress, so excludedContentTypes has no direct form: list the types to compress instead. Brotli (br) and zstd need NGINX modules the image does not ship, so clients that ask for them get gzip. | |
CORS & headers
headers middleware. The NGINX Ingress Controller splits these across different constructs, so the table below maps each facet of the middleware separately.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
headers(CORS: accessControlAllowCredentials, accessControlAllowHeaders, accessControlAllowMethods, accessControlAllowOriginList, accessControlExposeHeaders, accessControlMaxAge) |
Policy CRD cors + VirtualServer CRD policies[]— or —Policy CRD cors + nginx.org/policies New v5.4.0 |
Traefik ProxyNGINX Ingress ControllerNote:
allowOrigin is required. accessControlAllowOriginListRegex has no cors Policy equivalent — list the allowed origins explicitly in allowOrigin. addVaryHeader also has no cors Policy equivalent — the NGINX Ingress Controller CORS struct exposes no Vary toggle, so this Traefik option is intentionally unmapped. When allowCredentials is true, a wildcard "*" origin is rejected per the CORS specification.Traefik ProxyNGINX Ingress ControllerNew in v5.4.0: CORS Policies can be referenced directly from Ingress resources using the
nginx.org/policies annotation, so you can migrate the middleware without leaving Ingress resources. | |
headers( customRequestHeaders) |
VirtualServer CRD action.proxy.requestHeaders.set— or —nginx.org/proxy-set-headers |
Traefik ProxyNGINX Ingress ControllerNote: To override the
Host header sent upstream (Traefik's customRequestHeaders can set it), use requestHeaders.set on the VirtualServer — the nginx.org/proxy-set-headers annotation cannot reliably override Host because the generated config emits proxy_set_header Host $host after it.Traefik ProxyNGINX Ingress ControllerNote: Explicit values in
nginx.org/proxy-set-headers may not contain $. Use the VirtualServer approach for values that need variables, for header removal, or for Host overrides. | |
headers( customResponseHeaders) |
VirtualServer CRD action.proxy.responseHeaders.add— or —nginx.org/add-header New v5.5.0 |
Traefik ProxyNGINX Ingress ControllerNote: Set
always: true so the header is also added to error responses, matching Traefik behavior. An empty customResponseHeaders value (header removal) maps to responseHeaders.hide.Traefik ProxyNGINX Ingress ControllerNew in v5.5.0: the
nginx.org/add-header annotation (and matching ConfigMap key). Values may not contain $, newlines, or unescaped double quotes; append : always to a pair to add the header on all response codes. Header removal has no annotation form — use responseHeaders.hide on a VirtualServer. | |
headers(security: browserXssFilter, contentSecurityPolicy, contentSecurityPolicyReportOnly, contentTypeNosniff, customBrowserXSSValue, customFrameOptionsValue, frameDeny, permissionsPolicy, referrerPolicy) |
VirtualServer CRD action.proxy.responseHeaders.add— or —nginx.org/add-header New v5.5.0 |
Traefik ProxyNGINX Ingress ControllerNote: Traefik builds these response headers from dedicated toggles; the NGINX Ingress Controller has no per-header toggles — you emit the literal header name and value yourself.
nginx.org/add-header is new in v5.5.0; values may not contain $, newlines, or unescaped double quotes, and comma-containing values (such as multi-directive Permissions-Policy) break the comma-separated list — use the CRD approach for those. browserXssFilter/customBrowserXSSValue emit X-XSS-Protection, which is deprecated and ignored by modern browsers; contentSecurityPolicyReportOnly emits the report-only Content-Security-Policy-Report-Only header.Traefik ProxyNGINX Ingress Controller | |
headers( stsIncludeSubdomains, stsPreload, stsSeconds) |
VirtualServer CRD action.proxy.responseHeaders.add— or —nginx.org/hsts + nginx.org/hsts-max-age + nginx.org/hsts-include-subdomains |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress Controllernginx.org/hsts always adds preload: NGINX Ingress Controller writes
preload into the header whenever nginx.org/hsts is on, which asks browsers to put the domain on their preload lists. It fits a middleware with stsPreload: true. Without it, the analyzer writes the header as Traefik sent it with nginx.org/add-header (Strict-Transport-Security: max-age=…; includeSubDomains: always) instead.Note: Traefik sends the header over TLS only and only when
stsSeconds is not 0; stsSeconds: 0 sends nothing. responseHeaders.add and add-header also send it over plain HTTP, which browsers ignore (RFC 6797). nginx.org/hsts sends it only over TLS, or behind a TLS-terminating proxy with nginx.org/hsts-behind-proxy. A parse error in any of the HSTS annotations skips all of them. | |
Error handling
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware errors( query, service, status, statusRewrites) |
nginx.org/custom-http-errors New v5.6.0 + spec.defaultBackend— or —VirtualServer CRD routes[].errorPages[] |
Traefik ProxyNGINX Ingress ControllerNew in v5.6.0:
nginx.org/custom-http-errors sends the listed codes to the Ingress's spec.defaultBackend, which answers with the error page and the original status, as Traefik's errors service did. Codes are 300 to 599 (not 499), and ranges are listed out. A VirtualServer has no such field, so the analyzer keeps this Ingress an Ingress under CRD-first.Traefik ProxyNGINX Ingress ControllerNote: a VirtualServer
errorPages entry redirects or returns; it cannot proxy. Where a pasted route serves the error Service, each code redirects (302) to its page there, {status} filled in per code; the client follows the redirect and gets a 200, not the original status.Note: Traefik rewrites the path to
query (/{status}.html) when it calls the error service; custom-http-errors sends the original path, so the error service has to pick the page another way (NGINX passes the status in the response, not the request). statusRewrites has no equivalent: NGINX keeps the original status. | |
Ingress annotations
traefik.ingress.kubernetes.io/ annotations configure Traefik routers and services on standard Ingress resources. To stay on Ingress during the migration, swap each one for its nginx.org/ equivalent below and change ingressClassName from traefik to nginx. Middlewares referenced from these annotations are converted per-type — see their rows elsewhere in this guide.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
traefik.ingress.kubernetes.io/router.entrypoints |
GlobalConfiguration CRD listeners + VirtualServer CRD spec.listener— or —nginx.org/listen-ports / nginx.org/listen-ports-ssl |
Traefik ProxyNGINX Ingress ControllerNote:
web/websecure map to the NGINX Ingress Controller's default ports 80/443 — if those are the only entryPoints in play, simply remove the annotation. On mergeable Ingress, listen-ports belongs on the master (not minions); host-less Ingress resources use the -default-http-listener-port / -default-https-listener-port flags instead.Traefik ProxyNGINX Ingress ControllerNote: The controller loads a single GlobalConfiguration, referenced by the
-global-configuration <namespace>/<name> flag. HTTP listeners are consumed by VirtualServer spec.listener.http/spec.listener.https; TCP/UDP listeners by TransportServer. | |
traefik.ingress.kubernetes.io/router.middlewarestraefik.ingress.kubernetes.io/service.middlewares |
nginx.org/policies New v5.4.0— or —VirtualServer CRD policies[] |
Traefik ProxyNGINX Ingress ControllerNote: Convert each referenced Middleware first — see its row in this guide. Only some Policy types attach to Ingress via
nginx.org/policies (requires -enable-custom-resources): accessControl and cors (v5.4.0+); egressMTLS, externalAuth, and ingressMTLS (v5.5.0+). basicAuth and rateLimit are not Ingress-attachable — on Ingress use the nginx.org/basic-auth-* and nginx.org/limit-req-* annotations instead.Traefik ProxyNGINX Ingress ControllerNote: Every Policy type attaches to VirtualServer
policies[] (spec or per-route). Traefik chains middlewares in annotation order; NGINX applies each policy type at its own place in the request phases, so review interactions after flattening a chain. | |
traefik.ingress.kubernetes.io/router.observability.*( accesslogs, metrics, traceVerbosity, tracing) |
ConfigMap access-log-off / otel-trace-in-http; Controller flag -enable-prometheus-metrics |
Traefik ProxyNGINX Ingress ControllerEvery observability control is global in NGINX Ingress Controller, so turning one on or off affects every route, not just this router. accesslogs: "false" becomes the ConfigMap key access-log-off: "true"; tracing: "true" becomes otel-trace-in-http: "true" with otel-exporter-endpoint and otel-service-name; metrics becomes the -enable-prometheus-metrics flag (controller-wide /metrics on port 9113); traceVerbosity has no equivalent. See Observability for the examples. | |
traefik.ingress.kubernetes.io/router.pathmatcher |
VirtualServer CRD routes[].path |
Traefik ProxyNGINX Ingress ControllerNote: The matcher choice moves from a router-wide annotation to per-route path syntax:
Path → =/exact, PathPrefix → /prefix, PathRegexp → ~regex (~* for case-insensitive). NGINX regexes are PCRE while Traefik uses Go/RE2 — most patterns port unchanged, but lookarounds and some syntax details differ. | |
traefik.ingress.kubernetes.io/router.rulesyntax |
Not applicable |
Traefik ProxyNGINX Ingress ControllerRule syntax is a deprecated, Traefik-only toggle. Convert v2-only matchers to their v3 forms first ( Headers to Header, HeadersRegexp to HeaderRegexp, HostHeader to Host), then map the v3 rule to VirtualServer host, routes and matches (see Routing (IngressRoute)). | |
traefik.ingress.kubernetes.io/router.tls |
VirtualServer CRD spec.tls.secret— or —Ingress spec.tls[].secretName |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote:
router.tls makes the router HTTPS-only: Traefik answers plain HTTP for that host with 404. NGINX Ingress Controller derives TLS from spec.tls with no annotation, and by default answers plain HTTP too: a VirtualServer serves it unless spec.tls.redirect is enabled, and an Ingress redirects it to HTTPS (nginx.org/ssl-redirect defaults to true). | |
traefik.ingress.kubernetes.io/router.tls.certresolvertraefik.ingress.kubernetes.io/router.tls.domains.n.main / .sans |
cert-manager + VirtualServer CRD spec.tls.cert-manager.cluster-issuer |
Traefik ProxyNGINX Ingress ControllerNote: Traefik's ACME certificates live in
acme.json (a file, not Kubernetes Secrets) and cannot be reused — re-issue them through cert-manager before cutover. A VirtualServer serves a single host and spec.tls.cert-manager has no SAN field — extra names from router.tls.domains.n.sans must be split into per-host VirtualServers or handled in your cert-manager configuration. For HTTP-01 challenges on an HTTPS-only setup, add tls.cert-manager.issue-temp-cert: "true". See TLS & certificates for TLSOption and TLSStore conversions. | |
traefik.ingress.kubernetes.io/router.tls.options |
ConfigMap ssl-ciphers / ssl-protocols |
Traefik ProxyNGINX Ingress ControllerNote: The referenced TLSOption converts field by field:
cipherSuites and minVersion/maxVersion become the global ssl-ciphers/ssl-protocols ConfigMap keys (every host, not per router), while clientAuth becomes a per-application ingressMTLS Policy. See TLS & certificates for each TLSOption field's row. | |
traefik.ingress.kubernetes.io/service.nativelb (on the Service) |
VirtualServer CRD upstreams[].use-cluster-ip— or —nginx.org/use-cluster-ip |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: With
use-cluster-ip, kube-proxy distributes the traffic, so lb-method and next-upstream settings become no-ops. The annotation is not allowed on the master of a mergeable Ingress. | |
traefik.ingress.kubernetes.io/service.passhostheader |
VirtualServer CRD action.proxy.requestHeaders.set— or —nginx.org/upstream-vhost New v5.6.0 |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNew in v5.6.0:
nginx.org/upstream-vhost sets the Host header sent to the backend, for every path of the Ingress. Where only some paths' Services set passhostheader: "false", the VirtualServer sets it per route.Note: NGINX Ingress Controller sends
Host: $host by default, as passHostHeader: true does, so "true" needs nothing. With "false", Traefik sent the backend's own address; the Service's cluster name is the nearest stable name for it. | |
traefik.ingress.kubernetes.io/service.serversscheme (on the Service) |
VirtualServer CRD upstreams[].tls / proxy-http-version— or —nginx.org/ssl-services / nginx.org/proxy-http-version New v5.7.0 |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: Traefik reads
service.* annotations from the Service a path routes to; on the Ingress they do nothing. h2c is plaintext HTTP/2 with prior knowledge, which NGINX speaks to any backend with proxy-http-version: "2"; a gRPC backend can use upstreams[].type: grpc (or nginx.org/grpc-services) for gRPC error handling as well. serversscheme: http is the default and needs nothing. | |
traefik.ingress.kubernetes.io/service.serverstransport |
Policy CRD egressMTLS + VirtualServer CRD upstreams[] |
Traefik ProxyNGINX Ingress ControllerConvert the referenced ServersTransport once. Its TLS fields ( certificatesSecrets, rootCAs, serverName) become an egressMTLS Policy; maxIdleConnsPerHost and forwardingTimeouts become VirtualServer upstreams[] keepalive and timeout fields. To stay on an Ingress, attach the egressMTLS Policy with nginx.org/policies (v5.5.0 and later) and pair it with nginx.org/ssl-services to switch the upstream to HTTPS; the timeout and keepalive half still needs VirtualServer upstream fields. See Backend transport for the full conversion. | |
traefik.ingress.kubernetes.io/service.sticky.cookie(+ .domain, .httponly, .maxage, .name, .path, .samesite, .secure) |
VirtualServer CRD upstreams[].sessionCookie New v5.4.0 |
Traefik ProxyNGINX Ingress ControllerNote: See Session affinity for the full field-by-field map, including
.maxage (seconds) → expires (NGINX time) and the lowercase samesite values. | |
| Several Ingresses on one host | VirtualServer CRD spec.routes[]— or —Ingress spec.rules[].http.paths[] |
Traefik ProxyNGINX Ingress ControllerNote: Each Ingress keeps its own upstreams, so the body-size limit above stays with
api, as its middleware did in Traefik, and its Policies go on its own routes. Traefik tries the longest rule first by default, so /api beats / there as NGINX's longest prefix does here.Traefik ProxyNGINX Ingress ControllerSettings become host-wide: In one Ingress, only the per-Service annotations (
nginx.org/ssl-services, nginx.org/grpc-services, nginx.org/websocket-services, nginx.org/rewrites, nginx.org/sticky-cookie-services) stay with the Service they name. Every other setting covers every path, so the body-size limit above, set only on api, applies to web too, where Traefik kept it to api's paths. The analyzer names each setting that changes scope. To keep them per Ingress, use the VirtualServer approach, where each Ingress keeps its own upstreams.One host, one resource: Traefik makes a router of every Ingress rule and applies each router's middlewares to its own paths only. NGINX Ingress Controller gives a host to one resource and rejects a second that claims it, so the analyzer merges the Ingresses of a host into one; IngressRoutes on one host, and an Ingress sharing a host with one, become one VirtualServer the same way. An Ingress that routes several hosts is split into one per host first.
A resource per team: NGINX Ingress Controller can also delegate a host's paths to VirtualServerRoutes, or to mergeable minion Ingresses under a master, and NGINX Gateway Fabric attaches several HTTPRoutes to one Gateway listener. Each gives a team a resource of its own, and each needs setting up with the result in mind. The analyzer does not emit them.
| |
traefik.ingress.kubernetes.io/router.priority |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX location precedence is fixed: an exact match ( =) first, then regex routes in the order they are listed, then the longest matching prefix. Reorder VirtualServer regex routes to change which one matches; exact and prefix routes need no priority. | |
traefik.ingress.kubernetes.io/service.nodeportlb |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX Ingress Controller load-balances pod endpoints directly, or the Service ClusterIP when nginx.org/use-cluster-ip is set, never NodePorts. Remove the annotation: endpoint load balancing is the default. | |
Miscellaneous
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware chain |
Policy CRD VirtualServer CRD policies[]— or —nginx.org/policies New v5.4.0 |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote:
nginx.org/policies requires the -enable-custom-resources flag. Only some Policy types attach to Ingress resources: accessControl and cors since v5.4.0; egressMTLS, externalAuth, and ingressMTLS since v5.5.0. Policy types that are not Ingress-attachable (such as basicAuth and rateLimit) use their annotation equivalents (nginx.org/basic-auth-secret, nginx.org/limit-req-rate) on the same Ingress instead.Note: NGINX Ingress Controller has no chain construct — there is nothing to convert the
chain Middleware itself into. Convert each chained Middleware using its own row in this guide, then list the results on one resource; the order of the flattened list is preserved. | |
Middleware contentType |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX proxies the upstream Content-Type header untouched and has no per-route control over Content-Type detection, which this middleware sets in Traefik's Go proxy. If the backend omits Content-Type, set it in the application. | |
Middleware encodedCharacters |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX URI normalization is fixed, so per-route allowances for encoded characters ( %2F, %3B and others) cannot be configured. | |
Middleware grpcWeb |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX Ingress Controller has no gRPC-Web to gRPC translation; nginx.org/grpc-services proxies native gRPC only. Keep a gRPC-Web proxy sidecar in front of the backend, or serve gRPC-Web from the application. | |
Observability
router.observability.* annotations toggle access logs, metrics, and tracing per router. In the NGINX Ingress Controller these are all global settings — access logging and OpenTelemetry tracing are ConfigMap keys that apply to every route, and Prometheus metrics are enabled with a controller CLI flag. There are no per-route observability toggles.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
traefik.ingress.kubernetes.io/router.observability.accesslogs |
ConfigMap access-log-off |
Traefik ProxyNGINX Ingress ControllerNote: The NGINX Ingress Controller has no per-route access-log toggle. Access logging is on by default (the
access-log ConfigMap key defaults to /dev/stdout main), so if the annotation value is "true", simply remove it — no replacement is needed. Only "false" translates to the global access-log-off: "true", which silences access logs for every route, not just this one. | |
traefik.ingress.kubernetes.io/router.observability.tracing |
ConfigMap otel-exporter-endpoint + otel-service-name + otel-trace-in-http + otel-trace-context New v5.7.0 |
Traefik ProxyNGINX Ingress ControllerNote: OpenTelemetry tracing is global in the NGINX Ingress Controller —
otel-trace-in-http: "true" traces every route, not just this router. Traefik continues an incoming trace and passes it on; otel-trace-context: propagate keeps that, where NGINX Ingress Controller would otherwise ignore the trace headers. The v5.7.0 ConfigMap has six otel-* keys: otel-exporter-endpoint, otel-exporter-header-name, otel-exporter-header-value, otel-service-name, otel-trace-context, and otel-trace-in-http (the header keys require the endpoint and each other). The exporter endpoint is OTLP/gRPC — Traefik's OTLP/HTTP exporter option has no equivalent. For per-route tracing, leave otel-trace-in-http unset (default false) and enable tracing in snippets on the routes that need it — note that resource snippets (annotations, VirtualServer) require the -enable-snippets flag, while ConfigMap snippet keys are always available. | |
traefik.ingress.kubernetes.io/router.observability.metrics |
No direct equivalent (metrics are controller-global) |
Traefik ProxyNGINX Ingress ControllerNote: The NGINX Ingress Controller exposes Prometheus metrics for the whole controller on
/metrics (port 9113 by default) once -enable-prometheus-metrics is set — individual routers cannot opt in or out. Remove this annotation during migration and filter by label in Prometheus instead if you need per-app views. | |
traefik.ingress.kubernetes.io/router.observability.traceverbosity |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX Ingress Controller has no trace-verbosity setting: the NGINX OpenTelemetry module fixes the span content, and tracing itself is global (the otel-* ConfigMap keys in the row above). Remove the annotation. | |
Rate limiting & concurrency
rateLimit middleware to any router; in the NGINX Ingress Controller the rateLimit Policy attaches via VirtualServer spec.policies only — it is not Ingress-attachable through nginx.org/policies. On Ingress resources, use the nginx.org/limit-req-burst + nginx.org/limit-req-rate annotations instead.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware inFlightReq( amount, sourceCriterion) |
VirtualServer CRD routes[].location-snippets (limit_conn) + ConfigMap http-snippets (limit_conn_zone)— or —nginx.org/location-snippets |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: There is no Policy for concurrent-request limiting, so it is
limit_conn in the route's location snippets (-enable-snippets) with its zone in the ConfigMap http-snippets key, which is always available. Traefik's inFlightReq counts per Host by default (its default sourceCriterion is requestHost, unlike rateLimit), so the zone is keyed on $host; requestHeaderName keys it on that header, and ipStrategy on the client address. Traefik answers 429 and limit_conn 503, hence limit_conn_status 429. With amount 0 or unset, Traefik refuses every request, and the route answers 429. | |
Middleware rateLimit( average, burst, period, redis, sourceCriterion) |
Policy CRD rateLimit + VirtualServer CRD policies[]— or —nginx.org/limit-req-* |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote:
rate is average over period (100 per 1s is 100r/s, 100 per 1m 100r/m). Traefik's bucket admits burst requests at once; NGINX admits burst + 1 (checked on NGINX 1.31.7), so burst is Traefik's less one, with noDelay so they pass at once, and is left out at 0. sourceCriterion.requestHeaderName keys the limit on that header and requestHost on ${http_host}; the default is the client address. Traefik answers 429, NGINX 503 unless rejectCode says otherwise. Redis-backed limiting counts across replicas; NGINX Ingress Controller counts per replica unless NGINX Plus zone synchronization shares the zone. | |
Redirects
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware redirectRegex( permanent, regex, replacement) |
VirtualServer CRD routes[].location-snippets— or —nginx.org/location-snippets |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: Traefik matches the regex against the whole URL,
scheme://host and the path with its query string, replaces what matches and keeps the rest, and leaves a URL the regex misses alone. NGINX can do the same in the route's location: build that URL in a variable, match it with if, and return the replacement, ${1} becoming $1 (checked on NGINX 1.31.7). A regex that matches only part of the URL is wrapped to keep what precedes and follows the match. A VirtualServer action.redirect is not a substitute: it takes a fixed URL and redirects every request on the route. Traefik answers 301 (permanent) or 302 to GET and 308 or 307 to other methods; NGINX takes one code, so 308 or 307, which keep the method. Snippets need -enable-snippets; Traefik's regex is RE2 and NGINX's PCRE, which agree on the common syntax. | |
Middleware redirectScheme( permanent, port, scheme) |
VirtualServer CRD tls.redirect— or —nginx.org/http-redirect-code |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: in Traefik the redirect sits on a plain-HTTP router, beside the HTTPS router that serves the app; in NGINX Ingress Controller one resource does both.
tls.redirect redirects plain HTTP for the whole host. An Ingress with TLS already redirects plain HTTP (nginx.org/ssl-redirect, on by default), as Traefik did when the connection was not TLS; nginx.org/http-redirect-code sets the code. nginx.org/redirect-to-https is for TLS that ends in front of NGINX Ingress Controller: it redirects on X-Forwarded-Proto, which a client talking to NGINX directly never sends.Note: Traefik picks the redirect status by request method:
permanent: true returns 301 for GET but 308 for other methods, and permanent: false returns 302 for GET but 307 for other methods — so the method is preserved on non-GET requests. NGINX Ingress Controller emits one static code, so choose the method-preserving one: 308 for permanent: true (a static 301 — the NGINX Ingress Controller default — can make clients replay a non-GET request as GET) and 307 for permanent: false (or 302 if the route only serves GET). Both NGINX Ingress Controller paths cover scheme: https only, and neither the annotations nor spec.tls.redirect exposes a field for redirectScheme.port — a non-standard target port has no direct equivalent. | |
Resilience
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware circuitBreaker (checkPeriod, expression, fallbackDuration, recoveryDuration, responseCode) |
VirtualServer CRD upstreams[].fail-timeout + upstreams[].max-fails |
Traefik ProxyNGINX Ingress ControllerNote: this is a passive approximation, not a translation. Traefik evaluates the
expression every checkPeriod and probes recovery over recoveryDuration; NGINX passive health checks instead mark an upstream server unavailable for fail-timeout after max-fails failed proxy attempts within that same window — there is no equivalent for the expression language, checkPeriod, recoveryDuration, or the open-state responseCode (default 503; NGINX passive health checks have no notion of an open-state response code). The true analogue — active health checks via upstreams[].healthCheck — requires NGINX Plus: see NGINX Plus mappings. | |
Middleware retry |
VirtualServer CRD upstreams[].next-upstream + upstreams[].next-upstream-tries— or —nginx.org/proxy-next-upstream + nginx.org/proxy-next-upstream-tries New v5.4.0 |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNew in v5.4.0: the
nginx.org/proxy-next-upstream and nginx.org/proxy-next-upstream-tries annotations let you configure retries directly on Ingress resources without moving to VirtualServer.Note: By default Traefik's
retry retries only when the backend fails to respond and stops as soon as it answers, regardless of status — so a plain retry maps to next-upstream: "error timeout" (network errors only) with next-upstream-tries ← attempts. initialInterval (exponential backoff) has no equivalent — NGINX retries immediately. Traefik v3's retry also has status (HTTP codes to retry on, e.g. 500-599), disableRetryOnNetworkError, retryNonIdempotentMethod, timeout, and maxRequestBodyBytes: when status is set, add the matching tokens NGINX supports (only http_403 http_404 http_429 http_500 http_502 http_503 http_504) to next-upstream; disableRetryOnNetworkError: true → drop error timeout; retryNonIdempotentMethod: true → add non_idempotent; timeout → next-upstream-timeout. | |
IngressRoute services[].passiveHealthCheck( failureWindow, maxFailedAttempts) |
VirtualServer CRD upstreams[].max-fails + upstreams[].fail-timeout |
Traefik ProxyNGINX Ingress ControllerNote: Traefik's passive check is NGINX's own: a server that fails
maxFailedAttempts times within failureWindow is taken out for that window, and the defaults match (1 failure in 10s). NGINX counts a connection error or timeout as a failure; Traefik also counts a 5xx response. To count those too, add next-upstream: "error timeout http_500 http_502 http_503 http_504". On an Ingress, the same fields are nginx.org/max-fails and nginx.org/fail-timeout. | |
Rewrites
action.proxy.rewritePath supports $1–$9 captures only when the route path is a regex (starts with ~). Traefik regexes are Go/RE2 while NGINX uses PCRE — most patterns port unchanged, but verify anything using lookarounds or RE2-specific syntax.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware addPrefix( prefix) |
VirtualServer CRD path + action.proxy.rewritePath |
Traefik ProxyNGINX Ingress ControllerNote: Traefik prepends the prefix to the path as it is, with no slash between (
/api + /users = /api/users); the regex captures the whole path, slash included, so rewritePath joins them the same way. | |
Middleware replacePath( path) |
VirtualServer CRD action.proxy.rewritePath— or —nginx.org/path-regex + nginx.org/rewrite-target |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: Traefik replaces the whole path and keeps the query string, as
rewritePath and rewrite-target do. On an Ingress, nginx.org/path-regex turns every path of the Ingress into a regex location (/status$ is the exact path), and nginx.org/rewrite-target applies to all of them; an Ingress whose paths rewrite differently needs the VirtualServer.X-Replaced-Path: Traefik also sends the original path to the backend in
X-Replaced-Path; NGINX Ingress Controller does not. If the backend reads it, set it with action.proxy.requestHeaders.set (value: ${request_uri}). | |
Middleware replacePathRegex( regex, replacement) |
VirtualServer CRD regex path + action.proxy.rewritePath |
Traefik ProxyNGINX Ingress ControllerNote: Traefik replaces what the regex matches and keeps the rest of the path; a path the regex misses goes through unchanged, so the route's plain path stays as a second route, and NGINX tries the regex first. A regex that matches only part of the path is wrapped to capture what precedes and follows it:
/v1/ → /v2/ becomes ~ ^(.*?)(?:/v1/)(.*)$ with rewritePath: $1/v2/$2. Traefik replaces every match; the route replaces the first. Its regex is RE2 and NGINX's PCRE, which agree on the common syntax. An Ingress cannot keep the unmatched paths unchanged once nginx.org/path-regex is set, so this rewrite needs the VirtualServer.X-Replaced-Path: Traefik also sends the original path to the backend in
X-Replaced-Path; NGINX Ingress Controller does not. If the backend reads it, set it with action.proxy.requestHeaders.set (value: ${request_uri}). | |
Middleware stripPrefix( prefixes) |
VirtualServer CRD regex path + action.proxy.rewritePath— or —nginx.org/path-regex + nginx.org/rewrite-target |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: Traefik cuts the prefix as plain text, so
/api turns /api/x into /x and also /apix into /x; ^/api/?(.*)$ with /$1 does exactly that, and adds back the leading slash Traefik restores. Each prefix the route matches gets its own route. nginx.org/rewrites is not a substitute: on the path /api it sends /api/x as //x.X-Forwarded-Prefix: Traefik also sends the stripped prefix to the backend in
X-Forwarded-Prefix; NGINX Ingress Controller does not. If the backend builds URLs from it, set it with action.proxy.requestHeaders.set. | |
Middleware stripPrefixRegex( regex) |
VirtualServer CRD regex path + action.proxy.rewritePath |
Traefik ProxyNGINX Ingress ControllerNote: Traefik cuts the leftmost match only when it starts the path, then restores a leading slash:
/team/abc/x becomes /x, and /team/ABC/x passes through unchanged. The regex route does the same, with the route's own match kept as a lookahead, and the route's plain path takes what the regex misses. Its regex is RE2 and NGINX's PCRE, which agree on the common syntax.X-Forwarded-Prefix: Traefik also sends the stripped prefix to the backend in
X-Forwarded-Prefix; NGINX Ingress Controller does not. If the backend builds URLs from it, set it with action.proxy.requestHeaders.set. | |
Routing (IngressRoute)
routes[].match rule decomposes into three VirtualServer constructs — Host() becomes spec.host, Path*() becomes routes[].path, and every other matcher becomes a routes[].matches[].conditions[] entry. Each condition tests exactly one of header, cookie, argument, or a whitelisted NGINX variable (11 are allowed, including $remote_addr and $request_method), and all conditions inside one match are AND-ed.spec.routes[].priority field — like the traefik.ingress.kubernetes.io/router.priority annotation — has no NGINX Ingress Controller equivalent, because NGINX location precedence is fixed (exact > longest prefix > regex in order). To influence matching, reorder overlapping regex routes rather than assigning a numeric priority.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
ClientIP(...) |
VirtualServer CRD matches[].conditions[] $remote_addr |
Traefik ProxyNGINX Ingress ControllerNote:
ClientIP with a CIDR (for example ClientIP(`10.0.0.0/8`)) cannot be expressed in matches conditions — condition values are compared against $remote_addr as strings, not networks. For allow/deny by CIDR, use an accessControl Policy instead (see Access control). | |
Header(...)HeaderRegexp(...) |
VirtualServer CRD matches[].conditions[].header |
Traefik ProxyNGINX Ingress ControllerNote: String condition values match case-insensitively. Regex values use a
~ prefix (value: "~^Mobile") and negation a ! prefix (value: "!canary") — this value syntax comes from the live NGINX Ingress Controller documentation; verify it against your deployed version. Traefik regexes are Go/RE2 while NGINX uses PCRE — most patterns port unchanged, but verify each one. | |
Host(...) |
VirtualServer CRD spec.host |
Traefik ProxyNGINX Ingress ControllerNote: One host per VirtualServer —
Host(`a`) || Host(`b`) becomes one VirtualServer per host. Wildcards support only a leading label (host: *.example.com), and the host must be unique across all Ingress and VirtualServer resources. | |
Method(...) |
VirtualServer CRD matches[].conditions[] variable: $request_method |
Traefik ProxyNGINX Ingress ControllerNote:
Method(`GET`) || Method(`HEAD`) combines single-method matchers with || to express OR (each Method() matcher takes exactly one method in v3 syntax) — conditions within one match are AND-only, so create one matches[] block per method. | |
Path(...)PathPrefix(...)PathRegexp(...) |
VirtualServer CRD routes[].path (=/exact, /prefix, ~regex) |
Traefik ProxyNGINX Ingress ControllerNote:
routes[].path also supports ~*regex (case-insensitive regex) and ^~/prefix (longest-prefix). NGINX regexes are PCRE while Traefik's are Go/RE2 — most patterns port unchanged, but lookarounds and some syntax differ; verify each pattern. | |
Query(...)QueryRegexp(...) |
VirtualServer CRD matches[].conditions[].argument |
Traefik ProxyNGINX Ingress ControllerNote:
QueryRegexp(`version`, `^v2`) becomes value: "~^v2". The one-argument key-presence form Query(`version`) has no direct presence check — set the value you expect the parameter to carry. | |
Rule operators — && / || / ! |
VirtualServer CRD && → conditions[]; || → routes[]; ! → !value |
Traefik ProxyNGINX Ingress ControllerNote:
! applies only to individual condition values (!value, !~regex) — full boolean negation of sub-expressions (for example !(A && B)) and negated Host/Path matchers cannot be expressed. OR combinations of header/query conditions need separate matches[] entries; review the semantics of each branch after splitting. | |
HostRegexp(...) |
No direct equivalent — VirtualServer CRD per host |
Traefik ProxyNGINX Ingress ControllerNote: If the regex simply matches every subdomain (for example
^[a-z]+\.example\.com$), a leading-label wildcard host (host: *.example.com) may cover it — otherwise enumerate the concrete hosts. | |
IngressRoute → VirtualServer conversion — entry points, match rule, middlewares, weighted services, and TLS. For the TCP/UDP variants (IngressRouteTCP/IngressRouteUDP) see TCP & UDP; for TraefikService weighted routing see Traffic splitting.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
IngressRoute (entryPoints, routes[].match/middlewares/services, tls.secretName) |
VirtualServer CRD (policies[], routes[], spec.host, spec.tls.secret, upstreams[]) |
Traefik ProxyNGINX Ingress ControllerNote:
entryPoints: [websecure] maps to the standard HTTPS listener. Custom entry points/ports map to GlobalConfiguration HTTP listeners referenced via VirtualServer spec.listener, or nginx.org/listen-ports on Ingress. Each middleware converts per its own section — api-ratelimit becomes a rateLimit Policy referenced from policies[] (see Rate limiting & concurrency); middlewares without Policy equivalents (rewrites, headers, …) move into the route's action.proxy instead (see Rewrites and CORS & headers). Traefik service weights are relative; splits[] weights are percentages that must sum to 100 (minimum two splits). An IngressRoute with tls is HTTPS-only — Traefik answers plain HTTP with 404 — while a VirtualServer with a TLS secret also serves plain HTTP; set spec.tls.redirect (enable: true) to send it to HTTPS instead. | |
| No direct equivalent | VirtualServerRoute CRD (cross-namespace delegation) |
Traefik ProxyNGINX Ingress Controller | |
Session affinity
upstreams[].sessionCookie block. Like Traefik's per-service sticky, sessionCookie is configured per upstream: repeat it on every upstream that needs stickiness.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
IngressRoute routes[].services[].sticky.cookie(+ domain, httpOnly, maxAge, name, path, sameSite, secure) |
VirtualServer CRD upstreams[].sessionCookie New v5.4.0 |
Traefik ProxyNGINX Ingress ControllerNote:
expires takes an NGINX time (2h, 7200s) or max — convert maxAge from seconds. Traefik's maxAge: 0 (never expire) and unset maxAge both map to omitting expires; a negative maxAge (expire the cookie immediately) has no equivalent. Traefik accepts sameSite case variants (none, lax, strict) — the NGINX Ingress Controller's samesite field takes the lowercase value. A TraefikService weighted.sticky.cookie uses these same sessionCookie fields, but per-upstream sessionCookie only reproduces the pod-level (within-service) stickiness — not Traefik's WRR service-selection stickiness, which NGINX Ingress Controller's per-request splits[] cannot pin (see the Traffic splitting warning). | |
traefik.ingress.kubernetes.io/service.sticky.cookie(+ .domain, .httponly, .maxage, .name, .path, .samesite, .secure) |
VirtualServer CRD upstreams[].sessionCookie New v5.4.0 |
Traefik ProxyNGINX Ingress ControllerNote:
sessionCookie is a VirtualServer upstream field — plan to convert Ingress resources that use the service.sticky.cookie.* annotations to VirtualServer. The field map is identical to the IngressRoute row above: .maxage seconds become an NGINX expires time (7200 → 2h; 0 or unset → omit expires), and .samesite values are written lowercase. | |
TCP & UDP
IngressRouteTCP/IngressRouteUDP resources bound to static entryPoints. The NGINX Ingress Controller uses TransportServer resources bound to TCP/UDP listeners that are defined once per cluster in a GlobalConfiguration (referenced via the -global-configuration <namespace>/<name> flag). TLS passthrough uses the built-in tls-passthrough listener instead of a GlobalConfiguration entry.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
IngressRouteTCP(TLS terminating: routes[].match: HostSNI(`...`) + tls.secretName) |
TransportServer CRD spec.host + spec.tls.secret + GlobalConfiguration CRD |
Traefik ProxyNGINX Ingress ControllerNote: On a TCP listener, setting
spec.host makes spec.tls.secret required — the NGINX Ingress Controller routes by SNI and terminates TLS on that listener, matching Traefik's terminating HostSNI behavior. Define one GlobalConfiguration per cluster and reference it with the -global-configuration <namespace>/<name> flag. | |
IngressRouteTCP( tls.passthrough: true) |
TransportServer CRD listener.name: tls-passthrough / protocol: TLS_PASSTHROUGH + spec.host |
Traefik ProxyNGINX Ingress ControllerNote: TLS passthrough is off by default — enable it with the
-enable-tls-passthrough flag; the passthrough port is set with -tls-passthrough-port (default 443). Passthrough traffic is routed by SNI host only: there is no HostSNI(`*`) catch-all equivalent, and spec.tls is forbidden on the passthrough listener (TLS is not terminated). | |
IngressRouteUDP |
TransportServer CRD protocol: UDP + upstreamParameters.udpRequests / udpResponses + GlobalConfiguration CRD |
Traefik ProxyNGINX Ingress ControllerNote: This is a 1:1 mapping —
IngressRouteUDP has no match rules, and the TransportServer forbids spec.host for UDP. udpRequests/udpResponses have no Traefik counterpart; set them to the number of datagrams your protocol exchanges per session. | |
MiddlewareTCP inFlightConn( amount) |
TransportServer CRD upstreams[].maxConns |
Traefik ProxyNGINX Ingress ControllerNote: The semantics differ: Traefik's
inFlightConn limits simultaneous connections per client IP, while maxConns caps total connections per upstream server (0 = unlimited). It is the closest TransportServer equivalent, not an exact one — review whether the per-server cap still meets your intent. | |
MiddlewareTCP ipAllowList( sourceRange) |
TransportServer CRD spec.serverSnippets |
Traefik ProxyNGINX Ingress ControllerNote:
serverSnippets are resource snippets and require the -enable-snippets flag (otherwise validation rejects the TransportServer). The deprecated MiddlewareTCP ipWhiteList migrates the same way. | |
IngressRouteTCP services[].proxyProtocol( version) |
TransportServer CRD serverSnippets (proxy_protocol) |
Traefik ProxyNGINX Ingress ControllerNote: Traefik sends PROXY protocol version 2 unless
version: 1 is set. In the stream proxy_protocol directive, on sends version 1 and v2 sends version 2; v2 needs NGINX 1.31.4 or later, which NGINX Ingress Controller 5.7.0 ships. The ConfigMap proxy-protocol key is a different setting: it accepts PROXY protocol from clients. Traefik deprecates services[].proxyProtocol in favor of ServersTransportTCP. | |
TLS & certificates
TLSOption, and can issue certificates itself via built-in ACME (certificatesResolvers). The NGINX Ingress Controller has no built-in ACME — certificate issuance moves to cert-manager — and its protocol/cipher settings are global ConfigMap keys that apply to every host. Only client-certificate authentication gains granularity: the ingressMTLS Policy attaches per application instead of per entry point.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
certificatesResolvers (ACME)IngressRoute spec.tls.certResolverrouter.tls.certresolver |
cert-manager + VirtualServer CRD spec.tls.cert-manager |
Traefik ProxyNGINX Ingress ControllerCertificates must be re-issued: Traefik's ACME certificates are stored in
acme.json — a file, not Kubernetes Secrets — so they cannot be copied over. Plan for cert-manager to issue fresh certificates during the migration window.Note: On an HTTPS-only host, add
issue-temp-cert: true under cert-manager: NGINX Ingress Controller serves a temporary self-signed certificate until cert-manager issues the real one, so the ACME HTTP-01 challenge can succeed.Note: Under
tls.cert-manager, cluster-issuer and issuer are mutually exclusive and exactly one is required. Optional fields: common-name, duration and renew-before (Go durations — no d unit), usages (comma-separated), and issue-temp-cert. tls.domains[].sans (and router.tls.domains.n.sans) move to the cert-manager Certificate's dnsNames — certificate domains are a cert-manager concern, not an NGINX Ingress Controller routing concern. | |
TLSOption spec.cipherSuites |
ConfigMap ssl-ciphers + ssl-prefer-server-ciphers |
Traefik ProxyNGINX Ingress ControllerNote:
ssl-ciphers is global — it applies to every host, not per router or per entry point like TLSOption. Go cipher constant names must be translated to their OpenSSL equivalents (the colon-separated OpenSSL cipher-string format). Defaults differ: Traefik uses Go's cipher defaults, while the ConfigMap key defaults to HIGH:!aNULL:!MD5 with ssl-prefer-server-ciphers off. Like Traefik's cipherSuites (which only applies up to TLS 1.2), this controls the pre-TLS 1.3 suite selection. | |
TLSOption spec.clientAuth( clientAuthType, secretNames) |
Policy CRD ingressMTLS + VirtualServer CRD spec.policies— or —Policy CRD ingressMTLS + nginx.org/policies New v5.5.0 |
Traefik ProxyNGINX Ingress ControllerclientAuthType → verifyClient map: NoClientCert → "off"; VerifyClientCertIfGiven → "optional"; RequireAndVerifyClientCert → "on"; RequestClientCert / RequireAnyClientCert → no exact equivalent — "optional_no_ca" is closest (requests a certificate without CA verification, but does not hard-require one). With secretNames and no clientAuthType, Traefik requires and verifies a certificate ("on"); VerifyClientCertIfGiven or RequireAndVerifyClientCert with no secretNames makes Traefik refuse the TLSOption, and every router naming it. Unlike TLSOption's per-entry-point client auth, the Policy attaches per application — an upgrade in granularity. It must be referenced at VirtualServer spec.policies level (not on a route or subroute), and TLS termination is required.Traefik ProxyNGINX Ingress ControllerNew in v5.5.0:
ingressMTLS Policies can be referenced from Ingress resources via nginx.org/policies. On mergeable Ingress resources the Policy applies to the master only; policy violations return 500. | |
TLSOption spec.curvePreferences |
ConfigMap http-snippets (ssl_ecdh_curve) |
Traefik ProxyNGINX Ingress ControllerNote: There is no
ssl-ecdh-curve ConfigMap key — the ssl_ecdh_curve directive goes into http-snippets, and applies globally. Translate Go curve names to OpenSSL names (CurveP256 → prime256v1, CurveP384 → secp384r1, CurveP521 → secp521r1, X25519 → x25519). ConfigMap snippet keys such as http-snippets are always available and do not require the -enable-snippets flag. | |
TLSOption spec.disableSessionTickets |
ConfigMap http-snippets (ssl_session_tickets off;) |
Traefik ProxyNGINX Ingress ControllerNote: Applies globally. The ConfigMap has a single
http-snippets key — if you also migrate curvePreferences (row above), put both directives in the same http-snippets block. ConfigMap snippet keys are always available and do not require -enable-snippets. | |
TLSOption spec.maxVersionTLSOption spec.minVersion |
ConfigMap ssl-protocols |
Traefik ProxyNGINX Ingress ControllerNote:
ssl-protocols is global — one protocol range for every host, not per router like TLSOption. It is an explicit list, so minVersion/maxVersion become the versions between the two bounds (a maxVersion: VersionTLS12 cap means listing only up to TLSv1.2). Set it explicitly during migration. Traefik's default minVersion is VersionTLS12. If you leave ssl-protocols unset, NGINX Ingress Controller does not render an ssl_protocols directive and NGINX's own default applies — TLSv1.2 TLSv1.3 since NGINX 1.23.4, and NGINX Ingress Controller v5.7.0 ships 1.31.7 — so TLS 1.0/1.1 stay disabled and TLS 1.3 stays enabled. Still set ssl-protocols explicitly to pin the exact protocol range that matches your migrated TLSOption min/max bounds. | |
TLSOption spec.sniStrict |
Not needed (default behavior) |
Traefik ProxyNGINX Ingress ControllerNote: This is behavior, not a knob — there is no user-facing toggle. For the opposite (
sniStrict: false-like) behavior, set -default-server-tls-secret so unmatched handshakes are served a default certificate — see the TLSStore row below. | |
TLSStore( certificates[], defaultCertificate.secretName, defaultGeneratedCert) |
Controller flag -default-server-tls-secret |
Traefik ProxyNGINX Ingress ControllerNote:
defaultGeneratedCert (ACME-issued default certificate) maps to cert-manager — see the certificatesResolvers row above; the NGINX Ingress Controller has no built-in ACME. If -default-server-tls-secret is unset and no fallback certificate file exists, the default server rejects unmatched TLS handshakes instead of serving a default certificate (see the sniStrict row above). | |
TLSOption spec.alpnProtocols |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNo ConfigMap key, annotation or CRD field controls the advertised ALPN protocol list at v5.7.0, so test any client that depends on it after migrating. The http2 ConfigMap key turns HTTP/2 on or off; it does not set an ALPN list. | |
Traffic splitting
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
IngressRoute routes[].services[].weightTraefikService weighted.services[] |
VirtualServer CRD routes[].splits[] |
Traefik ProxyNGINX Ingress ControllerWRR service-selection stickiness is not preserved: Traefik's
weighted.sticky.cookie pins a client to the same weighted service across requests (the WRR-level Set-Cookie records which service handled the first response). The NGINX Ingress Controller selects a split per request via split_clients $request_id …, which re-rolls the weighted choice on every request, so a returning client is redistributed across the weighted upstreams (a canary user does not stay on the same version). upstreams[].sessionCookie pins a client to a pod within one upstream, which is a different thing, so it is not added. There is no direct equivalent for Traefik's service-level stickiness.Note:
splits[].weight takes an integer percentage (0–100) and the weights in one splits block must sum to exactly 100, with at least two splits — convert Traefik's relative weights to percentages (3:1 → 75/25). A weighted TraefikService with a single service becomes a plain action: pass. splits is also available inside matches[] for conditional splitting. A services[].sticky.cookie on one of the weighted Services (stickiness to a pod inside it) maps to that upstream's sessionCookie — see Session affinity. | |
TraefikService mirroring(+ maxBodySize, mirrorBody, mirrors[].name, mirrors[].percent, name) |
VirtualServer CRD location-snippets / VirtualServer CRD server-snippets— or —nginx.org/location-snippetsnginx.org/server-snippets |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerNote: There is no dedicated mirroring field — replicate it with NGINX
mirror directives via snippets. Percent-based sampling (mirrors[].percent) has no equivalent: NGINX mirrors every request. mirrorBody: false becomes mirror_request_body off;. For additional entries in mirrors[], add one mirror line and matching internal location each. Resource snippets require the controller to run with -enable-snippets. | |
TraefikService failover(+ errors.maxRequestBodyBytes, errors.status, fallback, service) |
VirtualServer CRD upstreams[].backup/backupPort (partial) |
Traefik ProxyNGINX Ingress ControllerNote: VirtualServer and VirtualServerRoute upstreams do expose a fallback-service field —
backup + backupPort (TransportServer has the same for TCP) — but it differs from Traefik's failover in two ways: (1) NGINX Ingress Controller fails over when the main servers are unavailable (connection failures counted by max-fails/fail-timeout), not on the HTTP codes in failover.errors.status, which has no trigger equivalent; and (2) backup must reference a Service of type ExternalName, which NGINX Ingress Controller supports only on NGINX Plus. backup also cannot be combined with the random, hash, or ip_hash load-balancing methods. | |
TraefikService highestRandomWeight |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX upstreams have no highest-random-weight selection. The load-balancing methods are hash, ip_hash, least_conn, random and round_robin (least_time requires NGINX Plus). For the weighted 3:1 distribution itself, use routes[].splits[] (the weighted row above). | |
NGINX Plus mappings
Traefik's commercial tier (Traefik Hub / API Gateway) adds authentication and security middlewares, written as plugins (spec.plugin.<name>) — a commercial-to-commercial comparison. Most map to NGINX Plus Policies in NGINX Ingress Controller (JWT, OIDC, WAF, distributed rate limiting); the API-key middleware is the exception, since the apiKey Policy needs no NGINX Plus. The analyzer converts each to its Policy, and leaves out a route whose Hub middleware has no Policy rather than serve it without the check. One feature of Traefik's open source edition also lands here: active health checks, which need NGINX Plus.
Active health checks
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
IngressRoute services[].healthCheck( path, interval, timeout, port, status, hostname, headers) |
VirtualServer CRD NGINX Plus upstreams[].healthCheck |
Traefik ProxyNGINX Ingress ControllerNGINX Plus only: NGINX Ingress Controller rejects a VirtualServer with
upstreams[].healthCheck on NGINX Open Source, and serves an ExternalName Service only on NGINX Plus with a resolver-addresses ConfigMap key. Traefik refuses healthCheck on any other Service type, and drops the route. port carries over as port, status as statusMatch, and headers as headers. NGINX Plus probes with GET at one interval and does not follow redirects, so method, unhealthyInterval and followRedirects do not carry over; mode: grpc is upstreams[].type: grpc. On NGINX Open Source, passiveHealthCheck is the counterpart: see Resilience. TransportServer health-check fields at v5.7.0: enable, fails (default 1), interval (5s), jitter, match.expect, match.send, passes (1), port, timeout (5s). | |
API key authentication
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware plugin.apiKey (Traefik Hub)( keySource, secretValues) |
Policy CRD apiKey |
Traefik ProxyNGINX Ingress ControllerNote: the
apiKey Policy needs no NGINX Plus, and attaches to a VirtualServer or VirtualServerRoute only. Traefik Hub stores only hashes of the keys (secretValues), and the Policy compares keys in clear from a Secret of type nginx.org/apikey, so the keys are issued again. keySource.query maps to suppliedIn.query; keySource.cookie and headerAuthScheme have no field. Once keys are in place, a rateLimit Policy key can use the apikey_-prefixed variables for per-client limits. | |
Distributed rate limiting
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware plugin.distributedRateLimit (Traefik Hub)( limit, period, burst, store.redis) |
Policy CRD rateLimit + ConfigMap NGINX Plus zone-sync |
Traefik ProxyNGINX Ingress ControllerNote: the rate and burst convert as the open source
rateLimit middleware's do (see Rate limiting & concurrency). Without zone sync each NGINX Ingress Controller replica counts on its own, so the cluster admits the limit times the replica count. The zone-sync ConfigMap keys need NGINX Plus: zone-sync-port (default 12345), zone-sync-resolver-addresses, zone-sync-resolver-ipv6 (default true), zone-sync-resolver-valid (default 5s). denyOnError and responseHeaders have no equivalent. | |
JWT authentication
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware plugin.jwt (Traefik Hub)( jwksUrl, signingSecret, publicKey, tokenKey) |
Policy CRD NGINX Plus jwt |
Traefik ProxyNGINX Ingress ControllerNote: the
jwt Policy needs NGINX Plus, and attaches to a VirtualServer or VirtualServerRoute only. signingSecret, publicKey and jwksFile become a JWK set in a Secret of type nginx.org/jwk (key jwk) named in secret; tokenKey becomes token: $arg_<name>. claims, forwardHeaders and usernameClaim have no Policy field: NGINX Plus exposes claims as $jwt_claim_* variables, which snippets can check or forward. A rateLimit Policy key can use them for per-claim limits. | |
OIDC authentication
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware plugin.oidc (Traefik Hub)( issuer, clientId, clientSecret, scopes, redirectUrl) |
Policy CRD NGINX Plus oidcNative |
Traefik ProxyNGINX Ingress ControllerNote:
oidcNative discovers the provider from its issuer, as Traefik Hub does, where the older oidc Policy needs each endpoint by hand. It needs NGINX Plus and NGINX Ingress Controller started with -enable-oidc, and it also attaches to an Ingress through nginx.org/policies. The client secret moves to a Secret of type nginx.org/oidc (key client-secret). claims, forwardHeaders, loginUrl, logoutUrl, disableLogin, session and stateCookie have no oidcNative field. | |
Other Hub middlewares
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware plugin.hmac / plugin.ldap / plugin.oAuthClientCredentials / plugin.oAuthIntrospection / plugin.opa (Traefik Hub) |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNo NGINX Ingress Controller Policy does HMAC signing, LDAP, OAuth 2.0 client credentials, token introspection or OPA. The analyzer leaves out a route that carries one, so it is not served without the check it had. The externalAuth Policy (see Authentication) can front an in-cluster service that speaks LDAP, introspects tokens or asks OPA. | |
WAF
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
Middleware plugin.coraza (Traefik Hub WAF) |
Policy CRD NGINX Plus waf |
Traefik ProxyNGINX Ingress ControllerTraefik ProxyNGINX Ingress ControllerAttachment matters: on an Ingress the
waf Policy works only through nginx.com/policies; through nginx.org/policies the controller logs a warning and the routes answer 500.Note: Traefik Hub's WAF is Coraza, which runs ModSecurity SecLang rules; F5 WAF for NGINX does not read them, so the policy is written again and compiled into a bundle. The
waf Policy needs NGINX Plus with F5 WAF for NGINX. | |
Static config mappings
Traefik's static configuration (traefik.yml, CLI flags, or Helm values) maps to the NGINX Ingress Controller's global nginx-config ConfigMap, GlobalConfiguration CRD, or deployment flags. These settings apply controller-wide.
Certificates & ACME
certificatesResolvers equivalent. Traefik stores ACME certificates in a flat file (acme.json), not in Kubernetes Secrets, so they cannot be copied over: re-issue every certificate through cert-manager before cutover.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
certificatesResolvers.<name>.acme.* (httpChallenge / tlsChallenge / dnsChallenge, caServer, storage) |
cert-manager ClusterIssuer / Issuer + VirtualServer CRD spec.tls.cert-manager |
Traefik ProxyNGINX Ingress ControllerNote:
spec.tls.cert-manager at v5.7.0 also accepts issuer (a namespaced Issuer — mutually exclusive with cluster-issuer), issuer-kind / issuer-group (out-of-tree issuers), common-name, duration, renew-before (Go durations, no d unit), and usages. If you are staying on Ingress resources rather than VirtualServer, use cert-manager's own cert-manager.io/cluster-issuer annotation on the Ingress instead. | |
EntryPoints & networking
nginx.org/listen-ports), and the other entryPoint sub-settings become global ConfigMap keys in nginx-config.| Traefik Proxy | NGINX Ingress Controller |
|---|---|
entryPoints.<name>.address |
GlobalConfiguration CRD spec.listeners[]— or —nginx.org/listen-ports / nginx.org/listen-ports-ssl |
Traefik ProxyNGINX Ingress ControllerNote: The controller loads a single GlobalConfiguration, referenced by the
-global-configuration <namespace>/<name> flag. HTTP listeners are supported at v5.7.0 and are bound by VirtualServer spec.listener.http/spec.listener.https; TCP/UDP listeners are bound by TransportServer (see TCP & UDP). Listeners also accept ipv4/ipv6 bind addresses and ssl (HTTP listeners only — a custom HTTPS port).Traefik ProxyNGINX Ingress ControllerNote: On mergeable Ingress resources,
nginx.org/listen-ports / nginx.org/listen-ports-ssl belong on the master (they are denylisted on minions), and they cannot be used on host-less Ingress resources — use the -default-http-listener-port / -default-https-listener-port flags for those. | |
entryPoints.<name>.forwardedHeaders.trustedIPs |
ConfigMap real-ip-header + real-ip-recursive + set-real-ip-from |
Traefik ProxyNGINX Ingress ControllerNote: These ConfigMap keys are global — they apply to every listener, not per entryPoint.
real-ip-header defaults to X-Real-IP; set it to the header your load balancer actually sends. real-ip-recursive defaults to false. | |
entryPoints.<name>.http.redirections.entryPoint |
nginx.org/http-redirect-code New v5.4.0 + nginx.org/redirect-to-https / nginx.org/ssl-redirect |
Traefik ProxyNGINX Ingress ControllerNote: Traefik's redirection is per-entryPoint (every router on
:80); the NGINX Ingress Controller redirects per server — apply the annotation to each application, or set the ConfigMap key http-redirect-code to change the code globally. nginx.org/ssl-redirect (this nginx.org/ spelling is new in v5.4.0) already defaults to true once the Ingress has a tls section; use nginx.org/redirect-to-https instead when TLS terminates at an external load balancer (it keys off X-Forwarded-Proto). For VirtualServer, use spec.tls.redirect — see Redirects. | |
entryPoints.<name>.http2.maxConcurrentStreams |
ConfigMap http2 + http-snippets (http2_max_concurrent_streams) |
Traefik ProxyNGINX Ingress ControllerNote: The
http2 ConfigMap key is a boolean — on/off is the only built-in knob, and v5.7.0 has no HTTP/2 stream-tuning keys. Tune stream limits with the http2_max_concurrent_streams directive via http-snippets. ConfigMap snippet keys are always available (the -enable-snippets flag gates resource snippets only). | |
entryPoints.<name>.proxyProtocol.trustedIPs |
ConfigMap proxy-protocol + real-ip-header + set-real-ip-from |
Traefik ProxyNGINX Ingress ControllerNote: Incoming only —
proxy-protocol: "true" makes the controller accept the PROXY protocol; it cannot originate PROXY protocol toward backends (TransportServer has no field for it — the workaround is serverSnippets with proxy_protocol on;, which requires the -enable-snippets flag). The setting is global and all-or-nothing: set-real-ip-from controls which peers' PROXY headers are honored for the client IP, it does not gate who may speak the protocol. | |
entryPoints.<name>.transport.keepAliveMaxRequests |
ConfigMap keepalive-requests |
Traefik ProxyNGINX Ingress ControllerNote:
keepalive-requests and keepalive-timeout govern client connections. Do not confuse them with the keepalive ConfigMap key, which sets the upstream keepalive connection cache. | |
entryPoints.<name>.transport.respondingTimeouts.idleTimeout |
ConfigMap keepalive-timeout |
Traefik ProxyNGINX Ingress ControllerNote:
keepalive-timeout (how long an idle client keep-alive connection stays open) is the only direct responding-timeout equivalent — see the next row for readTimeout/writeTimeout. | |
entryPoints.<name>.transport.respondingTimeouts.readTimeout / .writeTimeout |
ConfigMap http-snippets / server-snippets (client_body_timeout, client_header_timeout, send_timeout) |
Traefik ProxyNGINX Ingress ControllerNote: v5.7.0 has no
client-header-timeout, client-body-timeout, or send-timeout ConfigMap keys (confirmed absent) — these client-side timeouts can only be set through snippets. ConfigMap snippet keys are always available; the -enable-snippets flag is only needed for resource snippets. | |
entryPoints.<name>.http3 |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX Ingress Controller v5.7.0 ships no QUIC or HTTP/3 support: its NGINX templates have no quic or http3 directive. Clients negotiate down to HTTP/2 (http2: "true" in the ConfigMap) or HTTP/1.1. | |
Logging & access logs
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
accesslog / accesslog.filePath |
ConfigMap access-log / access-log-off |
Traefik ProxyNGINX Ingress ControllerNote: The controller cannot write access logs to arbitrary file paths — keep the default stdout and collect logs through the container log pipeline, or point
access-log at a syslog: destination. | |
accesslog.format |
ConfigMap log-format + log-format-escaping |
Traefik ProxyNGINX Ingress ControllerNote:
log-format-escaping accepts json, default, or none. For TransportServer (stream) traffic the parallel keys are stream-log-format / stream-log-format-escaping. | |
log.level |
ConfigMap error-log-level |
Traefik ProxyNGINX Ingress ControllerNote: The value is passed verbatim to NGINX, so only NGINX level names are valid — Traefik's
TRACE and PANIC have no equivalent values; pick the closest NGINX level (debug / emerg). | |
accesslog.fields.* / accesslog.filters.* |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX access logging has no status or duration filters and no per-field keep or drop: every request is logged in the format log-format defines. Filter or drop fields downstream in the log pipeline (Fluent Bit, Logstash) instead. | |
Metrics & tracing
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
metrics.prometheus |
Controller flag -enable-prometheus-metrics + -prometheus-metrics-listen-port + -prometheus-tls-secret |
Traefik ProxyNGINX Ingress ControllerNote: Metrics are controller-global, exposed at
/metrics on port 9113 by default (valid range 1024–65535). Point your Prometheus scrape config (or a ServiceMonitor) at that port. Per-router metric toggles have no equivalent — see Observability. | |
tracing (OTLP) |
ConfigMap otel-exporter-endpoint + otel-exporter-header-name / otel-exporter-header-value + otel-service-name + otel-trace-in-http + otel-trace-context New v5.7.0 |
Traefik ProxyNGINX Ingress ControllerNote: These are the six
otel-* ConfigMap keys at v5.7.0, and tracing is global. With otel-trace-in-http left at its default false, tracing can instead be enabled per route via snippets. The exporter speaks OTLP/gRPC only — see the row below for Traefik options with no equivalent. | |
metrics.prometheus.{addEntryPointsLabels, addRoutersLabels, addServicesLabels, buckets, headerLabels}tracing.capturedRequestHeaders / tracing.capturedResponseHeaderstracing.otlp.httptracing.sampleRate |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerPrometheus label sets and histogram buckets are fixed. Tracing has no sample rate or captured-header options (six otel-* ConfigMap keys exist at v5.7.0). The exporter is OTLP/gRPC only: point otel-exporter-endpoint at a collector's gRPC port (4317), and let the collector fan out over OTLP/HTTP if needed. | |
Providers & miscellaneous
| Traefik Proxy | NGINX Ingress Controller |
|---|---|
ping |
Controller flag -ready-status + -ready-status-port |
Traefik ProxyNGINX Ingress ControllerNote: Nothing to migrate unless you disabled or customized it — wire the Deployment's
readinessProbe to the -ready-status-port. | |
providers.kubernetesCRD / providers.kubernetesIngress |
Controller flag -enable-custom-resources |
Traefik ProxyNGINX Ingress Controller | |
providers.kubernetesIngress.strictPrefixMatching |
VirtualServer CRD routes[].path |
Traefik ProxyNGINX Ingress ControllerPrefix matching changes: by default Traefik matches
pathType: Prefix character by character, so /foo also matches /foobar, and the analyzer's plain /foo route does the same. With strictPrefixMatching: true, Traefik matched /foo and paths below /foo/ only. Static configuration is not in a paste, so the analyzer cannot see the setting: write each Prefix path as the two routes above, =/foo and /foo/. On a migrated Ingress, that is an Exact path /foo and a Prefix path /foo/. | |
api.dashboard |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX Ingress Controller ships no web UI. Recreate the view with Prometheus and Grafana: turn on -enable-prometheus-metrics, scrape port 9113 (/metrics), and build Grafana dashboards on those metrics. | |
experimental.plugins |
No direct equivalent |
Traefik ProxyNGINX Ingress ControllerNGINX Ingress Controller has no plugin system. Many plugins map to built-in features (rate limiting, auth, headers), so check the mapping tables first. Beyond those, snippets inject raw NGINX configuration: the ConfigMap snippet keys are always available, and snippets on an Ingress or VirtualServer need the -enable-snippets flag. | |