Kubernetes Ingress NGINX 控制器迁移指南：旧版停服与替代方案

这轮公告里最扎眼的词是“立即”。Kubernetes 官方连着两轮发通知核心就一句话别再把生产集群的入口流量押在旧版 Ingress NGINX 控制器上了安排迁移。这件事不是又一条让你看完划走的技术新闻它直接影响到所有用registry.k8s.io/ingress-nginx/controller镜像、靠nginx.ingress.kubernetes.io/系列注解维护路由规则的存量集群。我做平台工程这些年看多了开源项目换“话事人”的戏码但像这次这样从项目所有权、商标归属到安全修复通道一锅端给出来的确实少见。官方态度已经很明确旧项目进入只读状态后续没有官方发版也没有安全补丁。这不是“你继续用也能凑合”的更新提醒而是“你再不动后面出问题没人兜底”的倒计时。这篇文章我不想重复粘贴官方公告原文我打算按一个真正经历过迁移的人的角度把这件事从头到尾捋一遍先讲清楚公告背后到底发生了什么然后带你用实际命令盘点现状接着对比迁移方案、给出可落地的操作步骤最后把我踩过的坑和排查思路一并交出来。全程按可复现的方式写适合负责 Kubernetes 集群网络和入口流量的 SRE、平台工程师也适合刚接手集群、想搞清楚流量入口怎么回事的人看。1. 公告背后的真实情况与影响面1.1 两轮公告到底说了什么第一轮公告来自 Kubernetes SIG Network通知社区Ingress NGINX 控制器的项目所有权和维护责任发生转移NGINX 公司退出原来的社区协作模式带着品牌和商标权另起炉灶。第二轮公告紧接着把话说透了——从某个时间点起Kubernetes 官方不再为存量版本提供发布和漏洞修复建议生产环境用户立即迁移。严格讲这并不是 Kubernetes 说“Ingress NGINX 这项目死了”而是“这个项目换主人了你手里的这个老版本没有售后了”。对你我来说结果的差别不大你的镜像仓库、控制器镜像 tag、注解规范都停留在旧时代而旧时代的闸门已经落下。这件事背后其实是一场典型的开源治理冲突。Ingress NGINX 控制器从诞生起就是 Kubernetes 生态里最知名的七层流量入口方案但真正掌握它商标和域名的是 NGINX 公司。双方在项目发展方向、代码所有权、发布流程上越走越远最后只能分家。社区版的历史贡献还在但它已经不能以“Kubernetes 官方项目”的名义继续向前走了。1.2 受影响面比你以为的大得多凡是满足下面任意一条的都属于本次受影响范围控制器镜像直接使用registry.k8s.io/ingress-nginx/controller或quay.io/kubernetes-ingress-controller/nginx-ingress-controller通过 Helm 安装了ingress-nginx/ingress-nginx官方 chart且长期跟随社区版本升级Ingress 资源上用了大量nginx.ingress.kubernetes.io前缀注解比如 rewrite、affinity、ssl-redirect自定义了ingress-nginx-controller的 ConfigMap里面配了 body-size、timeout、log-format 之类参数用了--tcp-services-config-map和--udp-services-config-map转发 TCP/UDP 流量。你以为只是换个镜像 tag实际上牵扯面包括 IngressClass 绑定、注解语义、四层流量模型、证书挂载方式甚至健康检查路径。这也是为什么官方用“迁移”而不是“升级”这个词升级是在同一个体系内换版本迁移是你必须去适应另一套入口体系。组件与旧版 Ingress NGINX 的耦合点迁移时可能遇到的连锁问题Ingress 资源ingressClassName: nginx或旧注解指定控制器新控制器默认不监听同名 IngressClass切了不生效注解nginx.ingress.kubernetes.io/rewrite-target等新控制器未必支持相同注解名或语义有偏差ConfigMapingress-nginx-controller的全局配置参数名不兼容body-size 和 timeout 不生效TCP/UDP 服务--tcp-services-config-map挂载的 ConfigMap新控制器对四层流量是另一套模型需要改写Secret直接引用 controller 同名 Secret 做默认证书控制器不认旧 ServiceAccount 的 Secret 更新逻辑1.3 为什么官方把话说得这么重如果你翻过旧版 Ingress NGINX 的 CVE 列表会发现它几乎每年都会被挖出高危漏洞。最典型的例子是 CVE-2025-1974一个位于认证函数里的鉴权绕过问题CVSS 评分 9.8攻击者可以在未授权的情况下触达后端服务。这类漏洞之所以危险不是因为代码写得差而是因为 Ingress 控制器是整个集群流量入口最前排的位置。它一旦被攻破等于把大门的钥匙直接交给了攻击者。过去出现这种情况Kubernetes 官方会很快跟进补丁并发布新版本现在项目冻结了这个“发现漏洞—修复—发版”的循环就断了。以后每次安全公告出来你大概率只能看到“暂无修复方案”这七个字。这就是官方把“立即”写进标题的根本原因安全问题不等人。你当然可以继续跑在旧版本上但这等于把你的入口安全建立在一个没有守门人的院子里赌的是没人注意到你的门还开着。2. 动手前先搞清楚现状你的环境到底依赖什么2.1 定位你正在运行的控制器镜像迁移第一步不是下载 Helm chart而是搞清楚你现在跑的是哪个项目、哪个版本。多数情况下控制器部署在ingress-nginx命名空间下直接用下面的命令就能看到镜像来源和启动参数kubectl get deploy -n ingress-nginx ingress-nginx-controller -o yaml | grep -E image:|args: | head -20输出里如果出现registry.k8s.io/ingress-nginx/controller:v1.11.4或v1.9.x这类 tag说明你跑的就是社区版 Ingress NGINX。请顺手把--ingress-class参数也记下来绝大多数部署会把它设为nginx这决定了你现有的 Ingress 资源挂在哪个 class 下面。这一步的意义是建立“现状基线”。你不光要知道控制器叫什么还要知道它监听哪些 IngressClass、加载了哪些 ConfigMap、开了哪些额外 flag。这些信息在后续迁移选型时全部用得到。2.2 用一条命令盘点注解依赖Ingress NGINX 的老用户几乎都会用到注解比如 rewrite-target、proxy-body-size、ssl-redirect、affinity。这些注解就像是这个控制器给你开的“私房小灶”换一套控制器小灶未必还有就算有菜谱也不一定一样。把整个集群里所有 Ingress 的注解全部拉出来看一眼kubectl get ingress -A -o json | jq -c [.items[] | {namespace: .metadata.namespace, name: .metadata.name, annotations: (.metadata.annotations // {} | keys)}] 这段命令会把每个 Ingress 用到的注解键名全部列出来。你不需要逐条翻译真正要看的是“哪些注解被用了很多次”。现实里命中率最高的往往是这几组nginx.ingress.kubernetes.io/rewrite-target旧版最常用的路径重写新控制器同样支持但语义细节不同nginx.ingress.kubernetes.io/affinitycookie 粘滞会话新版控制器有自己的一套参数nginx.ingress.kubernetes.io/proxy-body-size上传大小限制这个相对容易平移nginx.ingress.kubernetes.io/ssl-redirect强制 HTTPS 跳转不同控制器默认行为不一样尤其要确认。2.3 把流量入口之外的隐藏依赖一并列出来很多人迁移到一半才发现自己不只是依赖 Ingress 控制器本身还依赖它顺带提供的一堆“周边功能”。我建议你按这张清单自查四层流量有没有用--tcp-services-config-map把 MySQL、Redis、Dubbo 服务暴露到外部如果有迁移难度会立刻上升一个级别金丝雀发布有没有用nginx.ingress.kubernetes.io/canary系列注解做按比例或按 Header 的灰度新的控制器对金丝雀的支持逻辑不一定完全一致默认后端控制器有没有挂独立的default-backend服务404 页面长啥样、空白响应对业务有没有影响证书流转Cert-Manager 签发后会不会自动写入控制器读取的 Secret如果之前依赖 controller 的 leader election 去 watch Secret切到新控制器后可能要重新挂权限健康检查外部负载均衡器探测的是/healthz还是自定义路径新控制器如果换了健康检查路径SLB 会立刻摘掉后端。你把这些依赖一条条列完迁移方案基本就清晰了一半。最怕的是“先装了新控制器再说”结果切过去才发现 WebSocket 断了、灰度规则没了、TCP 端口全挂了。3. 迁移目标选型别急着抄命令先想清楚往哪走3.1 三条路线对比在动手装任何东西之前先回答一个选择题你准备迁到哪里现在市场上有几条主流路线我列个对照表你按自己的场景挑方案维护方与旧版注解兼容度Ingress v1 支持适合场景NGINX 官方 NGINX Ingress ControllerNGINX 公司高但不完全一致支持生产环境要求稳定、需要商业支持NGINX Gateway FabricNGINX 公司低偏向 Gateway API支持但非重点计划未来切到 Gateway API 的团队旧版社区 Ingress NGINX 长期自维护自己社区或 fork100%支持实在没有迁移力量但风险自担HAProxy / Traefik / 其他各自社区低支持愿意重构注解想顺手换技术栈这里有个误区要讲清楚很多人看到“NGINX 官方”四个字就以为注解完全通用其实不对。NGINX 官方控制器虽然也用 NGINX 内核但它对 Ingress 注解的处理逻辑和社区版不一样比如 rewrite 的组捕获规则、affinity 的写法、上游的use-proxy-protocol参数配置都存在差异。选型时不要把“兼容”理解成“一模一样”要理解成“思路接近仍需做配置迁移”。3.2 选型的三个关键信号三个信号基本能定方向第一个信号是注解依赖有多重。如果十几个服务都在用 rewrite 和 affinity选 NGINX 官方控制器会更省力因为它至少在语义层面最接近。反过来如果注解字段几乎没怎么用那选路就宽了Traefik 甚至 HAProxy 都行。第二个信号是是否正在规划 Gateway API。如果你的平台组已经明确未来半年内会切到 Gateway API那 NGINX Gateway Fabric 就是一步到位的选择。代价是你要把 Ingress 注解体系整个重写一遍这个工作量和风险需要提前估算。第三个信号是有没有商业支持诉求。银行、政务、大企业往往要求厂商兜底那显然要选有 commercial support 的 NGINX 官方产品线。这一点对中小公司影响不大但大公司别忽略。3.3 我个人的推荐组合我给大多数团队的建议是不要一次性从 A 迁到 B 再迁到 C尽量一次迁到你能长期停留的位置。如果你现在没有明确接入 Gateway API 的计划优先选 NGINX 官方 NGINX Ingress Controller因为它的 Ingress v1 支持和注解平移成本最平滑如果你们已经开始在测试环境摸索 Gateway API那直接上 NGINX Gateway Fabric省得迁移半年后又来一轮。这一点属于个人经验仅供参考。关键是先把目标定下来否则你在后面“备份、部署、切流、回滚”每一步都会犹豫。4. 迁移实操从备份到切流的一次完整动作4.1 先备份备份完还要验证备份迁移这种事备份做不好就等于裸奔。先跑这三条命令把 Ingress 资源、IngressClass、TLS Secret 全部导出来kubectl get ingress -A -o yaml ingress-all.yaml kubectl get ingressclass -o yaml ingressclass-all.yaml kubectl get secret -A -l kubernetes.io/tls -o yaml ingress-tls-secrets.yaml导出完成后随机挑两个文件打开看一遍确认里面有内容而不是空文件。更稳妥的做法是再导一份 JSON 存档因为 YAML 在某些工具下格式化会丢注释和未知字段JSON 反而更保真。Secret 这块我要单独提醒TLS 证书文件不要只留在 Kubernetes 里建议从 Secret 里 base64 解码出来放到公司的密钥管理系统里。万一迁移过程中 Secret 被误删你没有备份就只剩哭的份。4.2 起新控制器旧的不动我强烈建议至少在迁移初期同时运行新旧两套控制器让它们共享同一批 Ingress 资源但监听不同的 IngressClass这样你可以在完全不影响线上的情况下验证新控制器的行为。以 NGINX 官方控制器为例安装命令大致这样helm repo add nginx-stable https://helm.nginx.com/stable helm repo update helm install ingress-nginx-new nginx-stable/nginx-ingress \ --namespace ingress-nginx \ --set controller.ingressClassnginx-new \ --set controller.ingressClassResource.namenginx-new注意这里设置的 IngressClass 名称是nginx-new意味着新控制器不会和旧控制器抢名为nginx的 IngressClass 资源。这一步非常关键两个控制器如果同时监听同一个 IngressClass会出现资源竞争甚至导致后端每隔几秒就被重新摘除再挂上。部署完成后用命令确认新控制器已经 Readykubectl get pods -n ingress-nginx -l appingress-nginx-new4.3 核心操作迁移 Ingress 资源现在到了关键动作把 Ingress 资源的ingressClassName从旧值改成新值。最简单的情况是直接把每个 Ingress 的ingressClassName字段从nginx改为nginx-new然后观察新控制器是否生成对应的后端。kubectl patch ingress my-app -n prod --type merge \ -p {spec:{ingressClassName:nginx-new}}这时候需要注意一个现象Ingress 资源改了 class 之后你在旧控制器里看不到这个 Ingress 了等于后端被抽走。如果你同时运行双控制器理想状态是同一个域名在旧控制器和新控制器都能正常访问但不一定两者同时处于“接管流量”的状态——所以下面引入 DNS 灰度。如果你的 Ingress 比较多不要手动一条条 patch写个循环按命名空间批量改但每改完一个就走一遍自动校验确认新控制器日志里出现了对应的 “Configuration changed” 记录。4.4 用 DNS 做灰度切流别一把梭控制器层面的切换不代表流量层面的切换因为你还有最后一环流量怎么从旧入口进到新入口。一个非常实用的做法是通过 DNS 解析切换完成灰度。首先拿到新旧控制器的 Service LoadBalancer IP 或域名kubectl get svc -n ingress-nginx ingress-nginx-new -o wide然后把某个测试域名的 A 记录先从旧的 LB IP 临时切到新的 LB IP跑一晚上看日志、看错误率、看后端响应码。确认没问题后再按业务域逐个切。有条件的团队建议先把内部测试域名切过来跑一周再动生产域名。这里我要强调一个反直觉的点不要觉得改了 IngressClass 就算切流完成。你的 DNS 解析如果还是指向旧 LB IP哪怕新控制器已经接管了 Ingress 资源流量还是打到旧控制器上等于白迁。切换的最终判定标准一定是“公网 DNS 到新 LB新 LB 到新控制器新控制器到新后端”这条链路全部打通。4.5 验证清单一条条打勾切换完成后我建议按这个清单逐项验收不要看完首页能开就宣布成功首页 200静态资源 200接口返回码无异常HTTPS 证书链完整无过期提示WebSocket 连接能建立并保持心跳带大开文件上传的接口正常验证 body-size 配置配置了 sticky session 的服务多次请求落到同一后端自定义的 404 页面依然生效访问日志里的 X-Forwarded-For 和真实客户端 IP 保留正确。只要有一项对不上就说明新控制器的配置还没完全对齐宁可停下排查也不要带着问题往下推。5. 迁移过程里最常踩的坑与排查思路5.1 症状对照速查表这里把我在迁移中遇到的和群里看到的高频问题整理成一张表按症状查原因能省不少时间症状排查方向处理建议切了 IngressClass 后域名 404新控制器没有监听对应 IngressClass检查 IngressClass 名称是否匹配查看新控制器启动参数全部后端都返回 502rewrite 注解或 upstream 配置不兼容对比新旧控制器生成的 nginx.conf重点检查 proxy_pass 路径只有部分服务 503新控制器没有对应 Service 的 Endpoint 权限检查 RBAC是否给了 get/list/watch endpoint 权限WebSocket 连上就断read timeout 默认值不同在新控制器 ConfigMap 里调大 proxy-read-timeout上传大文件被拒proxy-body-size 未设置找到原 ConfigMap 的参数并复制到新控制器sticky session 失效affinity 注解写法不一致确认新控制器支持的 cookie 注解名逐条对照HTTPS 证书警告Secret 所在命名空间或名称变了检查 Ingress 里 tls 段指向的 Secret确认新控制器具备读取权限5.2 注解迁移最容易在 rewrite 上翻车Ingress NGINX 的 rewrite 注解是很多团队最依赖的功能也是最容易在迁移时翻车的地方。旧版写法通常是nginx.ingress.kubernetes.io/rewrite-target: /$2这种做法依赖正则里的组捕获。NGINX 官方控制器同样支持 rewrite 目标但路径匹配的优先级、组捕获的转义规则和默认行为不完全一致。我见过最典型的翻车案例路径从/api/v1/foo被 rewrite 成/v1/foo肉眼看起来没问题结果登录接口全部 401原因是 rewrite 规则把/api/auth这个前缀里的鉴权路径也吞掉了。遇到这类问题不要一条条瞎试最有效的办法是打开新控制器的调试日志把每一条请求的 rewrite 前后 path 打出来对比。或者先把注解全部摘掉让路由按原始路径走通再逐步加回 rewrite每加一条验证一次基本能定位到是哪条规则改错了。5.3 回滚剧本要提前写好迁移前回滚脚本要像备份一样准备好而且最好演练一遍。这里给一个最小可用的回滚序列把 DNS 解析从新 LB 切回旧 LB这一步能让流量秒级回退执行kubectl patch ingress my-app -p {spec:{ingressClassName:nginx}}把 Ingress 资源改回旧控制器观察旧控制器日志确认恢复了后端绑定确认业务接口返回码恢复后再决定是否卸载新控制器。注意回滚顺序永远是“先切 DNS再改 IngressClass”因为 DNS 是真正的流量闸门IngressClass 只是告诉控制器“你是谁有资格处理这些路由”。反过来操作会有一段流量黑洞时间Ingress 已经切回旧控制器但 DNS 还盯着新 LB新控制器又不再监听这个 Ingress直接就是 404。5.4 一个真实事故复盘我栽在了“默认证书”上分享一个我自己的真实教训。去年给一个电商项目做入口迁移时我几乎把所有 Ingress 资源都切过去了域名访问也正常结果移动端 App 在弱网环境下频繁报证书错误。排查半天才发现问题出在默认证书上旧控制器配置里挂了--default-ssl-certificate把根域名证书放在了 controller 的启动参数里所有没显式配置 tls 段的 Ingress 都会自动套上这张证书。新控制器没设这个参数那些没写tls段的域名全部落回 NGINX 自签证书上线验证时因为监控检测的是首页 HTTP完全没触发告警直到移动端做 HTTPS 证书校验才暴露。这个坑在迁移文档里很少被提到。负责迁移的同事如果只是对着 Ingress 资源列表检查很容易漏掉。建议大家迁移时专门搜一遍tls段为空的 Ingress确认它们是否依赖旧控制器的默认证书这一步跑了能避开很大的线上事故。6. 一些体会写在最后Ingress NGINX 这轮迁移表面上是一次技术栈替换本质上是一次入口架构的重新梳理。官方公告推着每个使用者去审视自己的入口层哪些资源真的在用哪些注解已经过期哪些流量可以用 Gateway API 重写哪些服务其实根本不该从入口出去。这个过程痛苦但做完了对集群的整体把控力会明显提升。我个人实操下来的体会是迁移最大的敌人不是技术差异而是对现状的无知与惯性。很多人觉得自己对集群里每个 Ingress 都了如指掌直到真的要迁才在注解盘点阶段发现一堆没人认领的旧路由和过期证书。所以哪怕你暂时不打算迁移我也建议按第 2 节的方式把现状盘点一遍这本身就是在给入口层做一次健康检查。如果你后续计划做这件事还有一个小建议不要把这次迁移理解成“换控制器版本”的机械动作而是顺手把入口层的统一认证、限流、可观测性全部对齐一遍。反正都要动一次刀不如一次把该清的清掉该建的建起来。