Traefik Kubernetes Ingress NGINX Routing Configuration

The experimental Kubernetes Controller for Ingresses with NGINX annotations.

Ingress Discovery

The Kubernetes Ingress NGINX provider is discovering by default all Ingresses in the cluster, which may lead to duplicated routers if you are also using the Kubernetes Ingress provider. We recommend to use IngressClass for the Ingresses you want to be handled by this provider, or to use the watchNamespace or watchNamespaceSelector options to limit the discovery of Ingresses to a specific namespace or set of namespaces.

---

Overview

The NGINX Ingress Controller is officially projected to enter maintenance mode, leaving organizations with production workloads that need a practical migration path. This provider addresses that need by offering a secure bridge that respects existing configuration investments while enabling future innovation.

The Kubernetes Ingress NGINX provider watches for incoming ingresses events, such as the example below, and derives the corresponding Routing Configuration from it, which in turn will create the resulting routers, services, handlers, etc.

Annotations Support

This section lists all known NGINX Ingress annotations, split between those currently implemented (with limitations if any) and those not implemented. Limitations or behavioral differences are indicated where relevant.

Global configuration

Traefik Hub API Gateway does not expose all global configuration options to control default behaviors for ingresses.

Some behaviors that are globally configurable in NGINX (such as default SSL redirect, rate limiting, or affinity) are currently not supported and cannot be overridden per-ingress as in NGINX.

Supported NGINX Annotations

The annotation support follows a data-driven approach based on real-world usage patterns. Rather than attempting to support every possible annotation immediately, the implementation focuses on the most commonly used annotations that appear in the majority of production deployments. This approach allows most organizations to migrate their core ingress configurations without modification while gradually adopting Traefik-native features for advanced use cases.

The provider architecture also positions teams for future transitions to the Gateway API standard, which represents the next evolution of Kubernetes networking. Starting with this provider means adopting a platform that actively leads Gateway API implementation while maintaining backward compatibility with existing ingress resources.

We welcome feedback on which unsupported annotations matter most for your deployments. The provider's architecture makes community contributions clear, and each addition expands the migration path for more use cases.

For a detailed discussion of the design philosophy and migration strategies, see the NGINX Ingress transition blog post.

Annotation	Limitations / Notes
nginx.ingress.kubernetes.io/affinity
nginx.ingress.kubernetes.io/affinity-mode	Only persistent mode supported; balanced/canary not supported.
nginx.ingress.kubernetes.io/auth-type
nginx.ingress.kubernetes.io/auth-secret
nginx.ingress.kubernetes.io/auth-secret-type
nginx.ingress.kubernetes.io/auth-realm
nginx.ingress.kubernetes.io/auth-url	Only URL and response headers copy supported. Forward auth behaves differently than NGINX.
nginx.ingress.kubernetes.io/auth-method
nginx.ingress.kubernetes.io/auth-response-headers
nginx.ingress.kubernetes.io/ssl-redirect	Cannot opt-out per route if enabled globally.
nginx.ingress.kubernetes.io/force-ssl-redirect	Cannot opt-out per route if enabled globally.
nginx.ingress.kubernetes.io/ssl-passthrough	Some differences in SNI/default backend handling.
nginx.ingress.kubernetes.io/use-regex
nginx.ingress.kubernetes.io/session-cookie-name
nginx.ingress.kubernetes.io/session-cookie-path
nginx.ingress.kubernetes.io/session-cookie-domain
nginx.ingress.kubernetes.io/session-cookie-samesite
nginx.ingress.kubernetes.io/load-balance	Only round_robin supported; ewma and IP hash not supported.
nginx.ingress.kubernetes.io/backend-protocol	FCGI and AUTO_HTTP not supported.
nginx.ingress.kubernetes.io/enable-cors	Partial support.
nginx.ingress.kubernetes.io/cors-allow-credentials
nginx.ingress.kubernetes.io/cors-allow-headers
nginx.ingress.kubernetes.io/cors-allow-methods
nginx.ingress.kubernetes.io/cors-allow-origin
nginx.ingress.kubernetes.io/cors-max-age
nginx.ingress.kubernetes.io/proxy-ssl-server-name
nginx.ingress.kubernetes.io/proxy-ssl-name
nginx.ingress.kubernetes.io/proxy-ssl-verify
nginx.ingress.kubernetes.io/proxy-ssl-secret
nginx.ingress.kubernetes.io/service-upstream

Caveats and Key Behavioral Differences

• Authentication: Forward auth behaves differently and session caching is not supported. NGINX supports sub-request based auth, while Traefik Hub API Gateway forwards the original request.
• Session Affinity: Only persistent mode is supported.
• Leader Election: Not supported; no cluster mode with leader election.
• Default Backend: Only defaultBackend in Ingress spec is supported; the annotation is ignored.
• Load Balancing: Only round_robin is supported; EWMA and IP hash are not supported.
• CORS: NGINX responds with all configured headers unconditionally; Traefik Hub API Gateway handles headers differently between pre-flight and regular requests.
• TLS/Backend Protocols: AUTO_HTTP, FCGI and some TLS options are not supported in Traefik Hub API Gateway.
• Path Handling: Traefik Hub API Gateway preserves trailing slashes by default; NGINX removes them unless configured otherwise.

Unsupported NGINX Annotations

Annotation	Notes
nginx.ingress.kubernetes.io/app-root
nginx.ingress.kubernetes.io/affinity-canary-behavior
nginx.ingress.kubernetes.io/auth-tls-secret
nginx.ingress.kubernetes.io/auth-tls-verify-depth
nginx.ingress.kubernetes.io/auth-tls-verify-client
nginx.ingress.kubernetes.io/auth-tls-error-page
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream
nginx.ingress.kubernetes.io/auth-tls-match-cn
nginx.ingress.kubernetes.io/auth-cache-key
nginx.ingress.kubernetes.io/auth-cache-duration
nginx.ingress.kubernetes.io/auth-keepalive
nginx.ingress.kubernetes.io/auth-keepalive-share-vars
nginx.ingress.kubernetes.io/auth-keepalive-requests
nginx.ingress.kubernetes.io/auth-keepalive-timeout
nginx.ingress.kubernetes.io/auth-proxy-set-headers
nginx.ingress.kubernetes.io/auth-snippet
nginx.ingress.kubernetes.io/enable-global-auth
nginx.ingress.kubernetes.io/canary
nginx.ingress.kubernetes.io/canary-by-header
nginx.ingress.kubernetes.io/canary-by-header-value
nginx.ingress.kubernetes.io/canary-by-header-pattern
nginx.ingress.kubernetes.io/canary-by-cookie
nginx.ingress.kubernetes.io/canary-weight
nginx.ingress.kubernetes.io/canary-weight-total
nginx.ingress.kubernetes.io/client-body-buffer-size
nginx.ingress.kubernetes.io/configuration-snippet
nginx.ingress.kubernetes.io/custom-http-errors
nginx.ingress.kubernetes.io/disable-proxy-intercept-errors
nginx.ingress.kubernetes.io/default-backend	Use defaultBackend in Ingress spec.
nginx.ingress.kubernetes.io/limit-rate-after
nginx.ingress.kubernetes.io/limit-rate
nginx.ingress.kubernetes.io/limit-whitelist
nginx.ingress.kubernetes.io/limit-rps
nginx.ingress.kubernetes.io/limit-rpm
nginx.ingress.kubernetes.io/limit-burst-multiplier
nginx.ingress.kubernetes.io/limit-connections
nginx.ingress.kubernetes.io/global-rate-limit
nginx.ingress.kubernetes.io/global-rate-limit-window
nginx.ingress.kubernetes.io/global-rate-limit-key
nginx.ingress.kubernetes.io/global-rate-limit-ignored-cidrs
nginx.ingress.kubernetes.io/permanent-redirect
nginx.ingress.kubernetes.io/permanent-redirect-code
nginx.ingress.kubernetes.io/temporal-redirect
nginx.ingress.kubernetes.io/preserve-trailing-slash	Traefik Hub API Gateway preserves trailing slashes by default.
nginx.ingress.kubernetes.io/proxy-cookie-domain
nginx.ingress.kubernetes.io/proxy-cookie-path
nginx.ingress.kubernetes.io/proxy-connect-timeout
nginx.ingress.kubernetes.io/proxy-send-timeout
nginx.ingress.kubernetes.io/proxy-read-timeout
nginx.ingress.kubernetes.io/proxy-next-upstream
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout
nginx.ingress.kubernetes.io/proxy-next-upstream-tries
nginx.ingress.kubernetes.io/proxy-request-buffering
nginx.ingress.kubernetes.io/proxy-redirect-from
nginx.ingress.kubernetes.io/proxy-redirect-to
nginx.ingress.kubernetes.io/proxy-http-version
nginx.ingress.kubernetes.io/proxy-ssl-ciphers
nginx.ingress.kubernetes.io/proxy-ssl-verify-depth
nginx.ingress.kubernetes.io/proxy-ssl-protocols
nginx.ingress.kubernetes.io/enable-rewrite-log
nginx.ingress.kubernetes.io/rewrite-target
nginx.ingress.kubernetes.io/satisfy
nginx.ingress.kubernetes.io/server-alias
nginx.ingress.kubernetes.io/server-snippet
nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none
nginx.ingress.kubernetes.io/session-cookie-expires
nginx.ingress.kubernetes.io/session-cookie-change-on-failure
nginx.ingress.kubernetes.io/ssl-ciphers
nginx.ingress.kubernetes.io/ssl-prefer-server-ciphers
nginx.ingress.kubernetes.io/connection-proxy-header
nginx.ingress.kubernetes.io/enable-access-log
nginx.ingress.kubernetes.io/enable-opentracing
nginx.ingress.kubernetes.io/opentracing-trust-incoming-span
nginx.ingress.kubernetes.io/enable-opentelemetry
nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span
nginx.ingress.kubernetes.io/enable-modsecurity
nginx.ingress.kubernetes.io/enable-owasp-core-rules
nginx.ingress.kubernetes.io/modsecurity-transaction-id
nginx.ingress.kubernetes.io/modsecurity-snippet
nginx.ingress.kubernetes.io/mirror-request-body
nginx.ingress.kubernetes.io/mirror-target
nginx.ingress.kubernetes.io/mirror-host
nginx.ingress.kubernetes.io/x-forwarded-prefix
nginx.ingress.kubernetes.io/upstream-hash-by
nginx.ingress.kubernetes.io/upstream-vhost
nginx.ingress.kubernetes.io/denylist-source-range
nginx.ingress.kubernetes.io/whitelist-source-range
nginx.ingress.kubernetes.io/proxy-buffering
nginx.ingress.kubernetes.io/proxy-buffers-number
nginx.ingress.kubernetes.io/proxy-buffer-size
nginx.ingress.kubernetes.io/proxy-max-temp-file-size
nginx.ingress.kubernetes.io/stream-snippet