Traefik Kubernetes Ingress NGINX 兼容：从 NGINX Ingress Controller 无痛迁移的注解路由配置全指南

本篇文章系统梳理 Traefik 官方仓库中 Kubernetes Ingress NGINX（kubernetesIngressNGINX）提供者（Provider）的路由配置能力：如何通过兼容 nginx.ingress.kubernetes.io/* 注解，让原本面向 NGINX Ingress Controller 编写的 Ingress 资源在 Traefik 上原样生效，从而在 NGINX Ingress Controller 于 2026 年 3 月正式停止维护之前完成平滑迁移。读完本文你将掌握：Ingress 发现范围控制、完整的最小可用部署 YAML（RBAC / Deployment / Service / IngressClass / Ingress）、11 大类注解的逐条语义与限制说明，以及 Traefik 与 NGINX 在默认行为与底层算法上的关键差异清单。

!!! info "文档与源码出处" 本文以仓库文档 ingress-nginx.md 为骨架，结合提供者源码（见 pkg/provider/kubernetes/ingress-nginx）与提供者安装配置参考编写。

背景：为什么需要 NGINX 注解兼容能力

Kubernetes 官方的 NGINX Ingress Controller 项目已经宣布将在 2026 年 3 月退休，届时将不再接收任何更新与安全补丁。对于正在使用 nginx.ingress.kubernetes.io/* 注解管理流量的用户来说，继续留在该控制器上意味着长期暴露于未修复的安全风险中。

Traefik（"The Cloud Native Application Proxy"）提供了一条迁移路径：其 Kubernetes Ingress NGINX 提供者直接支持解析 NGINX Ingress 注解，并在内部将其翻译为 Traefik 的动态配置。这意味着大量存量 Ingress 清单无需重写为 Traefik 的 CRD（IngressRoute / Middleware 等）即可继续工作，从而把迁移成本从“重写全部路由”降为“调整部署方式 + 核对行为差异”。

分步迁移的完整操作指引见仓库文档 NGINX to Traefik 迁移指南，本文则聚焦该提供者的路由配置与注解兼容细节。

Ingress 发现机制与作用域控制

从文档与源码结构看，该提供者会默认发现集群内的全部 Ingress。因此，如果你同时启用了标准的 Kubernetes Ingress 提供者（kubernetesingress）与当前的 Ingress NGINX 提供者（kubernetesingressnginx），两者会对同一批 Ingress 重复生成路由，导致路由器（Router）重复。避免冲突的最佳实践有：

• 使用 IngressClass 精确圈定：只让带指定 ingressClassName 的 Ingress 被本提供者接管（下文的完整示例中，IngressClass nginx 的 spec.controller 声明为 k8s.io/ingress-nginx，Ingress 通过 ingressClassName: nginx 关联它）；
• 配置 watchNamespace：将发现范围限制在单个命名空间内；
• 使用 watchNamespaceSelector：按命名空间标签（Label）定向选择要监听的命名空间。

这几个选项都属于提供者级配置，具体参数名与取值方式请查阅提供者安装配置参考文档中 watchNamespace、watchNamespaceSelector 等条目。

工作方式：注解如何被翻译成 Traefik 动态配置

该提供者本质上是一个 Kubernetes 事件的监听者 + 翻译器：

1. 监听 Ingress 的创建 / 更新 / 删除事件；
2. 读取 Ingress 上携带的 nginx.ingress.kubernetes.io/* 注解；
3. 把它们转换为 Traefik 的动态配置，自动生成路由所依赖的 Router、Service、Middleware 等组件；
4. 通过 Traefik 动态配置通道热更新到运行时。

在源码层面，这一“注解词典”被集中声明在 annotations.go 的 IngressConfig 结构体中。例如该结构体通过形如 AuthType *string \annotation:"nginx.ingress.kubernetes.io/auth-type"`的结构化标签逐条声明支持的注解、其数据类型与对应字段（以 [annotations.go](https://gitcode.com/GitHub_Trending/tr/traefik/blob/14bc52dd1f1d1c08cedd1da531a527fc04d79c19/pkg/provider/kubernetes/ingress-nginx/annotations.go?utm_source=gitcode_repo_files#L13-L14) 为起点），随后由翻译逻辑（同目录下的translator.go、build.go、middleware.go` 等）把解析结果映射到各类 Traefik 中间件与服务定义上。从源码结构可以推断：凡是未出现在该结构体中的注解，就不会被解析生效——这正是本文后续“不支持注解清单”一节所对应代码语义的体现。

需特别留意的 ConfigMap 与默认行为差异

NGINX Ingress Controller 中大量全局行为是通过其 ConfigMap 配置的（而不是逐 Ingress 注解）。Traefik 的注解体系能覆盖路由级行为，但不能 1:1 复刻 NGINX ConfigMap 的全套全局语义。迁移时需要特别核对的两个默认行为差异：

• 请求缓冲（Request buffering）：NGINX 默认开启 proxy-request-buffering；Traefik 默认不缓冲，需要显式开启提供者级选项 proxyRequestBuffering 才会获得同样行为；
• 旧式 Scheme 头：如果业务应用依赖 X-Forwarded-Scheme 或 X-Scheme 请求头，需要在对应入口点（EntryPoint）上设置 entryPoints.<name>.forwardedHeaders.addXForwardedSchemeHeaders=true。

原则：路由级注解优先级高于提供者级默认值，但注解无法取代 NGINX ConfigMap 的所有全局控制。为保证迁移前后行为一致，建议对照当前的 NGINX ConfigMap 设置，逐项检查并配置 Traefik 的提供者级选项（完整选项列表见提供者配置参考）。

最小可用配置示例

下面的四段 YAML 组成了从零运行的完整示例：先为控制器声明所需 RBAC 权限，再部署 Traefik（启用 kubernetesingressnginx 提供者），接着部署一个测试后端 whoami，最后用 IngressClass + Ingress 把流量路由到该后端。该示例结构完整复刻自原文档，可直接用于本地集群（如 minikube / kind）验证。

1) RBAC：ClusterRole 与 ClusterRoleBinding

控制器需要读取 Ingress、IngressClass、Service、Endpoints、EndpointsSlice、ConfigMap、Secret、Pod，并更新 Ingress 状态、写入事件：

---
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

2) Traefik：ServiceAccount + Deployment + Service

Deployment 的关键在于启动参数 --providers.kubernetesingressnginx，它开启了 Ingress NGINX 提供者；入口点 web 监听 :80：

---
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

3) 测试后端 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

4) IngressClass 与 Ingress

注意：IngressClass 的 controller 字段仍声明为 k8s.io/ingress-nginx，这是为了让存量 Ingress 无需改动 ingressClassName 也能被接管；Ingress 本身带两条 Exact 路径规则 /bar 与 /foo，都指向 whoami 服务：

---
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

部署完成后，访问 http://whoami.localhost/bar 与 /foo 即可命中所配置的后端；后续若要展示注解兼容效果，只需在 myingress 的 metadata.annotations 中追加各类 NGINX 注解。

注解支持总览

以下分类表格列出该提供者已知支持的 NGINX Ingress 注解。表格本身源自官方文档的兼容矩阵，其中的 Limitations / Notes 列记录了与原生 NGINX 行为的差异——这些差异正是迁移验证阶段最需要逐个对照检查的检查点。

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	仅支持 URL 与响应头拷贝。Forward auth 的行为与 NGINX 不同。支持最小变量插值，可用 NGINX 变量如下：$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	在收到 401 响应时重定向到 signin URL，支持与 auth-url 相同的最小变量插值。与 ingress-nginx 一样，Traefik 会自动追加 rd=$scheme://$best_http_host$escaped_request_uri，使认证服务在登录后能重定向回来；传入空的 rd 可关闭该行为。安全提示：在没有 Host 匹配器的路由上，请求的 Host 头会参与插值，可能被利用进行开放重定向，强烈建议依赖该行为时用 Host 规则限定 Router 作用域。
nginx.ingress.kubernetes.io/auth-snippet	支持的指令：proxy_method、more_set_headers、proxy_set_header、more_set_input_headers、set、if、return code [text]。支持与 auth-url 相同的最小变量插值。
nginx.ingress.kubernetes.io/auth-method	该注解在 NGINX 中对应 proxy_method 指令，因此不能定义在已通过 auth-snippet 携带 proxy_method 指令的 Ingress 上。
nginx.ingress.kubernetes.io/auth-response-headers
nginx.ingress.kubernetes.io/enable-global-auth

SSL/TLS

Annotation	Limitations / Notes
nginx.ingress.kubernetes.io/ssl-redirect	若全局开启，无法在单条路由上单独退出（opt-out）。
nginx.ingress.kubernetes.io/force-ssl-redirect	若全局开启，无法在单条路由上单独退出（opt-out）。
nginx.ingress.kubernetes.io/ssl-passthrough	在 SNI / 默认后端处理上与 NGINX 存在差异。
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	校验失败时，拒绝发生在 TLS 握手阶段，而不是返回 400 Bad Request。
nginx.ingress.kubernetes.io/auth-tls-verify-client	校验失败时，拒绝发生在 TLS 握手阶段，而不是返回 400 Bad Request。
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream
nginx.ingress.kubernetes.io/auth-tls-verify-depth	Go 没有可配置的证书链深度上限，只要链有效就会接受，无论包含多少层中间证书。

Session Affinity（会话保持）

Annotation	Limitations / Notes
nginx.ingress.kubernetes.io/affinity
nginx.ingress.kubernetes.io/affinity-mode	仅支持 persistent 模式，不支持 balanced 模式。
nginx.ingress.kubernetes.io/affinity-canary-behavior	仅支持 sticky 行为，不支持 legacy 行为。
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	未实现，被静默忽略。
nginx.ingress.kubernetes.io/backend-protocol	不支持 FCGI 与 AUTO_HTTP。
nginx.ingress.kubernetes.io/service-upstream
nginx.ingress.kubernetes.io/upstream-hash-by	支持最小变量插值（变量列表同 auth-url 一节）。
nginx.ingress.kubernetes.io/upstream-vhost	支持 NGINX 变量插值：请求时变量（$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），以及提供者解析出的每位置（per-location）变量（$namespace、$ingress_name、$service_name、$service_port、$location_path）。NGINX 内部变量 $proxy_upstream_name 不可用。
nginx.ingress.kubernetes.io/custom-headers	不支持类似 NGINX 配置 global-allowed-response-headers 的响应头白名单机制。
nginx.ingress.kubernetes.io/default-backend	指定与 Ingress 同命名空间内的兜底服务：当主后端服务没有任何活跃端点时用于处理请求。若该服务暴露多个端口，流量会打到第一个端口。
nginx.ingress.kubernetes.io/proxy-http-version	控制与后端通信的 HTTP 协议版本。支持的值："1.1"（禁用到后端的 HTTP/2）。"1.0" 不支持，会打印警告。
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	部分支持。
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	不支持通配符主机（wildcard host）。
nginx.ingress.kubernetes.io/use-regex
nginx.ingress.kubernetes.io/rewrite-target
nginx.ingress.kubernetes.io/permanent-redirect	默认使用 301 Moved Permanently。
nginx.ingress.kubernetes.io/permanent-redirect-code	仅接受合法的 3XX HTTP 状态码。
nginx.ingress.kubernetes.io/temporal-redirect	优先级高于 permanent-redirect；默认使用 302 Found。
nginx.ingress.kubernetes.io/temporal-redirect-code	仅接受合法的 3XX HTTP 状态码。
nginx.ingress.kubernetes.io/custom-http-errors	指定一组逗号分隔、需要被错误页后端截获处理的 HTTP 状态码。当这些状态码出现时，请求被转发到全局默认后端；若指定了 default-backend 注解，则转发到该注解定义的后端。
nginx.ingress.kubernetes.io/server-alias	若该别名与既有 Ingress Host 规则冲突则被忽略——Ingress Host 规则始终优先。
nginx.ingress.kubernetes.io/server-snippet	支持的指令：add_header、proxy_method、more_set_headers、proxy_set_header、more_set_input_headers、set、if、return code [text]；支持最小变量插值。
nginx.ingress.kubernetes.io/configuration-snippet	支持的指令：add_header、proxy_method、more_set_headers、proxy_set_header、more_set_input_headers、set、if、return code [text]；支持最小变量插值。

IP Whitelist（IP 白名单）

!!! info "客户端 IP 判定策略" 默认情况下，客户端 IP 取自请求的远端地址（remote address）。当 Traefik 位于反向代理之后时，真实客户端 IP 通常存在于 X-Forwarded-For 头中，可通过提供者选项 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	超限返回 429 Too Many Requests（NGINX 默认返回 503）。
nginx.ingress.kubernetes.io/limit-rpm	超限返回 429 Too Many Requests（NGINX 默认返回 503）。
nginx.ingress.kubernetes.io/limit-burst-multiplier	若配置值小于 1，默认取乘数 5；超限返回 429 而非 NGINX 的 503。
nginx.ingress.kubernetes.io/limit-connections	超限返回 429 而非 NGINX 的 503。并发连接数限制按客户端 IP 评估；小于等于 0 的值会被安全忽略。

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	在 Traefik 中该值实际被用于计算单个缓冲区的大小（size × number）。
nginx.ingress.kubernetes.io/proxy-max-temp-file-size

Observability（可观测性）

Annotation	Limitations / Notes
nginx.ingress.kubernetes.io/enable-access-log	访问日志须先在安装配置中全局（或按入口点）开启，该注解才能生效。访问日志开启时，可把该注解设为 "false" 对特定 Ingress 退出；反之，当入口点访问日志关闭时，设为 "true" 可对特定 Ingress 开启。

Timeout（超时）

Annotation	Limitations / Notes
nginx.ingress.kubernetes.io/proxy-connect-timeout	可在提供者级别通过 proxyConnectTimeout 选项全局定义。
nginx.ingress.kubernetes.io/proxy-send-timeout	可在提供者级别通过 proxySendTimeout 选项全局定义。
nginx.ingress.kubernetes.io/proxy-read-timeout	可在提供者级别通过 proxyReadTimeout 选项全局定义。

Retry（重试）

Annotation	Limitations / Notes
nginx.ingress.kubernetes.io/proxy-next-upstream	与 NGINX 不同，Traefik 不保证重试会发给不同的服务器；error 与 timeout 没有区别，都按 TCP 层失败处理。可在提供者级别通过 proxyNextUpstream 选项全局定义。
nginx.ingress.kubernetes.io/proxy-next-upstream-tries	无限重试（0）会被封顶为可用服务器数量，以避免无限循环。可在提供者级别通过 proxyNextUpstreamTries 选项全局定义。
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout	可在提供者级别通过 proxyNextUpstreamTimeout 选项全局定义。

关键行为差异（Caveats）与底层原理对照

即使注解一一对应，Traefik 与 NGINX 在默认行为与实现机制上仍有本质差别。下列差异直接影响迁移后请求的最终表现，建议在灰度验证阶段逐一确认：

• 认证（Authentication）：Forward auth 行为不同，且不支持会话缓存。NGINX 基于 sub-request 做认证，而 Traefik 直接转发原始请求给认证服务。
• 会话保持（Session Affinity）：仅支持 persistent 模式（即基于 cookie 的粘性会话）。
• Leader Election（主节点选举）：不支持；不存在带 leader election 的集群模式。
• 负载均衡（Load Balancing）：仅支持 round-robin；EWMA 与 IP hash 均不支持（源码中 load-balance 注解被静默忽略与此一致）。
• CORS：NGINX 会无条件按配置返回全部 CORS 头；Traefik 在预检请求与普通请求之间对头的处理方式不同。
• TLS / 后端协议：AUTO_HTTP、FCGI 以及部分 TLS 选项在 Traefik 中不受支持。
• 路径处理（Path Handling）：Traefik 默认保留路径末尾斜杠（trailing slash）；NGINX 除非另行配置，否则会移除末尾斜杠。
• 重试（Retry）：NGINX 保证下一次重试会交给下一台服务器；Traefik 存在重试落在同一台服务器上的可能。
• 限流算法（Rate Limiting）：这是差异最值得展开的一项——
  • NGINX 使用 Leaky Bucket（漏桶）：请求先进入队列（burst），以固定速率被排空；一旦队列填满，超出的请求立即以 503 被拒绝。
  • Traefik 使用 Token Bucket（令牌桶）：桶以 burst 个令牌为初始容量，每个请求消耗一个令牌，令牌按 limit-rps 速率回填；当桶空时，请求要么被延迟到令牌可用，要么在延迟过长时以 429 拒绝。
  • 实际效果上，Traefik 对突发流量更宽容（会平滑突发而非直接丢弃），但稳态吞吐上限相近。

暂不支持的注解清单

以下 NGINX Ingress 注解目前不受支持（无论是否书写在 Ingress 上都会被忽略，除非未来版本扩充支持）。迁移前请检查工作负载是否依赖其中任一注解。若你希望贡献代码为 Traefik 增加对某个注解的支持，可以参照提交 Pull Request 的贡献指南发起 PR：

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/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 默认即保留末尾斜杠，因此无需该注解。
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

全局配置的差异边界

Traefik 并不像 NGINX 那样把全部全局默认行为都暴露为可配置项。一些在 NGINX 中可全局配置、且可被单个 Ingress 覆盖的行为（例如默认 SSL 重定向、默认限流、默认会话保持等），在 Traefik 中目前既不支持全局设置，也无法按 Ingress 覆盖——上一节注解表格中凡标注“可在提供者级别通过某选项全局定义”的条目属于例外，其余行为需要你在迁移时以路由级注解显式声明，或在应用层做出适配。

综上所述，Ingress NGINX 提供者不是 NGINX 配置的逐字复刻，而是一套“注解兼容 + 行为对齐检查”的迁移基础设施。建议的落地顺序是：先用本文的最小示例跑通 whoami 验证链路 → 依据上文的注解矩阵排查存量 Ingress 使用的注解是否受支持 → 对照“关键行为差异”逐项核对默认行为 → 最后参考 NGINX to Traefik 迁移指南 完成流量切换。