Traefik & Ingresses with NGINX Annotations

Enable seamless migration from NGINX Ingress Controller to Traefik with NGINX annotation compatibility. {: .subtitle }

!!! warning "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](../../../migrate/nginx-to-traefik.md) for step-by-step instructions.**

For more information about the NGINX Ingress Controller retirement, see the [official Kubernetes blog announcement](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement).

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.

!!! warning "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](../../install-configuration/providers/kubernetes/kubernetes-ingress-nginx.md) for available settings.

Configuration Example

??? example "Configuring Kubernetes Ingress NGINX Controller"

  ```yaml tab="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
  ```

  ```yaml tab="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
  ```

  ```yaml tab="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
  ```

  ```yaml tab="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

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. | | <a id="opt-nginx-ingress-kubernetes-ioauth-snippet" href="#opt-nginx-ingress-kubernetes-ioauth-snippet" title="#opt-nginx-ingress-kubernetes-ioauth-snippet">nginx.ingress.kubernetes.io/auth-snippet</a> | 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. | | <a id="opt-nginx-ingress-kubernetes-ioauth-method" href="#opt-nginx-ingress-kubernetes-ioauth-method" title="#opt-nginx-ingress-kubernetes-ioauth-method">nginx.ingress.kubernetes.io/auth-method</a> | 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. | | <a id="opt-nginx-ingress-kubernetes-ioauth-response-headers" href="#opt-nginx-ingress-kubernetes-ioauth-response-headers" title="#opt-nginx-ingress-kubernetes-ioauth-response-headers">nginx.ingress.kubernetes.io/auth-response-headers</a> | |

SSL/TLS

Session Affinity

Load Balancing & Backend

CORS

Routing

IP Whitelist

!!! info "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`](../../../install-configuration/providers/kubernetes/kubernetes-ingress-nginx/#opt-providers-kubernetesIngressNGINX-ipAllowListStrategy).

Rate Limiting

Buffering

Observability

Timeout

Retry

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

!!! question "Want to Add Support for More Annotations?"

You can help extend support in two ways:

- [**Open a PR**](../../../contributing/submitting-pull-requests.md) with the new annotation support.
- **Reach out** to the [Traefik Labs support team](https://info.traefik.io/request-commercial-support?cta=doc).

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

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.