综合 Ingress-NGINX 2026 年 3 月退役:迁到 Gateway API 前,这几处行为差异会直接造成 404

2026-11-20 21:07:11

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 对象更清楚,这也是迁移后顺带得到的东西。

复制全文 生成海报 运维 Kubernetes Gateway API 迁移

推荐文章

程序员茄子在线接单