Ingress-NGINX 2026 年 3 月退役:迁到 Gateway API 前,这几处行为差异会直接造成 404
退役公告:kubernetes.io/blog/2025/11/11/ingress-nginx-retirement
迁移前必读:Before You Migrate
Ingress2Gateway 1.0:kubernetes.io/blog/2026/03/20/ingress2gateway-1-0-release
时间线与后果
Ingress-NGINX 的尽力维护一直持续到 2026 年 3 月。之后的状态是:不再发版、不再修 bug、不再处理新发现的安全漏洞;GitHub 仓库转为只读。已经部署的实例继续运行,Helm chart 和容器镜像也仍然可拉取;也就是说,下线会很快发生,但不会在同一个时间点,你可能长时间处于“没有安全补丁”的状态。
按 Datadog 的统计,约一半云原生环境依赖它。委员会在 2026-01-29 的声明中提到,现有替代方案都不是 drop-in replacement,迁移需要规划和工程时间。
先确认自己有没有在用:
kubectl get pods --all-namespaces \
--selector app.kubernetes.io/name=ingress-nginx
注意 Ingress-NGINX(社区版,即将退役)和 NGINX Ingress(F5 维护)是两个不同的 controller;不要把检查结果和迁移对象对应错。另外,InGate 作为替代方案开发一直没有推进,同样会退役。
五处看起来等价、实际不等价的行为
1. 正则匹配:前缀 + 大小写不敏感 vs 由实现决定
Ingress-NGINX 的正则路径是前缀匹配,并且大小写不敏感。Gateway API 里对应的是 HTTP path match 的 RegularExpression,但它的语义由实现决定:Istio、Envoy Gateway、Kgateway 这些基于 Envoy 的实现执行的是全量、大小写敏感匹配。
把 /[a-z]{3} 直接翻过去,/uuid 将不再命中,返回 404。保留原语义有两种写法:
- 显式写成
/[a-zA-Z]{3}.* - 或用
(?i)内联标志:(?i)/[a-z]{3}.*
另外,Gateway API 不会把 Exact、Prefix 悄悄当成正则来解释;反过来,也不能指望正则被自动降级成前缀匹配。
2. 重定向:不再有隐式行为
符合规范的 Gateway API 实现不会隐式配置任何重定向。Ingress-NGINX 的一些默认行为(例如尾斜杠补全返回 301)在迁移后就不存在了;如果客户端依赖该行为,迁移后会得到 404,不再是 301。需要显式挂上 HTTPRequestRedirect filter。
3. snippets 没有等价物
configuration-snippet 注解曾经允许注入任意 NGINX 指令,如今它被视为严重的安全缺陷。Gateway API 中不存在对应能力;依赖 snippet 的逻辑需要在迁移前拆分,或改写为可表达的标准字段/实现扩展。
4. body size 与超时字段不对齐
proxy-body-size、proxy-read-timeout、proxy-send-timeout 没有精确对应的标准字段。自动转换会给出近似值——通常是一个 10s 的请求超时;proxy-body-size 在 Gateway API 中没有等价字段,只能依赖实现默认值(部分 emitter 通过扩展支持)。这几个值必须按业务逐个确认。
Ingress2Gateway 1.0
这一版支持 30 多个常见 Ingress-NGINX 注解(CORS、后端 TLS、正则匹配、路径重写等),并带有 controller 级集成测试,对比 Ingress-NGINX 与多个 Gateway API controller 在路由、重定向、重写上的运行期行为。
ingress2gateway print --providers=ingress-nginx --all-namespaces > gwapi.yaml
也可用 --input-file、--namespace 限定范围,用 --emitter 输出实现相关的扩展。
输出要人工过一遍:
enable-cors会转成 CORS filter;- 正则会被写成
(?i)/users/(\d+).*,多数场景应去掉(?i)和尾部.*; configuration-snippet不支持;- 工具会额外补一个 80 端口 listener 和 HTTP→HTTPS 重定向 filter,以贴近 Ingress-NGINX 默认行为,不需要就删掉;
- URL 规范化行为在各实现(Agentgateway、Envoy Gateway、Kgateway、Istio)之间不一致,且无法通过标准 Gateway API 配置。
迁移顺序
先在 dev 集群验证 body size 默认值和超时。生产上可以让 Gateway API controller 与 Ingress-NGINX 并行运行(使用不同的外部 IP),先把新入口跑起来做隔离测试;确认后再用加权 DNS、云负载均衡或平台的流量切分逐步放量,最后删除 Ingress 资源并卸载旧 controller。
Gateway API 本身的模型是 Gateway(集群运维)与 HTTPRoute(应用开发)分层,权限和职责边界比单个 Ingress 对象更清楚,这也是迁移后顺带得到的东西。