从 Ingress NGINX Controller 迁移到 Traefik零停机迁移完整实战指南【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik本文基于 Traefik 官方迁移文档《Migrate from Ingress NGINX Controller to Traefik》整理面向需要在 Kubernetes 集群中完成入口控制器替换的运维与平台工程师。由于 Kubernetes Ingress NGINX Controller 项目已宣布于 2026 年 3 月退役此后不再有版本更新、安全补丁和缺陷修复这篇指南会带你走完迁移的全过程将 ingress-nginx 的集群级 ConfigMap 全局配置翻译为 Traefik 的对应配置、在 NGINX 旁路安装 Traefik 并利用其 Kubernetes Ingress NGINX Provider 自动翻译 NGINX 注解、通过 DNS 渐进切流验证、处理双控制器共存时的 Ingress status 竞争问题最后以保留nginxIngressClass 的方式卸载 NGINX——全程零停机。读完本文你可以直接照做完成一次生产级迁移。迁移完成后你将得到什么完成迁移后你现有的 Ingress 资源无需任何修改即可由 Traefik 接管。Traefik 的 Kubernetes Ingress NGINX Provider 会自动把 NGINX 注解翻译为 Traefik 路由配置。你的 Ingress 保持原样apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: myapp annotations: # 这些 NGINX 注解会被 Traefik 自动翻译 nginx.ingress.kubernetes.io/ssl-redirect: true nginx.ingress.kubernetes.io/force-ssl-redirect: true nginx.ingress.kubernetes.io/enable-cors: true nginx.ingress.kubernetes.io/cors-allow-origin: https://example.com nginx.ingress.kubernetes.io/affinity: cookie nginx.ingress.kubernetes.io/session-cookie-name: route spec: ingressClassName: nginx # ← Traefik 会监听这个 class rules: - host: myapp.example.com http: paths: - path: / pathType: Prefix backend: service: name: whoami port: number: 80对应的 Service 与 Deployment 同样无需改动apiVersion: apps/v1 kind: Deployment metadata: name: 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: - protocol: TCP port: 80 targetPort: 80支持的注解完整清单及各注解在两种控制器下的行为差异参见 Ingress NGINX 路由配置参考。版本要求Kubernetes Ingress NGINX Provider 要求Traefik v3.6.2 或更高版本。Legacy Scheme 头兼容如果你的应用仍依赖 ingress-nginx 的旧版X-Forwarded-Scheme或X-Scheme头可在入口点开启entryPoints.name.forwardedHeaders.addXForwardedSchemeHeaderstrue。该选项保持X-Forwarded-Proto不变并在入口点层面为所有 Provider 恢复兼容头。这一行为在源码中可以直接印证入口点静态配置中的AddXForwardedSchemeHeaders字段会传入转发头中间件XForwarded处理器在启用时读取X-Forwarded-Proto的值并写入X-Forwarded-Scheme等兼容头。注解是如何被自动翻译的源码视角从源码结构看这套注解翻译机制的核心是一张注解映射表IngressConfig结构体用annotation标签把每一个nginx.ingress.kubernetes.io/*注解对应到一个具名字段覆盖认证Basic/ForwardAuth/客户端证书、SSL 重定向与 passthrough、正则重写、CORS、会话粘性、限速limit-rpm/limit-rps/limit-burst-multiplier/limit-connections、缓冲与超时、Canary 等类别。解析过程由parseIngressConfig基于反射完成布尔值按strings.EqualFold(val, true)解析整数字段解析失败则忽略字符串列表按逗号分隔。这也解释了一个实用细节——注解值写错如布尔字段写yes时该注解会被静默丢弃迁移后遇到注解不生效时应优先核对取值格式。迁移前准备开始前请确认以下条件集群中已有运行中的 Ingress NGINX Controller已配置kubectl并具备集群访问权限集群支持同时在 80/443 端口运行多个 LoadBalancer 服务已安装Helm具备创建 RBAC 资源的集群管理员权限已备份关键配置Ingress 资源、ConfigMap、Secret。备份建议# 导出所有 Ingress 资源 kubectl get ingress --all-namespaces -o yaml ingress-backup.yaml # 导出 NGINX ConfigMaps kubectl get configmap --all-namespaces -l app.kubernetes.io/nameingress-nginx -o yaml nginx-configmaps.yaml迁移策略总览迁移通过Traefik 与 NGINX 并行运行实现零停机两个控制器同时服务同一批 Ingress 资源允许你先验证、再逐步切流最后移除 NGINX。现状: DNS → LoadBalancer → NGINX → 你的服务 迁移中: DNS → LoadBalancer → NGINX → 你的服务 → LoadBalancer → Traefik → 你的服务 最终: DNS → LoadBalancer → Traefik → 你的服务迁移流程Step 0— 审查 ingress-nginx ConfigMap把集群级默认值翻译为 Traefik 配置Step 1— 与 NGINX 并行安装 TraefikStep 2— 验证 Traefik 已能处理流量Step 3— 将流量从 NGINX 逐步切换到 TraefikStep 4— 从 DNS 移除 NGINX、保留 IngressClass 并卸载Step 0迁移全局 ConfigMap 设置在安装 Traefik 之前先审查当前ingress-nginxConfigMap 中的全局默认值。ingress-nginx 中控制器 ConfigMap 是一层集群级配置而在 Traefik 中同样的能力被拆分到providers.kubernetesIngressNGINX静态配置——ingress-nginx 兼容默认值entryPoints——监听器行为如 HTTP 到 HTTPS 重定向、PROXY 协议动态tls.options与 HTTP 中间件——TLS 策略、HSTS 及其他头行为Traefik 访问日志配置——请求日志先导出当前 ConfigMap 并检查你自定义过的键kubectl get configmap --all-namespaces -l app.kubernetes.io/nameingress-nginx,app.kubernetes.io/componentcontroller -o yaml这个标签选择器可以在任意命名空间、任意 release 名下定位控制器 ConfigMap。单位换算提醒多个 ingress-nginx ConfigMap 键使用 NGINX 风格值如16k、1m、30s而 Traefik 对应的providers.kubernetesIngressNGINX选项要求请求体/缓冲类设置使用原始字节数proxyConnectTimeout、proxyNextUpstreamTimeout使用整数秒proxyRequestBuffering、proxyBuffering使用布尔值ConfigMap 到 Traefik 的映射表ingress-nginx ConfigMap 键Traefik 对应项provider 选项说明proxy-connect-timeoutproxyConnectTimeout使用整数秒。proxy-request-bufferingproxyRequestBufferingon/off转为true/false。注意 ingress-nginx 默认开启请求缓冲而 Traefik 默认false。client-body-buffer-sizeclientBodyBufferSize如把16k换算为字节。proxy-bufferingproxyBufferingon/off转为true/false。proxy-body-sizeproxyBodySize如把1m换算为字节。proxy-buffer-sizeproxyBufferSize如把8k换算为字节。proxy-buffers-numberproxyBuffersNumber保持整数值。proxy-next-upstreamproxyNextUpstream空格分隔的重试条件列表如error timeout http_502。proxy-next-upstream-timeoutproxyNextUpstreamTimeout使用整数秒。proxy-next-upstream-triesproxyNextUpstreamTries保持整数值。custom-http-errorscustomHTTPErrors若想要全局错误页服务同时配置providers.kubernetesIngressNGINX.defaultBackendService。global-allowed-response-headersglobalAllowedResponseHeadersnginx.ingress.kubernetes.io/custom-headers注解生效的前提。allow-cross-namespace-resourcesallowCrossNamespaceResources迁移后的 Ingress 需要引用其他命名空间资源时使用。strict-validate-path-typestrictValidatePathTypeTraefik v3.7 默认该选项为true。ssl-redirect/force-ssl-redirectnginx.ingress.kubernetes.io/ssl-redirect与nginx.ingress.kubernetes.io/force-ssl-redirect注解或集群级 entryPoint 重定向注解存在时 Traefik 会翻译全局默认则在web入口点配置 HTTP→HTTPS 重定向需要显式选择入口点时设置providers.kubernetesIngressNGINX.httpEntryPoint/httpsEntryPoint。ssl-protocols/ssl-ciphersTLS 选项通过入口点 TLS 选项全局应用或通过traefik.ingress.kubernetes.io/router.tls.options按 Ingress 指定。hsts、hsts-max-age、hsts-include-subdomains、hsts-preloadHeaders 中间件使用stsSeconds、stsIncludeSubdomains、stsPreload、forceSTSHeader把中间件挂到入口点上即形成集群级默认。use-proxy-protocol入口点proxyProtocol配置配置在每一个后面接说 PROXY 协议负载均衡器的入口点上。access-log-pathaccessLog.filePath静态配置。log-format-upstreamaccessLog.format使用 Traefik 内置common、genericCLF或json格式自定义 NGINX 日志格式模板没有 1:1 等价物。这些选项在源码中集中定义于 Provider 结构体默认值则由SetDefaults对齐 NGINX 原生默认连接/读/写超时各 60 秒、proxyBodySize1MB、clientBodyBufferSize16KB、proxyBufferSize8KB、proxyBuffersNumber4、重试 3 次、strictValidatePathType为true。也就是说如果你的 ConfigMap 没有自定义这些项Traefik 侧可以不配置直接获得等价行为。没有直接等价项的 ConfigMap 键一些键是 NGINX 特有的迁移时可以丢弃因为 Traefik 不暴露原始 NGINX 内部机制。常见例子worker 调优类worker-processes、worker-cpu-affinity、Lua shared dict 设置snippet 类键main-snippet、http-snippet、server-snippet、location-snippet、stream-snippetTraefik 内置访问日志格式之外的自定义 NGINX 日志格式模板遇到这类键时应翻译其背后的意图而不是照抄指令。参考文档Kubernetes Ingress NGINX Provider 安装配置Traefik TLS OptionsTraefik Headers 中间件Traefik EntryPoints 配置Step 1与 NGINX 并行安装 Traefik先读 status 竞争说明双控制器服务同一批 Ingress 会竞争status.loadBalancer.ingress[]字段。安装前请先看 Step 3 中的 Ingress Status 竞争条件 一节决定采用哪种缓解措施在 Traefik 上禁用publishService或使用过渡 IngressClass。如果你尚未安装 Ingress NGINX Controller可用以下命令先装一个helm upgrade --install ingress-nginx ingress-nginx --repo https://kubernetes.github.io/ingress-nginx --namespace ingress-nginx --create-namespace。启用 Kubernetes Ingress NGINX Provider 安装 Traefik两个控制器将同时服务相同的 Ingress 资源# 添加 Traefik Helm 仓库 helm repo add traefik https://traefik.github.io/charts helm repo update # 安装 Traefik helm upgrade --install traefik traefik/traefik \ --namespace traefik --create-namespace \ --set providers.kubernetesIngressNGINX.enabledtrue或者使用 values 文件做更多配置traefik-values.yamlproviders: kubernetesIngressNGINX: enabled: truehelm upgrade --install traefik traefik/traefik \ --namespace traefik --create-namespace \ --values traefik-values.yaml验证两个控制器都在运行# 查看 NGINX Pod kubectl get pods -n ingress-nginx # 查看 Traefik Pod kubectl get pods -n traefik # 确认两个服务都有 LoadBalancer IP kubectl get svc -n ingress-nginx ingress-nginx-controller kubectl get svc -n traefik traefik此时 NGINX 与 Traefik 都在运行且都能服务同一批 Ingress 资源DNS 仍指向 NGINX 的 LoadBalancer所以流量仍只走 NGINX。Step 2验证 Traefik 正在处理流量把 Traefik 加进 DNS 之前先确认它能正确服务你的 Ingress 资源。通过 Traefik 的 LoadBalancer IP 测试取出 Traefik 的 LoadBalancer IP用--resolve在不改 DNS 的情况下测试# 获取 LoadBalancer IP NGINX_IP$(kubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}) TRAEFIK_IP$(kubectl get svc -n traefik traefik -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}) echo -e Nginx IP: $NGINX_IP\nTraefik IP: $TRAEFIK_IP # 两边分别测 HTTP FQDNmyapp.example.com # 观察 HTTPS 重定向行为 curl --connect-to ${FQDN}:80:${NGINX_IP}:80 http://${FQDN} -D - curl --connect-to ${FQDN}:80:${TRAEFIK_IP}:80 http://${FQDN} -D - # 注意响应头 X-Forwarded-Server 应为 traefik # 两边分别测 HTTPS curl --connect-to ${FQDN}:443:${NGINX_IP}:443 https://${FQDN} curl --connect-to ${FQDN}:443:${TRAEFIK_IP}:443 https://${FQDN}TLS 证书注意HTTPS 测试要成功NGINX 和 Traefik 都必须持有有效证书。由于验证阶段 Traefik 不对外暴露Lets Encrypt HTTP challenge 无法工作。过渡期证书方案现有tls.secretName证书—— 如果你用 cert-manager 等外部工具spec.tls引用的现有 TLS secret 在两个控制器上都能工作Lets Encrypt DNS challenge—— 配置 Traefik 的 ACME DNS challenge无需公网暴露即可申请证书。不要用curl -k跳过证书校验它掩盖的 TLS 配置问题会在迁移后变成事故。验证 Ingress 发现情况查看 Traefik 日志确认它已发现你的 Ingress 资源kubectl logs -n traefik deployment/traefik | grep -i ingressStep 3把流量切换到 Traefik两个控制器都已验证无误后开始渐进切流。方案 A基于 DNS 的迁移把 Traefik 的 LoadBalancer IP 加入 DNS 记录与 NGINX 并存让两个控制器同时收流量。获取 LoadBalancer 地址# NGINX LoadBalancer echo $(kubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}) # Traefik LoadBalancer echo $(kubectl get svc -n traefik traefik -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }})渐进式 DNS 迁移五步把 Traefik 加入 DNS—— 两个 IP 开始轮询接收流量观察—— 监控两侧流量模式从 DNS 移除 NGINX—— 确认无误后删除 NGINX IP 记录等待 DNS 传播—— 给缓存过期留时间卸载 NGINX—— 进入 Step 4。DNS TTL 提醒部分 ISP 为省流量会忽略 TTL 值、把记录缓存得比指定时间更长。从 DNS 移除 NGINX 后保持 NGINX 至少再运行 24–48 小时再卸载避免旧缓存用户掉流量。Ingress Status 竞争条件双控制器共存时当两个控制器管理同一批 Ingress同为ingressClassName: nginx时双方都会把 LoadBalancer 地址写入每个 Ingress 的status.loadBalancer.ingress[]。每次协调循环里它们互相覆盖对方日志中没有报错只是两侧反复出现Updated ingress status信息行。路由本身不受影响——共存窗口内两个控制器都正常服务流量。但 flapping 的 status 字段会影响所有观察它的一方ExternalDNS可能在两个 LoadBalancer IP 之间来回改 DNS 记录kube-state-metrics、监控看板与告警规则ArgoCD、Flux 等 GitOps 工具会对每个受影响的 Ingress 报告永久漂移任何基于 Ingress status 字段做协调的自定义 Operator从源码看这一行为有据可查Provider 的updateIngressStatus在每次loadConfiguration后为名下每个 Ingress 回写状态——PublishService为空且未配置publishStatusAddress时直接返回LoadBalancer 类型 Service 则把service.Status.LoadBalancer.Ingress复制进 status。这既解释了竞争从何而来也给出了缓解手段的开关位置。推荐缓解方案 1共存期间在 Traefik 上禁用 status 发布以publishService禁用状态安装 Traefik# traefik-values.yaml providers: kubernetesIngressNginx: enabled: true publishService: enabled: false # 禁止写 statusTraefik 照常服务 Ingress只是不再写 status 字段NGINX 成为唯一写入方。用 port-forward 或独立测试域名 测试 TraefikExternalDNS 用户让 NGINX 发布 Traefik 的服务地址使 ExternalDNS 把流量指到 Traefik# nginx-values.yaml controller: publishService: pathOverride: traefik/traefik # 指向 Traefik 的服务验证流量走 Traefik—— 此时仍可回滚移除pathOverride即可在 Traefik 上重新启用publishService并进入 Step 4 卸载 NGINX。备选缓解方案 2过渡 IngressClass给迁移中的 NGINX 一个不同的 IngressClass例如nginx-migration让两个控制器不同时拥有同一批 Ingress从而彻底避免 status 竞争——代价是用一个短暂的流量切换步骤替代渐进 DNS 切流。方案 B外部负载均衡器 权重分流需要更精细控制时在两个 Kubernetes LoadBalancer 前面放一个外部负载均衡器Traefik、Cloudflare、AWS ALB 或专用 LB 均可。基础设施前提此方案假定你已有外部负载均衡器或愿意在迁移开始前搭建一个。新增外部 LB 是独立的基础设施变更应与入口控制器迁移分开规划与测试。设置步骤建一个指向 NGINX Kubernetes LoadBalancer 的外部 LBDNS 指向外部 LB把 Traefik Kubernetes LoadBalancer 以低权重如 10%加入外部 LB逐步调高 Traefik 权重、调低 NGINX 权重NGINX 无流量后卸载它。权重推进示例阶段NGINX 权重Traefik 权重持续时间初始100%0%-启动90%10%1 小时提升50%50%2 小时接近完成10%90%4 小时最终0%100%-常见外部 LB 选项Cloudflare Load Balancing带健康检查的流量引导、AWS Global Accelerator加权路由、Google Cloud Load Balancing流量分割、自建 Traefik / HAProxy / NGINX 等。LoadBalancer IP 保留若希望 Traefik 最终使用与 NGINX 相同的 LoadBalancer IP简化 DNS 管理可以在迁移后转移 IP。由于 Traefik 已带着自己的 LoadBalancer 在运行这可以零停机完成Traefik 已带自己的 LoadBalancer IP 运行Step 1把 Traefik IP 加入 DNS流量同时流向 NGINX 和 Traefik从 DNS 移除 NGINX IP 并等待传播删除 NGINX 的 LoadBalancer 服务以释放 IP升级 Traefik 认领释放出来的 IP可选新 IP 生效后从 DNS 移除 Traefik 旧 IP。整个转移过程中流量始终在流向 Traefik。获取当前 NGINX LoadBalancer IPkubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}AWSNLB 弹性 IPAWS Classic LB 不支持静态 IP应使用带弹性 IP 的 NLB前提是集群已安装 AWS Load Balancer Controller。# 预先分配弹性 IP每个可用区一个 aws ec2 allocate-address --domain vpc --region your-region # 记下每个 EIP 的 AllocationIdeipalloc-xxxtraefik-values.yaml更新service: type: LoadBalancer loadBalancerClass: service.k8s.aws/nlb # 需要 AWS Load Balancer Controller annotations: service.beta.kubernetes.io/aws-load-balancer-type: external service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip service.beta.kubernetes.io/aws-load-balancer-eip-allocations: eipalloc-xxx,eipalloc-yyyAzure支持 LB 静态公网 IP。# 定位现有公网 IP az network public-ip list --resource-group your-resource-group \ --query [?ipAddressyour-ip].name -o tsvservice: type: LoadBalancer annotations: # 仅当公网 IP 与 AKS 集群不在同一资源组时需要 service.beta.kubernetes.io/azure-load-balancer-resource-group: public-ip-resource-group spec: loadBalancerIP: your-existing-ipGCP通过预留区域静态 IP 实现。# 列出现有静态 IP gcloud compute addresses list # 或预留新的区域静态 IP必须与 GKE 集群同区域 gcloud compute addresses create traefik-ip --region your-cluster-regionservice: type: LoadBalancer spec: loadBalancerIP: your-static-ipOVHcloudOVHcloud 公网 LB 基于 OpenStack Octavia为 LoadBalancer 服务分配 floating IP需要集群中安装 OpenStack Cloud Controller ManagerMKS 用户已自带。保留现有 floating IP 的做法# 定位现有公网 IP NGINX_IP$(kubectl get svc -n ingress-nginx ingress-nginx-controller \ -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}) echo NGINX IP: $NGINX_IP# 给现有 NGINX LoadBalancer 服务加注解防止删除时释放 floating IP kubectl annotate svc my-lb-svc loadbalancer.openstack.org/keep-floatingiptruekeep-floatingip注解可阻止服务删除/修改时释放 floating IP。随后删除 NGINX LoadBalancer 服务、更新traefik-values.yamlservice: type: LoadBalancer spec: loadBalancerIP: your-existing-floating-ip其他云DigitalOcean 支持 floating IP 的loadBalancerIPLinode 支持loadBalancerIP裸机可结合 MetalLB 使用 IP 地址池。转移 IP 操作DNS 已指向 Traefik、values 已配好目标 IP 后# 确认 Traefik 已在通过当前 LoadBalancer 接收流量 kubectl get svc -n traefik traefik # 删除 NGINX LoadBalancer 服务以释放 IP kubectl delete svc -n ingress-nginx ingress-nginx-controller # 升级 Traefik 认领已释放的 IP helm upgrade traefik traefik/traefik \ --namespace traefik \ --values traefik-values.yaml # 确认 Traefik 拿到了原 NGINX 的 IP kubectl get svc -n traefik traefik零停机提示Helm 升级只会重启 Traefik Pod不会动 LoadBalancer 服务。Traefik 默认RollingUpdate部署策略新 Pod 先起来旧 Pod 再退出。为更稳妥建议配置高可用# traefik-values.yaml deployment: replicas: 2 # 把 Pod 打散到不同节点以容忍节点故障 affinity: podAntiAffinity: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchLabels: app.kubernetes.io/name: traefik app.kubernetes.io/instance: traefik topologyKey: kubernetes.io/hostname # 确保扰动期间至少一个 Pod 可用 podDisruptionBudget: enabled: true minAvailable: 1多副本打散 PodDisruptionBudget 可保证升级和节点维护期间至少有一个 Pod 在运行。Step 4卸载 Ingress NGINX ControllerNGINX 不再接收流量后将其移出集群。卸载前必须确保nginxIngressClass 被保留——Traefik 需要它继续发现你的 Ingress。保留 IngressClassHelm 安装的 NGINX添加helm.sh/resource-policy: keep注解让 Helm 保留 IngressClass# 添加所需注解 helm upgrade ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx \ --reuse-values \ --set-json controller.ingressClassResource.annotations{helm.sh/resource-policy: keep} # 确认注解确实生效 kubectl describe ingressclass nginx--reuse-values很关键——它保留你现有的全部 NGINX 配置没有它Helm 会把所有值重置为默认可能弄坏你的部署。注意kubectl annotate/patch/edit加注解无效。Helm 在内部保存 release 状态卸载时检查的是其内部清单中的注解而不是集群里的实时状态只有helm upgrade才能更新 Helm 的内部状态。GitOpsArgoCD、Flux安装的 NGINX在仓库中把nginxIngressClass 定义为独立资源与 NGINX Helm release 分离# ingressclass.yaml apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: nginx spec: controller: k8s.io/ingress-nginx手动安装的 NGINX直接创建独立 IngressClass 资源kubectl apply -f - EOF apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: nginx spec: controller: k8s.io/ingress-nginx EOF为什么保留的是这个spec.controller: k8s.io/ingress-nginx因为 Traefik Ingress NGINX Provider 的默认监听目标正是它SetDefaults把IngressClass默认为nginx、ControllerClass默认为k8s.io/ingress-nginx。保留原 IngressClass 对象Traefik 无需任何额外配置即可继续认领这些 Ingress。删除 NGINX 准入 Webhook为避免 NGINX 移除后 Ingress 修改出问题应删除准入 webhookkubectl delete validatingwebhookconfiguration ingress-nginx-admission kubectl delete mutatingwebhookconfiguration ingress-nginx-admission --ignore-not-found卸载 NGINXhelm uninstall ingress-nginx -n ingress-nginx如果你加过helm.sh/resource-policy: keep注解应看到These resources were kept due to the resource policy: [IngressClass] nginx release ingress-nginx uninstalled验证 IngressClass 存在kubectl get ingressclass nginx万一 IngressClass 被误删用上面保留 IngressClass一节的命令重建即可。清理 NGINX 命名空间kubectl delete namespace ingress-nginx迁移完成你已成功以零停机方式从 Ingress NGINX Controller 迁移到 Traefik。所有ingressClassName: nginx的现有 Ingress 继续工作只是现在由 Traefik 提供服务。故障排查Traefik 自带 Dashboard 可以帮助定位问题开启方式见 API Dashboard 文档。Ingress 未被 Traefik 发现# 验证 IngressClass 存在 kubectl get ingressclass nginx # 检查 Traefik provider 配置 kubectl logs -n traefik deployment/traefik | grep -i nginx\|ingress # 确认 Ingress 的 ingressClassName 正确 kubectl get ingress name -o yaml | grep ingressClassName注解行为不符合预期部分 NGINX 注解在 Traefik 中行为存在差异参见限制说明。TLS 证书不工作现有 TLS 配置在 Traefik 上照常工作——spec.tls条目保持原样Traefik 使用所引用的 secret 终结 TLSTLS secret 必须与 Ingress 位于同一命名空间NGINX 的ssl-redirect/force-ssl-redirect注解同样被遵守。# 验证 TLS secret 与 Ingress 同命名空间 kubectl get secrets -n namespace # 检查 secret 格式 kubectl get secret tls-secret-name -n namespace -o yamlLoadBalancer IP 未分配# 检查服务状态 kubectl describe svc -n traefik traefik # 查看事件 kubectl get events -n traefik --sort-by.lastTimestamp后续进阶深入了解 TraefikKubernetes Ingress NGINX 安装配置 —— Provider 配置详解Kubernetes Ingress NGINX 路由配置 —— 路由规则与注解支持HTTP 中间件 —— 超越 NGINX 注解的能力TLS 配置 —— 高级 TLS 与证书管理增强你的部署启用 指标 与 链路追踪配置访问日志完善可观测性探索 Traefik 中间件 实现高级流量管理把基于 NGINX 注解的配置迁移到 Traefik IngressRoute 或 Kubernetes Gateway API如果你使用 GitOps 管理入口资源迁移完成后将动态配置收敛到 Traefik CRDIngressRoute是自然的下一步——它提供比 Ingress 注解更精确的路由、中间件链与 TLS 控制也能顺带摆脱 Ingress status 竞争这一类控制器间协作问题。【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从 Ingress NGINX Controller 迁移到 Traefik：零停机迁移完整实战指南
从 Ingress NGINX Controller 迁移到 Traefik零停机迁移完整实战指南【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik本文基于 Traefik 官方迁移文档《Migrate from Ingress NGINX Controller to Traefik》整理面向需要在 Kubernetes 集群中完成入口控制器替换的运维与平台工程师。由于 Kubernetes Ingress NGINX Controller 项目已宣布于 2026 年 3 月退役此后不再有版本更新、安全补丁和缺陷修复这篇指南会带你走完迁移的全过程将 ingress-nginx 的集群级 ConfigMap 全局配置翻译为 Traefik 的对应配置、在 NGINX 旁路安装 Traefik 并利用其 Kubernetes Ingress NGINX Provider 自动翻译 NGINX 注解、通过 DNS 渐进切流验证、处理双控制器共存时的 Ingress status 竞争问题最后以保留nginxIngressClass 的方式卸载 NGINX——全程零停机。读完本文你可以直接照做完成一次生产级迁移。迁移完成后你将得到什么完成迁移后你现有的 Ingress 资源无需任何修改即可由 Traefik 接管。Traefik 的 Kubernetes Ingress NGINX Provider 会自动把 NGINX 注解翻译为 Traefik 路由配置。你的 Ingress 保持原样apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: myapp annotations: # 这些 NGINX 注解会被 Traefik 自动翻译 nginx.ingress.kubernetes.io/ssl-redirect: true nginx.ingress.kubernetes.io/force-ssl-redirect: true nginx.ingress.kubernetes.io/enable-cors: true nginx.ingress.kubernetes.io/cors-allow-origin: https://example.com nginx.ingress.kubernetes.io/affinity: cookie nginx.ingress.kubernetes.io/session-cookie-name: route spec: ingressClassName: nginx # ← Traefik 会监听这个 class rules: - host: myapp.example.com http: paths: - path: / pathType: Prefix backend: service: name: whoami port: number: 80对应的 Service 与 Deployment 同样无需改动apiVersion: apps/v1 kind: Deployment metadata: name: 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: - protocol: TCP port: 80 targetPort: 80支持的注解完整清单及各注解在两种控制器下的行为差异参见 Ingress NGINX 路由配置参考。版本要求Kubernetes Ingress NGINX Provider 要求Traefik v3.6.2 或更高版本。Legacy Scheme 头兼容如果你的应用仍依赖 ingress-nginx 的旧版X-Forwarded-Scheme或X-Scheme头可在入口点开启entryPoints.name.forwardedHeaders.addXForwardedSchemeHeaderstrue。该选项保持X-Forwarded-Proto不变并在入口点层面为所有 Provider 恢复兼容头。这一行为在源码中可以直接印证入口点静态配置中的AddXForwardedSchemeHeaders字段会传入转发头中间件XForwarded处理器在启用时读取X-Forwarded-Proto的值并写入X-Forwarded-Scheme等兼容头。注解是如何被自动翻译的源码视角从源码结构看这套注解翻译机制的核心是一张注解映射表IngressConfig结构体用annotation标签把每一个nginx.ingress.kubernetes.io/*注解对应到一个具名字段覆盖认证Basic/ForwardAuth/客户端证书、SSL 重定向与 passthrough、正则重写、CORS、会话粘性、限速limit-rpm/limit-rps/limit-burst-multiplier/limit-connections、缓冲与超时、Canary 等类别。解析过程由parseIngressConfig基于反射完成布尔值按strings.EqualFold(val, true)解析整数字段解析失败则忽略字符串列表按逗号分隔。这也解释了一个实用细节——注解值写错如布尔字段写yes时该注解会被静默丢弃迁移后遇到注解不生效时应优先核对取值格式。迁移前准备开始前请确认以下条件集群中已有运行中的 Ingress NGINX Controller已配置kubectl并具备集群访问权限集群支持同时在 80/443 端口运行多个 LoadBalancer 服务已安装Helm具备创建 RBAC 资源的集群管理员权限已备份关键配置Ingress 资源、ConfigMap、Secret。备份建议# 导出所有 Ingress 资源 kubectl get ingress --all-namespaces -o yaml ingress-backup.yaml # 导出 NGINX ConfigMaps kubectl get configmap --all-namespaces -l app.kubernetes.io/nameingress-nginx -o yaml nginx-configmaps.yaml迁移策略总览迁移通过Traefik 与 NGINX 并行运行实现零停机两个控制器同时服务同一批 Ingress 资源允许你先验证、再逐步切流最后移除 NGINX。现状: DNS → LoadBalancer → NGINX → 你的服务 迁移中: DNS → LoadBalancer → NGINX → 你的服务 → LoadBalancer → Traefik → 你的服务 最终: DNS → LoadBalancer → Traefik → 你的服务迁移流程Step 0— 审查 ingress-nginx ConfigMap把集群级默认值翻译为 Traefik 配置Step 1— 与 NGINX 并行安装 TraefikStep 2— 验证 Traefik 已能处理流量Step 3— 将流量从 NGINX 逐步切换到 TraefikStep 4— 从 DNS 移除 NGINX、保留 IngressClass 并卸载Step 0迁移全局 ConfigMap 设置在安装 Traefik 之前先审查当前ingress-nginxConfigMap 中的全局默认值。ingress-nginx 中控制器 ConfigMap 是一层集群级配置而在 Traefik 中同样的能力被拆分到providers.kubernetesIngressNGINX静态配置——ingress-nginx 兼容默认值entryPoints——监听器行为如 HTTP 到 HTTPS 重定向、PROXY 协议动态tls.options与 HTTP 中间件——TLS 策略、HSTS 及其他头行为Traefik 访问日志配置——请求日志先导出当前 ConfigMap 并检查你自定义过的键kubectl get configmap --all-namespaces -l app.kubernetes.io/nameingress-nginx,app.kubernetes.io/componentcontroller -o yaml这个标签选择器可以在任意命名空间、任意 release 名下定位控制器 ConfigMap。单位换算提醒多个 ingress-nginx ConfigMap 键使用 NGINX 风格值如16k、1m、30s而 Traefik 对应的providers.kubernetesIngressNGINX选项要求请求体/缓冲类设置使用原始字节数proxyConnectTimeout、proxyNextUpstreamTimeout使用整数秒proxyRequestBuffering、proxyBuffering使用布尔值ConfigMap 到 Traefik 的映射表ingress-nginx ConfigMap 键Traefik 对应项provider 选项说明proxy-connect-timeoutproxyConnectTimeout使用整数秒。proxy-request-bufferingproxyRequestBufferingon/off转为true/false。注意 ingress-nginx 默认开启请求缓冲而 Traefik 默认false。client-body-buffer-sizeclientBodyBufferSize如把16k换算为字节。proxy-bufferingproxyBufferingon/off转为true/false。proxy-body-sizeproxyBodySize如把1m换算为字节。proxy-buffer-sizeproxyBufferSize如把8k换算为字节。proxy-buffers-numberproxyBuffersNumber保持整数值。proxy-next-upstreamproxyNextUpstream空格分隔的重试条件列表如error timeout http_502。proxy-next-upstream-timeoutproxyNextUpstreamTimeout使用整数秒。proxy-next-upstream-triesproxyNextUpstreamTries保持整数值。custom-http-errorscustomHTTPErrors若想要全局错误页服务同时配置providers.kubernetesIngressNGINX.defaultBackendService。global-allowed-response-headersglobalAllowedResponseHeadersnginx.ingress.kubernetes.io/custom-headers注解生效的前提。allow-cross-namespace-resourcesallowCrossNamespaceResources迁移后的 Ingress 需要引用其他命名空间资源时使用。strict-validate-path-typestrictValidatePathTypeTraefik v3.7 默认该选项为true。ssl-redirect/force-ssl-redirectnginx.ingress.kubernetes.io/ssl-redirect与nginx.ingress.kubernetes.io/force-ssl-redirect注解或集群级 entryPoint 重定向注解存在时 Traefik 会翻译全局默认则在web入口点配置 HTTP→HTTPS 重定向需要显式选择入口点时设置providers.kubernetesIngressNGINX.httpEntryPoint/httpsEntryPoint。ssl-protocols/ssl-ciphersTLS 选项通过入口点 TLS 选项全局应用或通过traefik.ingress.kubernetes.io/router.tls.options按 Ingress 指定。hsts、hsts-max-age、hsts-include-subdomains、hsts-preloadHeaders 中间件使用stsSeconds、stsIncludeSubdomains、stsPreload、forceSTSHeader把中间件挂到入口点上即形成集群级默认。use-proxy-protocol入口点proxyProtocol配置配置在每一个后面接说 PROXY 协议负载均衡器的入口点上。access-log-pathaccessLog.filePath静态配置。log-format-upstreamaccessLog.format使用 Traefik 内置common、genericCLF或json格式自定义 NGINX 日志格式模板没有 1:1 等价物。这些选项在源码中集中定义于 Provider 结构体默认值则由SetDefaults对齐 NGINX 原生默认连接/读/写超时各 60 秒、proxyBodySize1MB、clientBodyBufferSize16KB、proxyBufferSize8KB、proxyBuffersNumber4、重试 3 次、strictValidatePathType为true。也就是说如果你的 ConfigMap 没有自定义这些项Traefik 侧可以不配置直接获得等价行为。没有直接等价项的 ConfigMap 键一些键是 NGINX 特有的迁移时可以丢弃因为 Traefik 不暴露原始 NGINX 内部机制。常见例子worker 调优类worker-processes、worker-cpu-affinity、Lua shared dict 设置snippet 类键main-snippet、http-snippet、server-snippet、location-snippet、stream-snippetTraefik 内置访问日志格式之外的自定义 NGINX 日志格式模板遇到这类键时应翻译其背后的意图而不是照抄指令。参考文档Kubernetes Ingress NGINX Provider 安装配置Traefik TLS OptionsTraefik Headers 中间件Traefik EntryPoints 配置Step 1与 NGINX 并行安装 Traefik先读 status 竞争说明双控制器服务同一批 Ingress 会竞争status.loadBalancer.ingress[]字段。安装前请先看 Step 3 中的 Ingress Status 竞争条件 一节决定采用哪种缓解措施在 Traefik 上禁用publishService或使用过渡 IngressClass。如果你尚未安装 Ingress NGINX Controller可用以下命令先装一个helm upgrade --install ingress-nginx ingress-nginx --repo https://kubernetes.github.io/ingress-nginx --namespace ingress-nginx --create-namespace。启用 Kubernetes Ingress NGINX Provider 安装 Traefik两个控制器将同时服务相同的 Ingress 资源# 添加 Traefik Helm 仓库 helm repo add traefik https://traefik.github.io/charts helm repo update # 安装 Traefik helm upgrade --install traefik traefik/traefik \ --namespace traefik --create-namespace \ --set providers.kubernetesIngressNGINX.enabledtrue或者使用 values 文件做更多配置traefik-values.yamlproviders: kubernetesIngressNGINX: enabled: truehelm upgrade --install traefik traefik/traefik \ --namespace traefik --create-namespace \ --values traefik-values.yaml验证两个控制器都在运行# 查看 NGINX Pod kubectl get pods -n ingress-nginx # 查看 Traefik Pod kubectl get pods -n traefik # 确认两个服务都有 LoadBalancer IP kubectl get svc -n ingress-nginx ingress-nginx-controller kubectl get svc -n traefik traefik此时 NGINX 与 Traefik 都在运行且都能服务同一批 Ingress 资源DNS 仍指向 NGINX 的 LoadBalancer所以流量仍只走 NGINX。Step 2验证 Traefik 正在处理流量把 Traefik 加进 DNS 之前先确认它能正确服务你的 Ingress 资源。通过 Traefik 的 LoadBalancer IP 测试取出 Traefik 的 LoadBalancer IP用--resolve在不改 DNS 的情况下测试# 获取 LoadBalancer IP NGINX_IP$(kubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}) TRAEFIK_IP$(kubectl get svc -n traefik traefik -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}) echo -e Nginx IP: $NGINX_IP\nTraefik IP: $TRAEFIK_IP # 两边分别测 HTTP FQDNmyapp.example.com # 观察 HTTPS 重定向行为 curl --connect-to ${FQDN}:80:${NGINX_IP}:80 http://${FQDN} -D - curl --connect-to ${FQDN}:80:${TRAEFIK_IP}:80 http://${FQDN} -D - # 注意响应头 X-Forwarded-Server 应为 traefik # 两边分别测 HTTPS curl --connect-to ${FQDN}:443:${NGINX_IP}:443 https://${FQDN} curl --connect-to ${FQDN}:443:${TRAEFIK_IP}:443 https://${FQDN}TLS 证书注意HTTPS 测试要成功NGINX 和 Traefik 都必须持有有效证书。由于验证阶段 Traefik 不对外暴露Lets Encrypt HTTP challenge 无法工作。过渡期证书方案现有tls.secretName证书—— 如果你用 cert-manager 等外部工具spec.tls引用的现有 TLS secret 在两个控制器上都能工作Lets Encrypt DNS challenge—— 配置 Traefik 的 ACME DNS challenge无需公网暴露即可申请证书。不要用curl -k跳过证书校验它掩盖的 TLS 配置问题会在迁移后变成事故。验证 Ingress 发现情况查看 Traefik 日志确认它已发现你的 Ingress 资源kubectl logs -n traefik deployment/traefik | grep -i ingressStep 3把流量切换到 Traefik两个控制器都已验证无误后开始渐进切流。方案 A基于 DNS 的迁移把 Traefik 的 LoadBalancer IP 加入 DNS 记录与 NGINX 并存让两个控制器同时收流量。获取 LoadBalancer 地址# NGINX LoadBalancer echo $(kubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}) # Traefik LoadBalancer echo $(kubectl get svc -n traefik traefik -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }})渐进式 DNS 迁移五步把 Traefik 加入 DNS—— 两个 IP 开始轮询接收流量观察—— 监控两侧流量模式从 DNS 移除 NGINX—— 确认无误后删除 NGINX IP 记录等待 DNS 传播—— 给缓存过期留时间卸载 NGINX—— 进入 Step 4。DNS TTL 提醒部分 ISP 为省流量会忽略 TTL 值、把记录缓存得比指定时间更长。从 DNS 移除 NGINX 后保持 NGINX 至少再运行 24–48 小时再卸载避免旧缓存用户掉流量。Ingress Status 竞争条件双控制器共存时当两个控制器管理同一批 Ingress同为ingressClassName: nginx时双方都会把 LoadBalancer 地址写入每个 Ingress 的status.loadBalancer.ingress[]。每次协调循环里它们互相覆盖对方日志中没有报错只是两侧反复出现Updated ingress status信息行。路由本身不受影响——共存窗口内两个控制器都正常服务流量。但 flapping 的 status 字段会影响所有观察它的一方ExternalDNS可能在两个 LoadBalancer IP 之间来回改 DNS 记录kube-state-metrics、监控看板与告警规则ArgoCD、Flux 等 GitOps 工具会对每个受影响的 Ingress 报告永久漂移任何基于 Ingress status 字段做协调的自定义 Operator从源码看这一行为有据可查Provider 的updateIngressStatus在每次loadConfiguration后为名下每个 Ingress 回写状态——PublishService为空且未配置publishStatusAddress时直接返回LoadBalancer 类型 Service 则把service.Status.LoadBalancer.Ingress复制进 status。这既解释了竞争从何而来也给出了缓解手段的开关位置。推荐缓解方案 1共存期间在 Traefik 上禁用 status 发布以publishService禁用状态安装 Traefik# traefik-values.yaml providers: kubernetesIngressNginx: enabled: true publishService: enabled: false # 禁止写 statusTraefik 照常服务 Ingress只是不再写 status 字段NGINX 成为唯一写入方。用 port-forward 或独立测试域名 测试 TraefikExternalDNS 用户让 NGINX 发布 Traefik 的服务地址使 ExternalDNS 把流量指到 Traefik# nginx-values.yaml controller: publishService: pathOverride: traefik/traefik # 指向 Traefik 的服务验证流量走 Traefik—— 此时仍可回滚移除pathOverride即可在 Traefik 上重新启用publishService并进入 Step 4 卸载 NGINX。备选缓解方案 2过渡 IngressClass给迁移中的 NGINX 一个不同的 IngressClass例如nginx-migration让两个控制器不同时拥有同一批 Ingress从而彻底避免 status 竞争——代价是用一个短暂的流量切换步骤替代渐进 DNS 切流。方案 B外部负载均衡器 权重分流需要更精细控制时在两个 Kubernetes LoadBalancer 前面放一个外部负载均衡器Traefik、Cloudflare、AWS ALB 或专用 LB 均可。基础设施前提此方案假定你已有外部负载均衡器或愿意在迁移开始前搭建一个。新增外部 LB 是独立的基础设施变更应与入口控制器迁移分开规划与测试。设置步骤建一个指向 NGINX Kubernetes LoadBalancer 的外部 LBDNS 指向外部 LB把 Traefik Kubernetes LoadBalancer 以低权重如 10%加入外部 LB逐步调高 Traefik 权重、调低 NGINX 权重NGINX 无流量后卸载它。权重推进示例阶段NGINX 权重Traefik 权重持续时间初始100%0%-启动90%10%1 小时提升50%50%2 小时接近完成10%90%4 小时最终0%100%-常见外部 LB 选项Cloudflare Load Balancing带健康检查的流量引导、AWS Global Accelerator加权路由、Google Cloud Load Balancing流量分割、自建 Traefik / HAProxy / NGINX 等。LoadBalancer IP 保留若希望 Traefik 最终使用与 NGINX 相同的 LoadBalancer IP简化 DNS 管理可以在迁移后转移 IP。由于 Traefik 已带着自己的 LoadBalancer 在运行这可以零停机完成Traefik 已带自己的 LoadBalancer IP 运行Step 1把 Traefik IP 加入 DNS流量同时流向 NGINX 和 Traefik从 DNS 移除 NGINX IP 并等待传播删除 NGINX 的 LoadBalancer 服务以释放 IP升级 Traefik 认领释放出来的 IP可选新 IP 生效后从 DNS 移除 Traefik 旧 IP。整个转移过程中流量始终在流向 Traefik。获取当前 NGINX LoadBalancer IPkubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}AWSNLB 弹性 IPAWS Classic LB 不支持静态 IP应使用带弹性 IP 的 NLB前提是集群已安装 AWS Load Balancer Controller。# 预先分配弹性 IP每个可用区一个 aws ec2 allocate-address --domain vpc --region your-region # 记下每个 EIP 的 AllocationIdeipalloc-xxxtraefik-values.yaml更新service: type: LoadBalancer loadBalancerClass: service.k8s.aws/nlb # 需要 AWS Load Balancer Controller annotations: service.beta.kubernetes.io/aws-load-balancer-type: external service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip service.beta.kubernetes.io/aws-load-balancer-eip-allocations: eipalloc-xxx,eipalloc-yyyAzure支持 LB 静态公网 IP。# 定位现有公网 IP az network public-ip list --resource-group your-resource-group \ --query [?ipAddressyour-ip].name -o tsvservice: type: LoadBalancer annotations: # 仅当公网 IP 与 AKS 集群不在同一资源组时需要 service.beta.kubernetes.io/azure-load-balancer-resource-group: public-ip-resource-group spec: loadBalancerIP: your-existing-ipGCP通过预留区域静态 IP 实现。# 列出现有静态 IP gcloud compute addresses list # 或预留新的区域静态 IP必须与 GKE 集群同区域 gcloud compute addresses create traefik-ip --region your-cluster-regionservice: type: LoadBalancer spec: loadBalancerIP: your-static-ipOVHcloudOVHcloud 公网 LB 基于 OpenStack Octavia为 LoadBalancer 服务分配 floating IP需要集群中安装 OpenStack Cloud Controller ManagerMKS 用户已自带。保留现有 floating IP 的做法# 定位现有公网 IP NGINX_IP$(kubectl get svc -n ingress-nginx ingress-nginx-controller \ -o go-template{{ $ing : index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}) echo NGINX IP: $NGINX_IP# 给现有 NGINX LoadBalancer 服务加注解防止删除时释放 floating IP kubectl annotate svc my-lb-svc loadbalancer.openstack.org/keep-floatingiptruekeep-floatingip注解可阻止服务删除/修改时释放 floating IP。随后删除 NGINX LoadBalancer 服务、更新traefik-values.yamlservice: type: LoadBalancer spec: loadBalancerIP: your-existing-floating-ip其他云DigitalOcean 支持 floating IP 的loadBalancerIPLinode 支持loadBalancerIP裸机可结合 MetalLB 使用 IP 地址池。转移 IP 操作DNS 已指向 Traefik、values 已配好目标 IP 后# 确认 Traefik 已在通过当前 LoadBalancer 接收流量 kubectl get svc -n traefik traefik # 删除 NGINX LoadBalancer 服务以释放 IP kubectl delete svc -n ingress-nginx ingress-nginx-controller # 升级 Traefik 认领已释放的 IP helm upgrade traefik traefik/traefik \ --namespace traefik \ --values traefik-values.yaml # 确认 Traefik 拿到了原 NGINX 的 IP kubectl get svc -n traefik traefik零停机提示Helm 升级只会重启 Traefik Pod不会动 LoadBalancer 服务。Traefik 默认RollingUpdate部署策略新 Pod 先起来旧 Pod 再退出。为更稳妥建议配置高可用# traefik-values.yaml deployment: replicas: 2 # 把 Pod 打散到不同节点以容忍节点故障 affinity: podAntiAffinity: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchLabels: app.kubernetes.io/name: traefik app.kubernetes.io/instance: traefik topologyKey: kubernetes.io/hostname # 确保扰动期间至少一个 Pod 可用 podDisruptionBudget: enabled: true minAvailable: 1多副本打散 PodDisruptionBudget 可保证升级和节点维护期间至少有一个 Pod 在运行。Step 4卸载 Ingress NGINX ControllerNGINX 不再接收流量后将其移出集群。卸载前必须确保nginxIngressClass 被保留——Traefik 需要它继续发现你的 Ingress。保留 IngressClassHelm 安装的 NGINX添加helm.sh/resource-policy: keep注解让 Helm 保留 IngressClass# 添加所需注解 helm upgrade ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx \ --reuse-values \ --set-json controller.ingressClassResource.annotations{helm.sh/resource-policy: keep} # 确认注解确实生效 kubectl describe ingressclass nginx--reuse-values很关键——它保留你现有的全部 NGINX 配置没有它Helm 会把所有值重置为默认可能弄坏你的部署。注意kubectl annotate/patch/edit加注解无效。Helm 在内部保存 release 状态卸载时检查的是其内部清单中的注解而不是集群里的实时状态只有helm upgrade才能更新 Helm 的内部状态。GitOpsArgoCD、Flux安装的 NGINX在仓库中把nginxIngressClass 定义为独立资源与 NGINX Helm release 分离# ingressclass.yaml apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: nginx spec: controller: k8s.io/ingress-nginx手动安装的 NGINX直接创建独立 IngressClass 资源kubectl apply -f - EOF apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: nginx spec: controller: k8s.io/ingress-nginx EOF为什么保留的是这个spec.controller: k8s.io/ingress-nginx因为 Traefik Ingress NGINX Provider 的默认监听目标正是它SetDefaults把IngressClass默认为nginx、ControllerClass默认为k8s.io/ingress-nginx。保留原 IngressClass 对象Traefik 无需任何额外配置即可继续认领这些 Ingress。删除 NGINX 准入 Webhook为避免 NGINX 移除后 Ingress 修改出问题应删除准入 webhookkubectl delete validatingwebhookconfiguration ingress-nginx-admission kubectl delete mutatingwebhookconfiguration ingress-nginx-admission --ignore-not-found卸载 NGINXhelm uninstall ingress-nginx -n ingress-nginx如果你加过helm.sh/resource-policy: keep注解应看到These resources were kept due to the resource policy: [IngressClass] nginx release ingress-nginx uninstalled验证 IngressClass 存在kubectl get ingressclass nginx万一 IngressClass 被误删用上面保留 IngressClass一节的命令重建即可。清理 NGINX 命名空间kubectl delete namespace ingress-nginx迁移完成你已成功以零停机方式从 Ingress NGINX Controller 迁移到 Traefik。所有ingressClassName: nginx的现有 Ingress 继续工作只是现在由 Traefik 提供服务。故障排查Traefik 自带 Dashboard 可以帮助定位问题开启方式见 API Dashboard 文档。Ingress 未被 Traefik 发现# 验证 IngressClass 存在 kubectl get ingressclass nginx # 检查 Traefik provider 配置 kubectl logs -n traefik deployment/traefik | grep -i nginx\|ingress # 确认 Ingress 的 ingressClassName 正确 kubectl get ingress name -o yaml | grep ingressClassName注解行为不符合预期部分 NGINX 注解在 Traefik 中行为存在差异参见限制说明。TLS 证书不工作现有 TLS 配置在 Traefik 上照常工作——spec.tls条目保持原样Traefik 使用所引用的 secret 终结 TLSTLS secret 必须与 Ingress 位于同一命名空间NGINX 的ssl-redirect/force-ssl-redirect注解同样被遵守。# 验证 TLS secret 与 Ingress 同命名空间 kubectl get secrets -n namespace # 检查 secret 格式 kubectl get secret tls-secret-name -n namespace -o yamlLoadBalancer IP 未分配# 检查服务状态 kubectl describe svc -n traefik traefik # 查看事件 kubectl get events -n traefik --sort-by.lastTimestamp后续进阶深入了解 TraefikKubernetes Ingress NGINX 安装配置 —— Provider 配置详解Kubernetes Ingress NGINX 路由配置 —— 路由规则与注解支持HTTP 中间件 —— 超越 NGINX 注解的能力TLS 配置 —— 高级 TLS 与证书管理增强你的部署启用 指标 与 链路追踪配置访问日志完善可观测性探索 Traefik 中间件 实现高级流量管理把基于 NGINX 注解的配置迁移到 Traefik IngressRoute 或 Kubernetes Gateway API如果你使用 GitOps 管理入口资源迁移完成后将动态配置收敛到 Traefik CRDIngressRoute是自然的下一步——它提供比 Ingress 注解更精确的路由、中间件链与 TLS 控制也能顺带摆脱 Ingress status 竞争这一类控制器间协作问题。【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考