Ingress-NGINX 迁移至 Gateway API：五个关键意外行为

概述

随着 Kubernetes 社区宣布将于 2026 年 3 月退役 ingress-nginx，迁移到更现代、标准化的 gateway-api 成为众多运维团队和 SRE 的首要任务。然而，ingress-nginx 长期广泛使用，其内部实现中存在许多非标准的默认行为和“副作用”。许多生产集群可能已经依赖于这些未文档化的行为，而在迁移过程中，如果只是简单地进行语法转换而不考虑这些特性，极易引发难以预料的服务中断。本文档梳理了五个常见的 ingress-nginx 意外行为，旨在帮助团队进行有意识的评估与规划，实现安全、平滑的迁移。

核心概念

  • Ingress-NGINX: 由 Kubernetes 社区维护的 Ingress 控制器实现，使用 NGINX 作为数据平面。它通过一系列注解提供超出 Ingress API 标准的功能，例如路径重写、正则匹配等。其行为往往由这些注解隐式控制。
  • Gateway API: Kubernetes 官方推出的下一代流量管理 API 标准。它旨在解决 Ingress API 的局限性，提供更丰富、更具表现力的模型来配置服务网格和负载均衡器。其设计更显式、标准化，减少了实现间的差异和隐式行为。
  • 关键区别: Ingress-NGINX 倾向于“宽容”和“自动化”，会自动处理一些常见情况（如尾部斜杠重定向）。而 Gateway API 则遵循“显式优于隐式”原则，要求用户明确配置每一个期望的行为，从而提供更高的可预测性和控制力。

实践

以下是在将 Ingress-NGINX 迁移至 Gateway API 时，必须注意的五个关键行为及其应对策略：

1. 正则匹配是前缀匹配且大小写不敏感

行为：当在 Ingress 资源中启用正则匹配（nginx.ingress.kubernetes.io/use-regex: "true"）时，ingress-nginx 的路径匹配并非标准的全正则匹配。它默认将正则表达式视为大小写不敏感的前缀。例如，正则 /[A-Z]{3} 会匹配任何以三个字母（无论大小写）开头的路径，如 /abc、/XYZ，而不仅仅是精确匹配 /ABC。

迁移风险：如果客户端或应用实际上依赖于这种宽松的前缀匹配，而迁移时简单地转换为 Gateway API 的 RegularExpression 类型，由于 Envoy 等主流实现默认进行大小写敏感的完整匹配，可能会导致原有匹配的请求返回 404。

Gateway API 实践：

  • 保留行为：显式使用 RegularExpression 类型，并调整正则模式以体现前缀和大小写不敏感的特性。 
    path:
  type: RegularExpression
  value: "/[a-zA-Z]{3}.*" # 或使用 (?i) 标志，如 "(?i)/[a-z]{3}.*"
  • 纠正行为：如果希望精确匹配，应使用 Exact 或 Prefix 类型，并修正正则逻辑。

2. use-regex 注解影响主机的所有 Ingress 路径

行为：nginx.ingress.kubernetes.io/use-regex: "true" 注解的作用范围不仅仅是添加它的单个 Ingress 资源。它会导致 Ingress-NGINX 控制器将同一主机（Host）下所有 Ingress 资源的所有路径都视为正则表达式模式进行匹配。因此，一个标注了此注解的 Ingress 会影响该主机下其他 Ingress 的路径匹配行为。

迁移风险：在迁移时，如果只关注了单个 Ingress 的注解，而忽略了其对主机下其他路由的影响，会导致那些本意为精确或前缀匹配的路由，意外地以正则（大小写不敏感前缀）方式匹配，引发流量错误路由或遗漏。

Gateway API 实践：

  • 逐条路由规则检查：Gateway API 中的路径匹配类型（Exact, Prefix, RegularExpression）仅作用于其所在的 HTTPRoute 的单条规则。不存在“全局正则开关”。
  • 迁移时全面审查：在迁移前，必须检查主机下所有相关的 Ingress 资源，理解其在 use-regex 开启下的实际匹配行为，并将其准确地转换为 Gateway API 的显式路径匹配类型。

3. rewrite-target 注解隐式启用正则匹配

行为：nginx.ingress.kubernetes.io/rewrite-target 注解的存在，除了定义路径重写规则外，还会隐式地为该主机启用正则匹配模式，其效果等同于同时设置了 use-regex: "true"。这是一个非常常见的意外行为来源。

迁移风险：用户可能仅关注于重写逻辑的迁移，而未意识到路径匹配类型因该注解而改变。直接使用 Exact 或 Prefix 类型创建 Gateway API 路由，会因为行为不匹配（从隐式正则变为显式精确/前缀）而导致路由失败。

Gateway API 实践：

  • 分离关注点：在 Gateway API 中，路径匹配和路径重写（URLRewrite 过滤器）是完全独立的概念。
  • 迁移策略：
    1. 分析原 Ingress 在 rewrite-target 作用下的实际路径匹配行为（通常是大小写不敏感前缀）。
    2. 在 Gateway API 的 HTTPRoute 中，使用 RegularExpression 类型并相应调整模式，或在确认意图后改用 Exact/Prefix 并修正路径值。
    3. 单独配置 URLRewrite 过滤器来处理路径重写逻辑。

4. 缺少尾部斜杠的请求会被自动重定向

行为：对于路径类型为 Exact 或 Prefix 的 Ingress 规则，如果定义的路径有尾部斜杠（如 /my-path/），而请求路径没有（如 /my-path），Ingress-NGINX 会自动发送一个 301 Moved Permanently 重定向，将请求重定向到带尾部斜杠的版本。

迁移风险：如果客户端或下游服务依赖于这个自动重定向（例如，前端应用或 API 客户端总是请求不带斜杠的版本），迁移到 Gateway API 后，这个默认行为将消失，请求会直接返回 404，导致功能中断。

Gateway API 实践：

  • 显式配置重定向：如果需要保持此行为，必须在 Gateway API 中使用 RequestRedirect 过滤器显式配置。 
    filters:
- type: RequestRedirect
  requestRedirect:
    statusCode: 301
    path:
      type: ReplaceFullPath
      replaceFullPath: /my-path/ # 添加尾部斜杠
  • 修正应用调用：更好的长期方案是修正客户端，使其直接请求正确的路径（带或不带尾部斜杠），并在路由规则中明确处理。

5. Ingress-NGINX 会对 URL 进行规范化处理

行为：在匹配路由规则之前，Ingress-NGINX 会根据 RFC 3986 对请求的 URL 路径进行规范化。例如，移除路径中的 . 段（/a/./b -> /a/b）、解析 .. 段（/a/../b -> /b）、合并连续的斜杠（/a///b -> /a/b）。规范化后的路径再用于规则匹配。

迁移风险：后端应用可能依赖于 Ingress-NGINX 提供的规范化服务，即发送未经规范化的 URL 也能正确路由。虽然许多 Gateway API 实现（如 Envoy）默认也开启了部分规范化（如处理 . 和 ..），但具体行为可能有细微差别。迁移后，一些边缘情况的请求可能会失败。

Gateway API 实践：

  • 查阅实现文档：不同 Gateway API 实现的默认规范化行为可能不同，务必查阅所选实现的文档（如 Istio, Envoy Gateway, Kgateway）。
  • 统一规范化策略：确保新架构中的规范化策略与之前一致，或在应用层处理 URL 规范化，减少对网关层的隐式依赖。

SRE 要点

  • 与可靠性的关联：上述每一个“意外行为”都是潜在的单点故障源。迁移过程中的疏忽会直接导致流量丢失或路由错误，引发严重的生产事故。SRE 必须将这些行为视为迁移验证清单的关键项。
  • 最佳实践：
    1. 全面审计：迁移前，彻底审查现有 Ingress 资源及其使用的注解，特别是 use-regex 和 rewrite-target，理解其对流量的实际影响。
    2. 测试驱动迁移：为每个关键路由编写集成或端到端测试用例，覆盖正则匹配、路径重写、重定向等场景。在新 Gateway API 环境中验证这些用例。
    3. 分阶段切换：采用蓝绿部署或金丝雀发布，逐步将流量从 Ingress-NGINX 切换到 Gateway API，并监控错误率（5xx）和路由异常。
    4. 利用工具：考虑使用官方的 Ingress2Gateway 工具作为起点，但必须结合人工审查和调整。
  • 常见反模式：
    • 逐行翻译：机械地将 Ingress YAML 转换为 HTTPRoute，而不分析其背后的行为逻辑。
    • 忽视注解副作用：假设一个注解只影响其所在的资源，不理解其全局或隐式影响。
    • 缺乏生产验证：在 staging 环境测试通过后，未在生产流量模式下进行验证就完成切换。
  • 相关指标与 SLO：
    • SLI: 迁移期间应重点关注 路由请求错误率（例如，因 404 导致的请求失败百分比）和 路径匹配准确性（通过采样日志检查请求路径与匹配的后端服务）。
    • SLO: 可能需要为迁移过渡期设定临时的、更宽松的错误预算，并在迁移完成后恢复严格的 SLO。
    • 可观测性：确保 Gateway API 实现提供了详细的访问日志和指标，能够追踪请求的匹配规则和最终路由结果，这对排查迁移后的问题至关重要。