Traefik & Ingresses with NGINX Annotations¶

Enable seamless migration from NGINX Ingress Controller to Traefik with NGINX annotation compatibility.

NGINX Ingress Controller Retirement

The Kubernetes NGINX Ingress Controller project has announced its retirement in March 2026 and will no longer receive updates or security patches. Traefik provides a migration path by supporting NGINX annotations, allowing you to transition your workloads without rewriting all your Ingress configurations.

→ See the NGINX to Traefik Migration Guide for step-by-step instructions.

For more information about the NGINX Ingress Controller retirement, see the official Kubernetes blog announcement.

Ingress Discovery¶

This provider discovers all Ingresses in the cluster by default, which may lead to duplicated routers if you are also using the standard Kubernetes Ingress provider.

Best Practices:

Use IngressClass to specify which Ingresses should be handled by this provider
Configure watchNamespace to limit discovery to a single namespace
Use watchNamespaceSelector to target Ingresses based on namespace labels

Routing Configuration¶

This provider watches for incoming Ingress events and automatically translates NGINX annotations into Traefik's dynamic configuration, creating the corresponding routers, services, middlewares, and other components needed to handle your traffic.

ConfigMap Configuration and Default Behaviors

Routing annotations take precedence over provider-level defaults, but they don't control all behaviors that NGINX Ingress Controller's ConfigMap configuration would handle globally.

Important differences in default behaviors:

Request buffering: NGINX enables proxy-request-buffering by default, while Traefik requires explicit opt-in via the provider's proxyRequestBuffering option.

To ensure consistent behavior during migration, review and configure Traefik's provider-level options to match your current NGINX ConfigMap settings. See the provider configuration options for available settings.

Configuration Example¶

Configuring Kubernetes Ingress NGINX Controller

RBAC

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: traefik-ingress-controller
rules:
  - apiGroups:
      - ""
    resources:
      - namespaces
    verbs:
      - get
  - apiGroups:
      - ""
    resources:
      - configmaps
      - pods
      - secrets
      - endpoints
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - ""
    resources:
      - services
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - networking.k8s.io
    resources:
      - ingresses
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - networking.k8s.io
    resources:
      - ingresses/status
    verbs:
      - update
  - apiGroups:
      - networking.k8s.io
    resources:
      - ingressclasses
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - ""
    resources:
      - events
    verbs:
      - create
      - patch
  - apiGroups:
      - discovery.k8s.io
    resources:
      - endpointslices
    verbs:
      - list
      - watch
      - get

    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: traefik-ingress-controller
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: traefik-ingress-controller
    subjects:
      - kind: ServiceAccount
        name: traefik-ingress-controller
        namespace: default

Traefik

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: traefik-ingress-controller

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: traefik
  labels:
    app: traefik

spec:
  replicas: 1
  selector:
    matchLabels:
      app: traefik
  template:
    metadata:
      labels:
        app: traefik
    spec:
      serviceAccountName: traefik-ingress-controller
      containers:
        - name: traefik
          image: traefik:v3.7
          args:
            - --entryPoints.web.address=:80
            - --providers.kubernetesingressnginx
          ports:
            - name: web
              containerPort: 80

---
apiVersion: v1
kind: Service
metadata:
  name: traefik
spec:
  type: LoadBalancer
  selector:
    app: traefik
  ports:
    - name: web
      port: 80
      targetPort: 80

Whoami

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
  labels:
    app: whoami

spec:
  replicas: 2
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami
          ports:
            - containerPort: 80

---
apiVersion: v1
kind: Service
metadata:
  name: whoami

spec:
  selector:
    app: whoami
  ports:
    - name: http
      port: 80

Ingress

---
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
spec:
  controller: k8s.io/ingress-nginx

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myingress

spec:
  ingressClassName: nginx
  rules:
    - host: whoami.localhost
      http:
        paths:
          - path: /bar
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80
          - path: /foo
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80

Annotations Support¶

This section lists all known NGINX Ingress annotations. The following annotations are organized by category for easier navigation.

Authentication¶

Annotation	Limitations / Notes
`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. It supports minimal variable interpolation by using the following NGINX variables: `$scheme`, `$host`, `$http_`, `$hostname`, `$request_uri`, `$request_method`, `$query_string`, `$args`, `$arg_`, `$remote_addr`, `$uri`, `$document_uri`, `$server_name`, `$server_port`, `$content_type`, `$content_length`, `$cookie_*`, `$is_args`, `$best_http_host`, `$escaped_request_uri`, `$proxy_add_x_forwarded_for`.
`nginx.ingress.kubernetes.io/auth-signin`	Redirects to signin URL on 401 response. It supports minimal variable interpolation by using the following NGINX variables: `$scheme`, `$host`, `$http_`, `$hostname`, `$request_uri`, `$request_method`, `$query_string`, `$args`, `$arg_`, `$remote_addr`, `$uri`, `$document_uri`, `$server_name`, `$server_port`, `$content_type`, `$content_length`, `$cookie_*`, `$is_args`, `$best_http_host`, `$escaped_request_uri`, `$proxy_add_x_forwarded_for`. Like ingress-nginx, Traefik automatically appends `rd=$scheme://$best_http_host$escaped_request_uri` so the auth service can redirect back after sign-in; pass an empty `rd` to disable it. On routes without a `Host` matcher, the request's `Host` header feeds the interpolation and can be abused for open redirects. Scoping routers with a `Host` rule is strongly recommended when relying on this behavior.
`nginx.ingress.kubernetes.io/auth-snippet`	Supported directives: `proxy_method`, `more_set_headers`, `proxy_set_header`, `more_set_input_headers`, `set`, `if`, `return code [text]`. It supports minimal variable interpolation by using the following NGINX variables: `$scheme`, `$host`, `$http_`, `$hostname`, `$request_uri`, `$request_method`, `$query_string`, `$args`, `$arg_`, `$remote_addr`, `$uri`, `$document_uri`, `$server_name`, `$server_port`, `$content_type`, `$content_length`, `$cookie_*`, `$is_args`, `$best_http_host`, `$escaped_request_uri`, `$proxy_add_x_forwarded_for`.
`nginx.ingress.kubernetes.io/auth-method`	This annotation uses the `proxy_method` directive in Nginx. Thus, it can't be defined on an ingress that already have an `auth-snippet` annotation with the `proxy_method` directive.
`nginx.ingress.kubernetes.io/auth-response-headers`

SSL/TLS¶

Annotation	Limitations / Notes
`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/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/auth-tls-secret`	When validation fails, the rejection happens during the TLS handshake rather than returning a 400 Bad Request.
`nginx.ingress.kubernetes.io/auth-tls-verify-client`	When validation fails, the rejection happens during the TLS handshake rather than returning a 400 Bad Request.
`nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream`
`nginx.ingress.kubernetes.io/auth-tls-verify-depth`	Go has no configurable depth limit. It will accept any valid chain regardless of how many intermediates it contains.

Session Affinity¶

Annotation	Limitations / Notes
`nginx.ingress.kubernetes.io/affinity`
`nginx.ingress.kubernetes.io/affinity-mode`	Only persistent mode supported; balanced not supported.
`nginx.ingress.kubernetes.io/affinity-canary-behavior`	Only the sticky behavior is supported; legacy behavior is not supported.
`nginx.ingress.kubernetes.io/session-cookie-name`
`nginx.ingress.kubernetes.io/session-cookie-secure`
`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/session-cookie-max-age`
`nginx.ingress.kubernetes.io/session-cookie-expires`

Load Balancing & Backend¶

Annotation	Limitations / Notes
`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/service-upstream`
`nginx.ingress.kubernetes.io/upstream-hash-by`	It supports minimal variable interpolation by using the following NGINX variables: `$scheme`, `$host`, `$http_`, `$hostname`, `$request_uri`, `$request_method`, `$query_string`, `$args`, `$arg_`, `$remote_addr`, `$uri`, `$document_uri`, `$server_name`, `$server_port`, `$content_type`, `$content_length`, `$cookie_*`, `$is_args`, `$best_http_host`, `$escaped_request_uri`, `$proxy_add_x_forwarded_for`.
`nginx.ingress.kubernetes.io/upstream-vhost`	Supports NGINX variable interpolation. Request-time variables (`$scheme`, `$host`, `$http_`, `$hostname`, `$request_uri`, `$request_method`, `$query_string`, `$args`, `$arg_`, `$remote_addr`, `$uri`, `$document_uri`, `$server_name`, `$server_port`, `$content_type`, `$content_length`, `$cookie_*`, `$is_args`, `$best_http_host`, `$escaped_request_uri`, `$proxy_add_x_forwarded_for`) and the provider-resolved per-location variables (`$namespace`, `$ingress_name`, `$service_name`, `$service_port`, `$location_path`) are supported. The NGINX-internal variable `$proxy_upstream_name` is not available.
`nginx.ingress.kubernetes.io/custom-headers`	Header whitelisting, similar to `global-allowed-response-headers` NGINX config is not supported.
`nginx.ingress.kubernetes.io/default-backend`	Specifies a fallback service within the same namespace as the Ingress resource used to handle requests when the primary backend service has no active endpoints. If the specified service exposes multiple ports, the first port will receive the traffic.
`nginx.ingress.kubernetes.io/proxy-http-version`	Controls HTTP protocol version for backend communication. Supported value: `"1.1"` (disables HTTP/2 to backend). Value `"1.0"` is not supported and will log a warning.
`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/x-forwarded-prefix`

CORS¶

Annotation	Limitations / Notes
`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-expose-headers`
`nginx.ingress.kubernetes.io/cors-max-age`

Routing¶

Annotation	Limitations / Notes
`nginx.ingress.kubernetes.io/app-root`
`nginx.ingress.kubernetes.io/from-to-www-redirect`	Doesn't support wildcard hosts.
`nginx.ingress.kubernetes.io/use-regex`
`nginx.ingress.kubernetes.io/rewrite-target`
`nginx.ingress.kubernetes.io/permanent-redirect`	Defaults to a 301 Moved Permanently status code.
`nginx.ingress.kubernetes.io/permanent-redirect-code`	Only valid 3XX HTTP Status Codes are accepted.
`nginx.ingress.kubernetes.io/temporal-redirect`	Takes precedence over the `permanent-redirect` annotation. Defaults to a 302 Found status code.
`nginx.ingress.kubernetes.io/temporal-redirect-code`	Only valid 3XX HTTP Status Codes are accepted.
`nginx.ingress.kubernetes.io/custom-http-errors`	Specifies a comma-separated list of HTTP status codes that should be intercepted and served by an error page backend. When any of these status codes occur, the request is forwarded to the global default backend, or to the backend defined by the default-backend annotation if specified.
`nginx.ingress.kubernetes.io/server-alias`	Ignored if the alias conflicts with an existing Ingress Host rule. Ingress Host rules always take precedence.
`nginx.ingress.kubernetes.io/server-snippet`	Supported directives: `add_header`, `proxy_method`, `more_set_headers`, `proxy_set_header`, `more_set_input_headers`, `set`, `if`, `return code [text]`. It supports minimal variable interpolation by using the following NGINX variables: `$scheme`, `$host`, `$http_`, `$hostname`, `$request_uri`, `$request_method`, `$query_string`, `$args`, `$arg_`, `$remote_addr`, `$uri`, `$document_uri`, `$server_name`, `$server_port`, `$content_type`, `$content_length`, `$cookie_*`, `$is_args`, `$best_http_host`, `$escaped_request_uri`, `$proxy_add_x_forwarded_for`.
`nginx.ingress.kubernetes.io/configuration-snippet`	Supported directives: `add_header`, `proxy_method`, `more_set_headers`, `proxy_set_header`, `more_set_input_headers`, `set`, `if`, `return code [text]`. It supports minimal variable interpolation by using the following NGINX variables: `$scheme`, `$host`, `$http_`, `$hostname`, `$request_uri`, `$request_method`, `$query_string`, `$args`, `$arg_`, `$remote_addr`, `$uri`, `$document_uri`, `$server_name`, `$server_port`, `$content_type`, `$content_length`, `$cookie_*`, `$is_args`, `$best_http_host`, `$escaped_request_uri`, `$proxy_add_x_forwarded_for`.

IP Whitelist¶

Client IP Strategy

By default, the client IP is determined from the remote address of the incoming request. When Traefik is behind a reverse proxy, the actual client IP is often found in the X-Forwarded-For header instead. This can be configured globally using the provider option ipAllowListStrategy.

Annotation	Limitations / Notes
`nginx.ingress.kubernetes.io/whitelist-source-range`
`nginx.ingress.kubernetes.io/allowlist-source-range`

Rate Limiting¶

Annotation	Limitations / Notes
`nginx.ingress.kubernetes.io/limit-rps`	Exceeding the limit returns `429 Too Many Requests` instead of NGINX's default `503 Service Unavailable`.
`nginx.ingress.kubernetes.io/limit-rpm`	Exceeding the limit returns `429 Too Many Requests` instead of NGINX's default `503 Service Unavailable`.
`nginx.ingress.kubernetes.io/limit-burst-multiplier`	Default to a multiplier of 5 if the configured value is less than 1. Exceeding the limit returns `429 Too Many Requests` instead of NGINX's default `503 Service Unavailable`.
`nginx.ingress.kubernetes.io/limit-connections`	Exceeding the limit returns `429 Too Many Requests` instead of NGINX's default `503 Service Unavailable`. The concurrent connection limit is evaluated per client IP address. Values less than or equal to `0` are safely ignored.

Buffering¶

Annotation	Limitations / Notes
`nginx.ingress.kubernetes.io/proxy-request-buffering`
`nginx.ingress.kubernetes.io/proxy-body-size`
`nginx.ingress.kubernetes.io/client-body-buffer-size`
`nginx.ingress.kubernetes.io/proxy-buffering`
`nginx.ingress.kubernetes.io/proxy-buffer-size`
`nginx.ingress.kubernetes.io/proxy-buffers-number`	With Traefik, `proxy-buffer-numbers` is actually used to compute the size of a single buffer (size * number).
`nginx.ingress.kubernetes.io/proxy-max-temp-file-size`

Observability¶

Annotation	Limitations / Notes
`nginx.ingress.kubernetes.io/enable-access-log`	Access logs must first be enabled in the install configuration (globally or per entrypoint) for this annotation to take effect. When access logs are enabled, this annotation allows opting out specific Ingresses by setting it to `"false"`. Conversely, when access logs are disabled on an entrypoint, setting this annotation to `"true"` allows opting in specific Ingresses.

Timeout¶

Annotation	Limitations / Notes
`nginx.ingress.kubernetes.io/proxy-connect-timeout`	Timeout can be defined globally at the provider level using the `proxyConnectTimeout` option.
`nginx.ingress.kubernetes.io/proxy-send-timeout`	Timeout can be defined globally at the provider level using the `proxySendTimeout` option.
`nginx.ingress.kubernetes.io/proxy-read-timeout`	Timeout can be defined globally at the provider level using the `proxyReadTimeout` option.

Retry¶

Annotation	Limitations / Notes
`nginx.ingress.kubernetes.io/proxy-next-upstream`	Unlike NGINX, Traefik does not guarantee that retries are sent to a different server. There is no difference between `error` and `timeout`, both are treated as TCP level failure. This configuration can be defined globally at the provider level using the `proxyNextUpstream` option.
`nginx.ingress.kubernetes.io/proxy-next-upstream-tries`	Unlimited retry (0) will be capped to the number of available servers to avoid infinite retries. The value can be defined globally at the provider level using the `proxyNextUpstreamTries` option.
`nginx.ingress.kubernetes.io/proxy-next-upstream-timeout`	The timeout can be defined globally at the provider level using the `proxyNextUpstreamTimeout` option.

Limitations¶

Caveats and Key Behavioral Differences¶

Authentication: Forward auth behaves differently and session caching is not supported. NGINX supports sub-request based auth, while Traefik forwards the original request.
Session Affinity: Only persistent mode is supported.
Leader Election: Not supported; no cluster mode with leader election.
Load Balancing: Only round_robin is supported; EWMA and IP hash are not supported.
CORS: NGINX responds with all configured headers unconditionally; Traefik handles headers differently between pre-flight and regular requests.
TLS/Backend Protocols: AUTO_HTTP, FCGI and some TLS options are not supported in Traefik.
Path Handling: Traefik preserves trailing slashes by default; NGINX removes them unless configured otherwise.
Retry: NGINX guarantee that the next retry will be passed to the next server, while on Traefik there is a possibility that the retry would be passed to the same server.
Rate Limiting: NGINX uses the Leaky Bucket algorithm, where requests are queued and drained at a fixed rate. Once the queue (burst) is full, excess requests are rejected immediately with 503. Traefik uses the Token Bucket algorithm, where the bucket starts full at burst tokens, each request consumes one token, and tokens refill at the limit-rps rate. When the bucket is empty, the request is either delayed until more tokens are available or rejected with 429 if the delay would be too long. In practice, Traefik is slightly more lenient under bursty load, as it smooths out burst traffic rather than dropping it, but the steady-state throughput cap is similar.

Unsupported Annotations¶

Want to Add Support for More Annotations?

You can help extend support in two ways:

Open a PR with the new annotation support.
Reach out to the Traefik Labs support team.

All contributions and suggestions are welcome — let's build this together!

Annotation	Notes
`nginx.ingress.kubernetes.io/auth-tls-error-page`
`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/enable-global-auth`
`nginx.ingress.kubernetes.io/disable-proxy-intercept-errors`
`nginx.ingress.kubernetes.io/limit-rate-after`
`nginx.ingress.kubernetes.io/limit-rate`
`nginx.ingress.kubernetes.io/limit-whitelist`
`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/preserve-trailing-slash`	Traefik preserves trailing slash by default.
`nginx.ingress.kubernetes.io/proxy-cookie-domain`
`nginx.ingress.kubernetes.io/proxy-cookie-path`
`nginx.ingress.kubernetes.io/proxy-redirect-from`
`nginx.ingress.kubernetes.io/proxy-redirect-to`
`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/satisfy`
`nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none`
`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-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/denylist-source-range`
`nginx.ingress.kubernetes.io/stream-snippet`

Global Configuration¶

Traefik does not expose all global configuration options to control default behaviors for Ingresses in the same way NGINX does.

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. These limitations are noted in the annotation tables below where applicable.