Gateway API 如何补足传统 Ingress 的路由表达

Gateway API 补足传统 Ingress 的核心，不是把入口资源换一个名字，而是把“谁负责基础设施、谁定义入口、谁维护应用路由”拆开，并把更多常见路由条件写进标准资源。Kubernetes 官方文档已经说明 Ingress API 进入冻结状态，仍然可用，但不会继续扩展；Gateway API 则面向更丰富、更可移植的流量路由场景。

官方地址：https://gateway-api.sigs.k8s.io/

如果现有 Ingress 只承担简单的 Host、Path 转发，可以继续稳定运行；如果开始依赖大量控制器注解、按请求头分流、按权重灰度，或需要让不同团队共享入口，Gateway API 的资源模型更适合承载这些表达。

• Ingress：资源简单、生态成熟，但扩展能力常落到控制器注解。
• Gateway API：用 GatewayClass、Gateway、HTTPRoute 分离职责，表达更结构化。
• 迁移策略：先对照目标控制器的支持矩阵，再按入口或路由逐步迁移，不必一次性重建全部流量。

这次变化解决的是什么问题

传统 Ingress 主要解决“外部 HTTP(S) 请求如何到达 Service”。它支持 Host、Path、TLS 等基础能力，但更复杂的请求头匹配、流量分配、重写和策略控制，往往依赖某个 Ingress Controller 的注解。这样做的直接代价是：配置看起来仍是 Kubernetes 对象，实际语义却可能被控制器实现锁定。

Gateway API 的思路是把可复用的路由语义提升到 API 资源中。官方概览把 Gateway API 描述为角色导向、可移植、可表达和可扩展的 API 家族；它不是单一控制器，而是一组由不同实现负责落地的 CRD。标准字段解决共性问题，厂商或项目扩展则应明确标注支持范围。

先看懂 GatewayClass、Gateway、HTTPRoute 的关系

Gateway API 把入口链路拆成三层。GatewayClass 表示由哪个控制器实现一类网关；Gateway 表示一个实际的流量入口和监听器；HTTPRoute 描述请求如何从监听器匹配到后端 Service。Service 仍然是应用后端，通常不需要因为入口 API 的变化而改写。

这组关系对应不同管理角色：基础设施提供者可以维护 GatewayClass，集群运维人员可以维护 Gateway 和监听器，应用团队则只维护自己的 HTTPRoute。Gateway 的 allowedRoutes 与 Route 的 parentRefs 共同决定“谁可以把什么路由挂到哪个入口”，比在一个 Ingress 对象上堆叠团队约定更容易审查。

HTTPRoute 如何补足路由表达

HTTPRoute 把一条 HTTP 路由拆成主机名、匹配条件、过滤器和后端引用。匹配条件可以组合路径前缀、精确路径、请求头、查询参数和方法；过滤器可表达请求或响应头修改等处理；多个 backendRefs 还可以通过权重完成渐进分流。不是每个扩展都在所有实现中具备相同支持等级，所以写配置前仍需查看所用 Gateway Controller 的文档。

用最小资源关系表达一个入口

下面的示例只展示资源之间的关系，不绑定具体控制器。实际部署前需要安装对应实现提供的 CRD，并把 controllerName 换成目标实现声明的值。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: shared-gateway
spec:
  # 中文注释：这里由具体 Gateway Controller 声明实际控制器名称。
  controllerName: example.net/gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
spec:
  # 中文注释：GatewayClass 决定这个入口由哪类实现负责管理。
  gatewayClassName: shared-gateway
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    # 中文注释：同命名空间路由是较保守的默认协作边界。
    allowedRoutes:
      namespaces:
        from: Same

这个拆分带来一个重要结果：应用团队不必修改基础设施层，就可以在被允许的范围内提交自己的 HTTPRoute。入口监听器和应用路由之间的边界由资源字段与 RBAC 共同约束，而不是只依赖注解命名规范。

把 Host、Path 和灰度权重写进 HTTPRoute

下面的配置让 api.example.com 下的 /v2 请求进入两个版本的 Service，并按 90% 与 10% 的权重分流。它用于展示表达方式；权重是请求分配意图，最终效果仍受具体实现、连接复用和流量规模影响。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-v2-route
spec:
  # 中文注释：parentRefs 把路由挂到指定 Gateway。
  parentRefs:
  - name: public-gateway
  # 中文注释：hostname 先筛选请求的 Host，再进入规则匹配。
  hostnames:
  - api.example.com
  rules:
  - matches:
    - path:
        # 中文注释：PathPrefix 只匹配 /v2 及其子路径。
        type: PathPrefix
        value: /v2
      # 中文注释：同一条规则还可按请求头继续收窄流量。
      headers:
      - name: X-Canary
        value: "true"
    backendRefs:
    - name: api-v2
      port: 8080
      weight: 90
    - name: api-v2-canary
      port: 8080
      weight: 10

与传统 Ingress 相比，读者可以直接从资源字段看出“匹配什么、转发到哪里、如何分流”。如果某个字段属于 Extended 或 Implementation-specific 能力，应以所选实现的支持声明为准，不要把标准示例当成所有环境中的自动保证。

从 Ingress 迁移时先做这张对照表

推荐的渐进采用流程

1. 盘点注解：把现有 Ingress 的 Host、Path、TLS、重写、限流和灰度需求分开，标出哪些依赖控制器注解。
2. 选择实现：确认目标 Gateway Controller 支持哪些 Standard、Extended 或 Implementation-specific 特性，并准备对应 CRD。
3. 先建入口：由基础设施或运维角色创建 GatewayClass 与 Gateway，明确 listener 和 allowedRoutes。
4. 迁移一条路由：先将一个低风险服务转换为 HTTPRoute，检查 Accepted、ResolvedRefs 等状态条件，再逐步扩展。
5. 保留回退：在切换 DNS、负载均衡或入口地址前保留原 Ingress 配置，确保能按服务粒度回退。

常见误区和判断边界

• 误区一：Gateway API 等于某个网关产品。它是 Kubernetes 生态中的 API 规范，具体流量处理仍由实现它的控制器负责。
• 误区二：Ingress 立即失效。Ingress API 已冻结不代表现有资源被删除；简单入口可以继续使用，迁移的价值主要来自新的表达需求。
• 误区三：标准字段在所有实现中都一样。Gateway API 有支持等级和 conformance，过滤器、跨命名空间引用等能力必须结合实现文档判断。
• 误区四：跨命名空间只改一处 YAML。Route 附着、Gateway 的 allowedRoutes、ReferenceGrant 和 RBAC 共同构成信任边界，少一层都可能导致路由不被接受。

速查结论

因此，Gateway API 对传统 Ingress 的补足可以概括为：把入口基础设施、监听器和应用路由拆成可协作的资源，再把常见的请求级路由条件从控制器注解中搬到更清晰的 API 表达里。是否迁移，取决于当前路由复杂度和目标实现的支持情况，而不是由“新旧”二字单独决定。

相关问题

Ingress 还能继续用吗？

可以。官方文档说明 Ingress API 已冻结，但现有能力仍受稳定性保证。只有在需要新的路由表达、角色协作或更强可移植性时，才更有必要评估 Gateway API。

Gateway API 会自动替换现有 Ingress 吗？

不会。Gateway API 不包含 Ingress kind，需要一次性的资源转换或按路由渐进迁移；具体转换方式取决于目标实现。

HTTPRoute 可以跨命名空间绑定吗？

可以设计跨命名空间关系，但必须满足 Gateway 的 allowedRoutes、Route 的 parentRefs 以及相关引用授权条件。实际配置还要检查实现对 ReferenceGrant 等资源的支持。

只用简单 Host 和 Path 是否需要马上迁移？

通常不需要。若现有 Ingress 稳定且没有控制器迁移压力，可以先保持；把 Gateway API 作为下一次入口能力扩展或平台统一时的演进方向更稳妥。