跳到正文
Træfɪk

Traefik 与带 NGINX 注解的 Ingress

该提供者是一个 Kubernetes Ingress 控制器,通过支持 Ingress 规范管理对集群服务的访问。它还支持 Ingress 上的许多 ingress-nginx 注解,让团队只需少量配置修改就能从 NGINX Ingress Controller 迁移到 Traefik。

NGINX Ingress Controller 退役

Kubernetes NGINX Ingress Controller 项目已宣布于 2026 年 3 月退役,之后将不再获得更新或安全补丁。Traefik 通过支持 NGINX 注解提供迁移途径,让您无需重写全部 Ingress 配置即可迁移工作负载。

→ 请参阅 NGINX 到 Traefik 迁移指南,获取分步操作说明。

有关 NGINX Ingress Controller 退役的更多信息,请参阅 Kubernetes 官方博客公告。

要求

不使用 Helm Chart 安装 Traefik 时,请确保添加或更新 Traefik Kubernetes Ingress NGINX 提供者所需的 RBAC。

命名空间选择器所需的额外 RBAC

使用 watchNamespaceSelector 选项时,Traefik 需要列出和监听命名空间的权限。下面的 RBAC 配置已包含这些权限。

# Install RBAC for Traefik Ingress NGINX provider:
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-ingress-nginx-rbac.yml

Ingress 发现

默认情况下,该提供者会发现集群中的全部 Ingress;如果您同时使用标准 Kubernetes Ingress 提供者,可能会产生重复的路由器。

最佳实践:

  • 使用 IngressClass 指定应由此提供者处理的 Ingress
  • 配置 watchNamespace,将发现范围限制为单个命名空间
  • 使用 watchNamespaceSelector,根据命名空间标签选择目标 Ingress

IngressClass 选择逻辑

默认情况下,该提供者会选择所有 spec.controller 与 controllerClass(默认值为 k8s.io/ingress-nginx)匹配的 IngressClass,并处理引用其中任意一个的每个 Ingress。设置 ingressClassByName: true 会增加第二条纳入路径:名称与 ingressClass 匹配的 IngressClass 也会被纳入,即使其 spec.controller 与 controllerClass 不匹配。这不会缩小基于控制器的选择范围,两条路径会各自独立生效。

配置示例

可以按以下方式启用 Kubernetes Ingress NGINX 提供者:

providers:
  kubernetesIngressNGINX:
    # Namespace discovery
    watchNamespace: "default"
    # OR use namespace selector (mutually exclusive with watchNamespace)
    # watchNamespaceSelector: "environment=production"

    # IngressClass configuration
    ingressClass: "nginx"
    controllerClass: "k8s.io/ingress-nginx"
    watchIngressWithoutClass: false
    ingressClassByName: false
    globalAuthURL: "http://foo.com/auth"
    proxyConnectTimeout: 60
    proxyReadTimeout: 60
    proxySendTimeout: 60
    proxyRequestBuffering: false
    clientBodyBufferSize: "16384" # 16k
    proxyBuffering: false
    proxyBodySize: "1048576"      # 1m
    proxyBufferSize: "8192"       # 8k
    proxyBuffersNumber: 4
    upstreamKeepaliveTimeout: 60
    customHTTPErrors:
      - "404"
      - "503"
    allowCrossNamespaceResources: true
    allowSnippetAnnotations: false
    globalAllowedResponseHeaders:
      - "X-Custom-Header1"
      - "X-Custom-Header2"
    ipAllowListStrategy:
      depth: 2
    strictValidatePathType: false
[providers.kubernetesIngressNGINX]
  # Namespace discovery
  watchNamespace = "default"
  # OR use namespace selector (mutually exclusive with watchNamespace)
  # watchNamespaceSelector = "environment=production"

  # IngressClass configuration
  ingressClass = "nginx"
  controllerClass = "k8s.io/ingress-nginx"
  watchIngressWithoutClass = false
  ingressClassByName = false
  globalAuthURL = "http://foo.com/auth"
  proxyConnectTimeout = 60
  proxyReadTimeout = 60
  proxySendTimeout = 60
  proxyRequestBuffering = false
  clientBodyBufferSize = "16384" # 16k
  proxyBuffering = false
  proxyBodySize = "1048576"      # 1m
  proxyBufferSize = "8192"       # 8k
  proxyBuffersNumber = 4
  upstreamKeepaliveTimeout = 60
  customHTTPErrors = ["404", "503"]
  allowCrossNamespaceResources = true
  allowSnippetAnnotations = false
  globalAllowedResponseHeaders = ["X-Custom-Header1", "X-Custom-Header2"]
  strictValidatePathType = false

[providers.kubernetesIngressNGINX.ipAllowListStrategy]
  depth = 2
--providers.kubernetesingressnginx=true
--providers.kubernetesingressnginx.watchnamespace=default
--providers.kubernetesingressnginx.ingressclass=nginx
--providers.kubernetesingressnginx.controllerclass=k8s.io/ingress-nginx
--providers.kubernetesingressnginx.watchingresswithoutclass=false
--providers.kubernetesingressnginx.ingressclassbyname=false
--providers.kubernetesingressnginx.globalauthurl=http://foo.com/auth
--providers.kubernetesingressnginx.proxyconnecttimeout=60
--providers.kubernetesingressnginx.proxyreadtimeout=60
--providers.kubernetesingressnginx.proxysendtimeout=60
--providers.kubernetesingressnginx.proxyrequestbuffering=false
--providers.kubernetesingressnginx.clientbodybuffersize=16384 # 16k
--providers.kubernetesingressnginx.proxybuffering=false
--providers.kubernetesingressnginx.proxybodysize=1048576      # 1m
--providers.kubernetesingressnginx.proxybuffersize=8192       # 8k
--providers.kubernetesingressnginx.proxybuffersnumber=4
--providers.kubernetesingressnginx.upstreamkeepalimetimeout=60
--providers.kubernetesingressnginx.customhttperrors=404,503
--providers.kubernetesingressnginx.allowCrossNamespaceResources=true
--providers.kubernetesingressnginx.allowsnippetannotations=false
--providers.kubernetesingressnginx.globalAllowedResponseHeaders=X-Custom-Header1,X-Custom-Header2
--providers.kubernetesingressnginx.ipallowliststrategy.depth=2
--providers.kubernetesingressnginx.strictvalidatepathtype=false
providers:
  kubernetesIngressNginx:
    # -- Enable Kubernetes Ingress NGINX provider
    enabled: true

    # Namespace discovery
    # -- Namespace the controller watches for updates to Kubernetes objects
    # When using rbac.namespaced, it will watch helm release namespace and namespaces listed in this array
    namespaces:
      - default
    # OR use namespace selector (mutually exclusive with namespaces)
    # namespaceSelector: "environment=production"

    # IngressClass configuration
    # -- Name of the ingress class this controller satisfies
    ingressClass: "nginx"
    # -- Ingress Class Controller value this controller satisfies
    controllerClass: "k8s.io/ingress-nginx"
    # -- Define if Ingress Controller should also watch for Ingresses without an IngressClass or the annotation specified
    watchIngressWithoutClass: false
    # -- Define if Ingress Controller should watch for Ingress Class by Name together with Controller Class
    ingressClassByName: false

该提供者监听传入的 Ingress 事件,并自动将 NGINX 注解转换为 Traefik 动态配置,创建相应的路由器、服务、中间件,以及将流量路由至集群服务所需的其他组件。

配置选项

字段 说明 默认值 必填
providers.providers
ThrottleDuration
配置重新加载后,等待至少这么长时间,才会处理任何新的配置刷新事件。
如果在此期间发生多个事件,只会处理最新事件,其余事件全部丢弃。
此选项不能针对单个提供者设置,但节流算法会独立应用于每个提供者。
2s 否
providers.
kubernetesIngressNGINX.
endpoint
服务器端点 URL。
更多信息请参阅此处。
"" 否
providers.
kubernetesIngressNGINX.
token
用于 Kubernetes 客户端配置的 Bearer 令牌。 "" 否
providers.
kubernetesIngressNGINX.
certAuthFilePath
证书颁发机构文件的路径。
用于 Kubernetes 客户端配置。
"" 否
providers.
kubernetesIngressNGINX.
throttleDuration
生成新配置前,两个 Kubernetes 事件之间至少需要等待的时间。
这可以防止每秒更新多次的 Kubernetes 集群持续修改 Traefik 配置。
留空则捕获每个事件。
0s 否
providers.
kubernetesIngressNGINX.
globalAuthURL
为所有位置提供身份认证的服务 URL。每个 Ingress 上的 auth-url 注解优先于此选项。 "" 否
providers.
kubernetesIngressNGINX.
watchNamespace
控制器监听 Kubernetes 对象更新的命名空间。此参数留空则监听所有命名空间。 "" 否
providers.
kubernetesIngressNGINX.
watchNamespaceSelector
选择器,用于选择控制器监听 Kubernetes 对象更新的命名空间。 "" 否
providers.
kubernetesIngressNGINX.
ingressClass
此控制器处理的 IngressClass 的名称。ingressClassByName 为 true 时,此名称的 IngressClass 都会被纳入发现范围,与其 spec.controller 的值无关。 "nginx" 否
providers.
kubernetesIngressNGINX.
controllerClass
此控制器所满足的 Ingress Class Controller 值。 "k8s.io/ingress-nginx" 否
providers.
kubernetesIngressNGINX.
watchIngressWithoutClass
定义 Ingress 控制器是否也应监听未指定 IngressClass 或相应注解的 Ingress。 false 否
providers.
kubernetesIngressNGINX.
ingressClassByName
为 true 时,任何名称与 ingressClass 匹配的 IngressClass 都会被纳入发现范围,即使其 spec.controller 与 controllerClass 不匹配。它会与基于控制器的选择同时评估,而不是替代后者。 false 否
providers.
kubernetesIngressNGINX.
publishService
位于 Ingress 控制器前方的服务。格式为 namespace/name。 "" 否
providers.
kubernetesIngressNGINX.
publishStatusAddress
用于设置此控制器所处理 Ingress 对象的负载均衡器状态的自定义地址(多个地址以逗号分隔)。 "" 否
providers.
kubernetesIngressNGINX.
defaultBackendService
用于处理不匹配任何已知服务器名称的 HTTP 请求的服务(兜底服务)。格式为 'namespace/name'。 "" 否
providers.
kubernetesIngressNGINX.
disableSvcExternalName
禁用对 ExternalName 类型服务的支持。 false 否
providers.
kubernetesIngressNGINX.
proxyConnectTimeout
等待与服务器建立连接的时长。该值不带单位,以秒计。未配置 Ingress 专属超时时,此值用作全局连接超时。可通过 nginx.ingress.kubernetes.io/proxy-connect-timeout 注解配置 Ingress 专属超时。 60 否
providers.
kubernetesIngressNGINX.
proxyReadTimeout
两次连续读取操作之间的时长。该值不带单位,以秒计。未配置 Ingress 专属超时时,此值用作全局读取超时。可通过 nginx.ingress.kubernetes.io/proxy-read-timeout 注解配置 Ingress 专属超时。 60 否
providers.
kubernetesIngressNGINX.
proxySendTimeout
两次连续写入操作之间的时长。该值不带单位,以秒计。未配置 Ingress 专属超时时,此值用作全局发送超时。可通过 nginx.ingress.kubernetes.io/proxy-send-timeout 注解配置 Ingress 专属超时。 60 否
providers.
kubernetesIngressNGINX.
proxyrequestbuffering
定义是否默认为所有 Ingress 启用请求缓冲。 false 否
providers.
kubernetesIngressNGINX.
clientBodyBufferSize
读取客户端请求体的默认缓冲区大小,单位为字节。 16384 否
providers.
kubernetesIngressNGINX.
proxybuffering
定义是否默认为所有 Ingress 启用响应缓冲。 false 否
providers.
kubernetesIngressNGINX.
proxyBodySize
客户端请求体的默认最大大小,单位为字节。 1048576 否
providers.
kubernetesIngressNGINX.
proxyBufferSize
读取响应体的默认缓冲区大小,单位为字节。 8192 否
providers.
kubernetesIngressNGINX.
proxyBuffersNumber
读取响应的默认缓冲区数量。 4 否
providers.
kubernetesIngressNGINX.
proxyNextUpstream
定义在哪些情况下重试请求。接受以下值组成的空格分隔列表:error、timeout、http_XXX(例如 http_502)、non_idempotent 和 off(禁用重试)。未配置 Ingress 专属值时,此值用作全局 proxy-next-upstream 配置。可通过 nginx.ingress.kubernetes.io/proxy-next-upstream 注解设置 Ingress 专属配置。 "error timeout" 否
providers.
kubernetesIngressNGINX.
proxyNextUpstreamTries
限制后端服务器未响应时可以尝试的次数。0 表示不限次数,但实际最多为可用服务器的数量。未配置 Ingress 专属值时,此值用作全局重试次数配置。可通过 nginx.ingress.kubernetes.io/proxy-next-upstream-tries 注解设置 Ingress 专属重试上限。 3 否
providers.
kubernetesIngressNGINX.
proxyNextUpstreamTimeout
限制后端服务器未响应时重试请求的总耗时。超时值不带单位,以秒计。0 表示不超时。未配置 Ingress 专属值时,此值用作全局重试超时。可通过 nginx.ingress.kubernetes.io/proxy-next-upstream-timeout 注解设置 Ingress 专属重试超时。 0 否
providers.
kubernetesIngressNGINX.
upstreamKeepaliveTimeout
定义到上游服务器的 keep-alive 连接的空闲超时。该值不带单位,以秒计。 60 否
providers.
kubernetesIngressNGINX.
customHTTPErrors
定义哪些状态应调用默认后端以返回错误页面。 [] 否
providers.
kubernetesIngressNGINX.
allowCrossNamespaceResources
允许 Ingress 引用其他命名空间中的资源(例如 ConfigMap、Secret)。 false 否
providers.
kubernetesIngressNGINX.
globalAllowedResponseHeaders
自定义头部注解中允许的响应头列表。必须配置此项,自定义头部注解才会生效。 [] 否
providers.
kubernetesIngressNGINX.
ipAllowListStrategy
定义用于 allowlist-source-range 和 whitelist-source-range 注解的客户端 IP 判定策略。设置后,该策略会应用于每个生成的 IPAllowList 中间件。 - 否
providers.
kubernetesIngressNGINX.
ipAllowListStrategy.
depth
从 X-Forwarded-For 头中提取客户端 IP 时要跳过的可信代理跳数。0 表示禁用基于深度的提取。 0 否
providers.
kubernetesIngressNGINX.
ipAllowListStrategy.
excludedIPs
扫描 X-Forwarded-For 头以查找客户端 IP 时要排除的 IP 列表。 [] 否
providers.
kubernetesIngressNGINX.
ipAllowListStrategy.
ipv6Subnet
检查允许列表时,用于对 IPv6 地址进行分组的 IPv6 子网大小。0 表示禁用子网分组。 0 否
providers.
kubernetesIngressNGINX.
httpentrypoint
定义 HTTP 请求使用的入口点。 "" 否
providers.
kubernetesIngressNGINX.
httpsentrypoint
定义 HTTPS 请求使用的入口点。 "" 否
providers.
kubernetesIngressNGINX.
strictValidatePathType
定义当任意路径包含正则表达式字符且 pathType 为 Prefix 或 Exact 时,是否拒绝整个 Ingress。 true 否

endpoint

Kubernetes 服务器的端点 URL。

部署到 Kubernetes 中时,Traefik 会读取环境变量 KUBERNETES_SERVICE_HOST 和 KUBERNETES_SERVICE_PORT,或 KUBECONFIG,以构造端点。

访问令牌从 /var/run/secrets/kubernetes.io/serviceaccount/token 读取,SSL CA 证书从 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt 读取。部署在 Kubernetes 内部时,两者都会自动挂载。

可以指定端点,以覆盖集群内环境变量的值。

找不到环境变量时,Traefik 会尝试使用集群外客户端连接 Kubernetes API 服务器。

这种情况下必须指定端点。具体而言,可以将其设置为 kubectl proxy 使用的 URL,以使用关联 kubeconfig 授予的身份认证和授权连接 Kubernetes 集群。

providers:
  kubernetesIngressNGINX:
    endpoint: "http://localhost:8080"
    # ...
[providers.kubernetesIngressNGINX]
  endpoint = "http://localhost:8080"
  # ...
--providers.kubernetesingressnginx.endpoint=http://localhost:8080

路由配置

请参阅路由中的专门章节。


在生产环境使用 Traefik OSS?

如果你在工作中使用 Traefik,可以考虑为 Traefik OSS 增加企业级 API 网关能力或商业支持。

为 Traefik OSS 增加 API 网关能力快捷且平滑,无需推倒重来,现有配置也会完整保留。请通过这个简短视频了解实际效果。


版权所有 © 头文件软件工作室

文档由 HeadFile Studio 翻译。

Traefik v3.7 中文快照 · 原文版权归 Traefik Labs 及贡献者所有 · MIT 许可证