Kubernetes Gateway API 与 Ingress 的职责边界有什么变化

如果你正在维护一套已经稳定运行的 Kubernetes Ingress，暂时不需要因为 Gateway API 出现就立刻重写全部入口配置。Ingress 仍然是稳定 API，Kubernetes 并没有计划移除它；真正发生的变化是 Ingress API 已经冻结，新的能力和更清晰的多团队协作模型会优先放在 Gateway API 中。

可以把这次变化理解为“入口配置从一个对象，拆成多个职责层”。Ingress 更像是把外部 HTTP/HTTPS 流量映射到后端的简洁入口；Gateway API 则把谁管理基础设施、谁创建监听入口、谁编写应用路由和谁允许跨命名空间引用表达出来。

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

一句话判断：简单、单团队、以 HTTP/HTTPS 为主的入口可以继续使用 Ingress；当入口需要多团队共享、跨命名空间附着、协议化路由或减少控制器专用注解时，Gateway API 更适合作为新的资源模型。

先看症状：为什么同一份 Ingress 越改越难维护

典型场景是一个 Ingress 对象同时包含域名、路径、TLS、后端服务和一长串控制器注解。早期这样做很直接，但对象的维护者逐渐变得模糊：平台团队要调整负载均衡或监听端口，应用团队要新增路径，安全团队又要限制哪些命名空间可以挂载。最后每一次修改都可能触碰同一个对象。

这里的故障症状通常不是“入口马上不可用”，而是边界开始失控：

• 同一能力依赖某个 Ingress Controller 的注解，换实现时需要重写配置。
• 基础设施设置与应用路由混在一起，审查变成整份 YAML 的共同审批。
• 跨命名空间引用需要额外约定，单看 Ingress 资源不容易判断谁授权了谁。

Kubernetes 官方文档明确说明 Ingress API 已冻结：它仍受稳定 API 的兼容性承诺保护，但不再继续增加新能力。因此，迁移判断的重点不是“旧对象是否还能运行”，而是“下一项需求是否会继续把职责塞进注解”。

资源模型：从一个 Ingress 对象到分层资源

Ingress 的基本思路是一个对象描述外部访问规则，控制器读取它并负责实现负载均衡、TLS 终止和基于域名或路径的转发。IngressClass 可以选择控制器，但应用路由和入口实现仍然容易集中在同一份对象周围。

Gateway API 把关系拆成三层核心资源，外加具体协议的 Route：

这并不意味着 Gateway API 一定要部署更多数据面组件。Gateway API 是一组 API 资源，实际由支持它的控制器实现。对迁移者来说，重要的是先把“入口基础设施”和“应用路由规则”分开，再确认目标控制器支持哪些标准或扩展能力。

时间线：变化首先发生在 API 的扩展方式

Ingress 的稳定性是它的优点，但稳定也意味着 API 本身不会再继续演进。过去控制器常用注解承载重写、权重、超时或其他实现特性；这些注解能解决问题，却把可移植性和职责边界交给了具体实现。

Gateway API 选择了另一条路线：用角色导向的资源模型，把基础设施提供方、集群运维者和应用开发者放到不同的配置层；用 HTTPRoute、GRPCRoute 等协议化 Route 表达常见路由；对无法统一的能力保留扩展点。这样做的结果不是所有注解都会自动消失，而是通用能力有了更稳定的表达位置。

例如，下面的片段把 Listener 和应用路由拆开。代码中的注释只解释资源关系，不代表某个具体控制器已经在当前集群中安装。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: edge-gateway
  namespace: platform
spec:
  gatewayClassName: shared-public
  listeners:
  - name: web
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            expose-apps: "true" # 只允许带标签的命名空间附着路由
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: orders-route
  namespace: orders
spec:
  parentRefs:
  - name: edge-gateway
    namespace: platform # parentRefs 表达路由要挂到哪个 Gateway
  hostnames:
  - "orders.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: orders-service
      port: 8080 # backendRefs 只描述应用后端，不携带负载均衡实现细节

触发条件：路由能挂上，不等于后端引用自动获授权

Gateway API 的一个重要变化，是把“Route 是否能附着到 Gateway”和“Route 是否能引用另一个命名空间的后端”区分开。Gateway 的 Listener 可以用 allowedRoutes 限制来源命名空间；HTTPRoute 用 parentRefs 表达它想连接的 Gateway。

跨命名空间的后端引用则需要更谨慎。Gateway API 文档把 ReferenceGrant 定义为资源所有者对跨命名空间引用的明确授权。也就是说，Route 的存在不能单独推导出它可以读取或使用另一个命名空间的 Service；授权要由目标资源所在命名空间显式给出。

因此，排查“路由资源已经创建但流量没有按预期转发”时，不能只看 HTTPRoute 的 parentRefs。至少要分别确认 Gateway 的 Listener 是否允许该命名空间、Route 是否被控制器接受，以及跨命名空间后端是否存在对应的 ReferenceGrant。它们是三个不同的责任面。

根因：不是 YAML 语法差异，而是所有权差异

把 Ingress 直接机械转换为 Gateway 和 HTTPRoute，最容易漏掉的是所有权。Ingress 常把这些信息写在一个对象中，而 Gateway API 要求你回答几个以前被隐藏的问题：

1. 谁决定使用哪一种 GatewayClass？
2. 谁创建和维护对外监听的 Gateway、地址与 TLS Listener？
3. 应用团队能附着到哪些 Gateway，范围是同命名空间、标签选择还是其他约束？
4. 后端 Service 是否跨命名空间，谁拥有授权它被引用的权力？

如果这些答案没有形成组织约定，迁移后的 YAML 可能比原来的 Ingress 更多，却没有更清晰。Gateway API 的价值需要配合 RBAC、命名空间标签和资源审查一起落地，不能只把注解改成新的字段名。

修复动作：三种迁移路径怎么选

路径一：继续使用 Ingress

如果入口由一个团队维护，需求主要是标准 HTTP/HTTPS 的域名和路径转发，现有控制器也能稳定满足业务，那么继续使用 Ingress 是合理选择。把它当作“已冻结但稳定”的基础能力，减少无收益的迁移。

路径二：并行引入 Gateway API

如果团队正在新增共享入口，或已经出现大量实现专用注解，可以让新的域名或新服务先使用 Gateway API，保留旧 Ingress 处理已验证的流量。并行阶段重点观察资源所有权、控制器支持矩阵、TLS 处理和回滚方式，不要同时重构所有入口。

路径三：按职责拆分后切换

当 Ingress 对象已经成为平台和应用团队的共同编辑点，或需要标准化的权重、Header 匹配、gRPC 路由和跨命名空间信任时，可以先建立 GatewayClass 与 Gateway，再逐个把应用规则搬到 HTTPRoute 或 GRPCRoute。迁移顺序应当是“先入口、后路由、最后切流”，不要先删除旧对象再寻找新的承载位置。

防复发：用资源边界替代注解堆叠

迁移完成后，可以用下面的检查表减少边界重新变模糊：

• 平台团队只把基础设施能力和 Listener 策略放在 Gateway 层，不把应用路径写回共享入口。
• 应用团队只在 Route 层维护 Host、Path、Header、权重和 Service 后端。
• 跨命名空间附着通过 allowedRoutes 与 parentRefs 明确表达，后端引用另用 ReferenceGrant 授权。
• 依赖控制器专用能力时，记录其扩展字段、支持版本和替代方案，不把它误认为 Gateway API 通用字段。
• 升级或迁移前先查看目标实现的 Gateway API 支持矩阵，区分 Standard、Extended 和 Experimental 能力。

常见问题

Ingress 会被 Kubernetes 立刻删除吗？

不会。官方说明是 Ingress API 已冻结，仍然稳定且不会被移除；只是新的 API 能力不会继续加入 Ingress。

Gateway API 能完全替代所有 Ingress Controller 注解吗？

不能这样概括。Gateway API 为常见路由能力提供了更标准的资源和字段，但控制器专用功能仍可能需要扩展。迁移前必须核对目标实现的支持范围。

HTTPRoute 放在应用命名空间就能自动使用共享 Gateway 吗？

不一定。Gateway Listener 的 allowedRoutes 需要允许来源，HTTPRoute 也要通过 parentRefs 指向 Gateway；如果还要跨命名空间引用后端，则要额外检查 ReferenceGrant。

迁移时应该先把所有 Ingress 删除吗？

不应该。更稳妥的做法是先建立新的资源层次，验证控制器支持和所有权边界，再按域名或服务逐步切换，并保留可回滚路径。

最终，Ingress 与 Gateway API 的区别不只是旧 API 和新 API 的替换关系。Ingress 解决的是“把外部 HTTP/HTTPS 流量接到服务”；Gateway API 进一步回答了“谁管理入口基础设施、谁管理路由、谁有权跨命名空间连接”。当问题已经从单对象配置变成团队协作和能力扩展时，这个职责边界才是迁移的主要收益。