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=falseproviders:
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.providersThrottleDuration |
配置重新加载后,等待至少这么长时间,才会处理任何新的配置刷新事件。 如果在此期间发生多个事件,只会处理最新事件,其余事件全部丢弃。 此选项不能针对单个提供者设置,但节流算法会独立应用于每个提供者。 |
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 网关能力快捷且平滑,无需推倒重来,现有配置也会完整保留。请通过这个简短视频了解实际效果。