Kubernetes Gateway API 进入新阶段后怎样理解迁移影响

Kubernetes Gateway API 进入新阶段，真正改变的不是“明天必须把所有 Ingress 删除”，而是入口流量的资源模型、职责边界和可移植能力开始有了更完整的标准答案。当前 Ingress API 仍然稳定，但已经冻结；Gateway API 则继续扩展 Standard 能力，尤其是对 HTTP 之外的 TCP、UDP 以及服务网格场景的覆盖。

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

因此，迁移的正确理解是：先把现有 Ingress 中“标准路由”和“控制器私有注解”分开，再让 Gateway API 控制器与旧入口并行，按业务入口逐步切换。Gateway API v1.6 已将 TCPRoute、UDPRoute 提升到 Standard，并将后续实验资源放入 gateway.networking.x-k8s.io；这会影响新资源的选型，却不会自动改变已有 Ingress 对象。

先把“新阶段”拆成三个事实

第一，Ingress 没有被删除。Kubernetes 文档明确说明，Ingress API 已冻结，项目没有移除计划，已有业务可以继续运行。第二，Gateway API 不是 Kubernetes 核心内置的某个单一负载均衡器，而是一组由控制器实现的 CRD；安装哪个控制器、支持哪些扩展，仍然是平台团队要做的选择。第三，Gateway API 的版本节奏与 Kubernetes 集群小版本解耦，升级 Gateway API 并不等同于升级整个集群。

v1.6 的信号在于：TCPRoute 和 UDPRoute 进入 v1 Standard，说明 Gateway API 已从“主要解决 HTTP/HTTPS 入口”继续向更完整的 L4/L7 网络 API 延伸。与此同时，新的实验资源不再和 Standard 资源混在同一个 API 组里，而是使用带 x- 的实验组名。团队审查 YAML 时，应先看 API 组和版本，再判断能否把它当成可迁移的标准契约。

迁移时最先变化的是资源职责

传统 Ingress 把入口、主机路径、TLS 和控制器选择压缩在一个对象里，复杂能力通常靠注解扩展。Gateway API 将这些职责拆开：GatewayClass 表示由哪类控制器实现，Gateway 描述入口监听器，HTTPRoute 或 TCPRoute 描述路由规则，平台或实现方策略再承载认证、超时等不完全标准化的能力。

这个拆分对多团队集群更重要。集群运维可以管理 Gateway 和监听器，应用团队只提交 HTTPRoute；路由通过 parentRefs 显式挂到某个 Gateway，而不是依赖一个模糊的默认入口。迁移时不要只做字段翻译，还要重新确认“谁可以修改哪个对象”。

# Gateway 由平台侧声明入口与监听器，HTTPRoute 由应用侧声明路由
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: platform-network
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: app.example.com
      # TLS 证书仍由 Secret 提供，具体跨命名空间规则需按实现配置
      tls:
        mode: Terminate
        certificateRefs:
          - name: app-example-com
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-route
  namespace: app-team
spec:
  # 通过 parentRefs 显式声明这条路由挂到哪个 Gateway
  parentRefs:
    - name: public-gateway
      namespace: platform-network
      sectionName: https
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      # backendRefs 指向 Service，不把后端地址写进入口对象
      backendRefs:
        - name: app-service
          port: 8080

上面的代码只表达资源关系和权限边界；它不是某个云厂商控制器的完整生产清单。跨命名空间引用、证书引用和策略附着都要按选定实现的文档补齐授权。

旧 Ingress 里的注解不能机械搬家

迁移成本通常藏在注解里，而不在 host、path 和后端 Service 这些显眼字段里。重定向、请求头改写、流量切分等能力已经有一部分对应到 HTTPRoute；认证、连接超时、健康检查等能力，则可能需要 Gateway 实现的策略资源或自定义扩展。也就是说，转换工具可以减少 YAML 手工劳动，却不能替平台团队做兼容性决策。

建议为每条注解建立三种状态：有标准字段可映射、需要控制器策略、暂时没有等价物。第三类不要在迁移时悄悄删除，应保留旧入口或先在影子环境验证替代行为。官方迁移指南也明确提醒，Ingress 的实现特定功能仍要结合源控制器和目标 Gateway 实现判断。

一套更稳妥的迁移落地路径

第一步：盘点入口，而不是先改 YAML

列出每个 Ingress 的控制器、外部地址、域名、TLS Secret、路径匹配、重写规则、认证注解和回滚依赖。特别标出同一域名由多个 Ingress 共享、依赖默认后端或依赖控制器私有行为的对象。没有这张清单，迁移后的“配置成功”可能只是丢掉了旧注解。

第二步：选择控制器并确认支持边界

Gateway API 的资源规范统一，不意味着所有实现的扩展都一致。先确认目标控制器支持的 Gateway API 版本、Standard/Experimental 资源、策略模型、跨命名空间引用和 conformance 信息，再决定首批迁移哪些入口。对核心生产流量，优先选择 Standard 资源；实验组资源应明确记录版本和退出路径。

第三步：并行部署，隔离外部流量

官方迁移建议允许 Gateway API 控制器与原 Ingress-NGINX 并行运行，让两套入口获得不同的外部地址，在不影响生产入口的前提下验证。这个阶段的重点不是把 DNS 立刻切过去，而是比较 TLS、重定向、路径匹配、请求头、超时和后端健康状态。

# 查看 Gateway API 资源的状态条件，重点关注 Accepted 和 Programmed
kubectl get gatewayclass,gateway,httproute -A

# 只读取目标 Gateway 的详细条件，不修改线上对象
kubectl describe gateway public-gateway -n platform-network

# 检查路由是否被目标 Gateway 接受，失败时回到控制器事件与实现文档
kubectl describe httproute app-route -n app-team

命令输出中的条件状态是控制器反馈，不是 Kubernetes API 自动保证的业务可用性。还需要使用测试域名或受控流量验证证书链、状态码、重试和日志。

第四步：按域名或业务单元切换

不要一次性把所有 Ingress 转成一组巨大 HTTPRoute。按域名、团队或风险等级拆分资源，先切低风险业务，再切有认证、重写和跨命名空间引用的入口。每个单元都要保留原 Ingress 清单和 DNS 回退记录，确认新入口稳定后再决定是否删除旧对象。

第五步：把回退写进操作手册

回退不仅是“重新应用旧 YAML”。还应包含 DNS 或负载均衡切回、证书 Secret 的归属、两套控制器的地址、策略资源清理、监控告警和变更窗口。若只是暂停 Gateway API 控制器而保留已切换的 DNS，入口仍可能不可用；回退顺序要按实际流量路径编排。

哪些团队现在就该迁移，哪些可以继续观察

如果团队正在新建平台入口、需要多租户职责分离、需要标准化的流量切分，或者已经使用 TCP/UDP 入口，Gateway API 值得作为新基线。新项目直接采用 Gateway、HTTPRoute、TCPRoute 等 Standard 资源，通常比先写 Ingress 再安排二次迁移更省协调成本。

如果现有 Ingress 只承担稳定的 HTTP/HTTPS 路由，控制器私有注解很多，且近期没有入口改造窗口，则没有必要因为“API 进入新阶段”而强制重写。可以先完成注解盘点、控制器选型和一条低风险域名的并行验证。Ingress 继续可用，但新能力和新团队协作不要再继续堆叠到冻结的 Ingress API 上。

迁移影响速查

相关问题

Ingress 会被 Kubernetes 立即移除吗？

不会。Ingress API 已冻结，但 Kubernetes 文档说明没有移除计划。迁移的主要原因是 Gateway API 的新能力、职责模型和扩展方式，而不是旧对象突然失效。

Gateway API 升级是否必须先升级 Kubernetes 集群？

不一定。Gateway API 项目说明其版本与 Kubernetes 集群版本解耦，但仍需满足所选控制器和 CRD 的支持要求，不能只看集群版本。

Ingress 到 Gateway API 能不能完全自动转换？

可以用 ingress2gateway 等工具辅助生成资源，但工具主要解决结构转换。控制器私有注解、策略、证书权限、外部地址和回滚仍需人工确认。

新项目应该直接使用实验资源吗？

除非确实需要实验能力并接受其变化成本，否则优先使用 Standard 资源。实验资源应记录 API 组、控制器支持范围和未来升级路径。

参考资料

Kubernetes Gateway API v1.6：https://kubernetes.io/blog/2026/08/03/gateway-api-v1-6-release/

Ingress 迁移指南：https://gateway-api.sigs.k8s.io/guides/getting-started/migrating-from-ingress/

Kubernetes Gateway API 概念：https://kubernetes.io/docs/concepts/services-networking/gateway/