云原生 Gateway API 迁移路由 怎样处理

我最近把一条由 Ingress 管理的云原生路由拆到 Gateway API 时，最先踩到的坑不是 YAML 语法，而是把“入口”和“路由”当成了同一个对象。更稳妥的做法是：先由 Gateway 定义流量入口、监听器和 TLS，再由 HTTPRoute 描述 hostname、路径和后端 Service；旧 Ingress 不要一上来就删，先让新旧入口并行，确认控制器能力和状态条件后再安排切换。

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

先判断这条路由能不能直接迁

Kubernetes 官方已经把 Ingress API 标记为冻结状态，但这不等于它会立刻消失。迁移的目标也不是追求“资源数量变少”，而是把原来隐含在 Ingress 控制器里的入口职责显式写出来。

我会先看三件事。第一，目标 Gateway 实现是否已经安装 Gateway API CRD，并支持文章要用的稳定资源；第二，原 Ingress 里是否大量依赖控制器专属注解；第三，团队是否愿意把入口权限交给集群运维，把路由权限交给应用开发。前两项决定能不能迁，最后一项决定迁完后权限边界是否真的更清楚。

尤其要注意默认后端、正则路径、重写、认证、超时和健康检查。Gateway API 对其中一部分提供了结构化字段，剩余能力仍可能依赖实现方的扩展资源。看到“有转换工具”不代表所有注解都能原样搬过去。

先搭出一个明确的 Gateway 入口

当前 Gateway API 入门文档给出的标准通道安装示例是把对应版本的 CRD 以 server-side apply 方式安装。实际生产环境还要按所选 Gateway 控制器的安装方式来做，下面只展示迁移文章中的资源边界。

# 先安装目标版本的标准 CRD，具体版本以官方文档和控制器兼容矩阵为准
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.1/standard-install.yaml

Gateway 负责入口。HTTP 和 HTTPS 是两个监听器，HTTPS 的证书仍然来自 Secret；应用路径不要直接塞进 Gateway。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shop-gateway
spec:
  # gatewayClassName 选择实际安装的 Gateway 控制器
  gatewayClassName: prod
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    hostname: "shop.example.com"
  - name: https
    port: 443
    protocol: HTTPS
    hostname: "shop.example.com"
    tls:
      # TLS 终止发生在监听器，证书引用仍指向 Secret
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: shop-example-com

把 Ingress 的 host、path 和 Service 改成 HTTPRoute

HTTPRoute 通过 parentRefs 连接到 Gateway 的监听器，再用 hostnames、matches 和 backendRefs 表达应用路由。这里的 hostname 必须能匹配 Gateway listener 的 hostname，否则监听器会忽略这条路由。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-route
spec:
  # parentRefs 明确这条应用路由挂到哪个 Gateway 监听器
  parentRefs:
  - name: shop-gateway
    sectionName: https
  hostnames:
  - "shop.example.com"
  rules:
  - matches:
    - path:
        # PathPrefix 对应常见 Ingress 前缀路径
        type: PathPrefix
        value: /orders
    backendRefs:
    - name: orders-api
      port: 8080

从 Ingress 迁移时可以这样记：ingressClassName 影响目标 Gateway 的 gatewayClassName，Ingress 的 TLS 主机和证书落到 Gateway listener，host 与 path 规则落到 HTTPRoute，后端 Service 落到 backendRefs。如果原配置有 HTTP 自动跳 HTTPS，通常要单独为 HTTP listener 写一条带 RequestRedirect 的 HTTPRoute，而不是期待 Gateway 自动猜出这层意图。

用转换工具找出遗漏，再保留旧入口并行

面对一批 Ingress，我会先用 Gateway API SIG 维护的 ingress2gateway 生成初稿。它可以读取 Ingress 和部分提供商资源，输出 Gateway API 资源，同时提示未翻译字段；生成结果仍要结合目标控制器文档复查，尤其是注解、正则、重写和策略资源。

# 以 ingress-nginx 为例，把现有资源转换成候选 Gateway API YAML
ingress2gateway print --providers=ingress-nginx

迁移期间不要让新旧控制器争抢同一个入口地址。Gateway API 的 Ingress-NGINX 迁移指南建议可以让两个控制器并行运行，由不同外部地址承载，再在 DNS 或上游负载均衡层安排切换。这样做的重点不是“同时发两份流量”，而是让新路由先拥有独立的复查边界。

我的复查顺序通常是先看资源状态，再看外部地址，最后才改 DNS：

# 只观察新入口的地址和路由状态，避免把旧入口误判为迁移成功
kubectl get gateway shop-gateway -o yaml
kubectl get httproute shop-route -o yaml

重点看 Gateway 是否被目标控制器接管、监听器是否进入可用状态、HTTPRoute 是否已绑定到对应 listener，以及 backendRefs 是否指向预期 Service。这里的状态检查是迁移过程中的操作步骤，不应把一份生成的 YAML 当作线上请求已经成功的证明。

几个容易让迁移结果失真的地方

如果目标只是把一条简单的 host/path 路由迁出 Ingress，上面的 Gateway 加 HTTPRoute 已经足够。若原系统依赖大量实现专属能力，先做一条低风险路由的并行迁移，再决定是否扩大范围，比一次性重写整个入口层更容易回滚。

常见问题

Gateway API 迁移是不是必须马上删除 Ingress？

不是。Ingress API 仍然是稳定 API，只是功能被冻结。迁移可以先安装新控制器、生成并复查 Gateway API 资源，再通过独立外部地址和切换点逐步替换旧入口。

为什么 HTTPRoute 已创建，却没有流量？

优先检查 parentRefs 是否指向正确 Gateway 和 listener、HTTPRoute 的 hostname 是否匹配 listener，以及控制器是否报告了绑定或引用错误。不要只看对象创建成功。

ingress2gateway 生成的 YAML 能直接上线吗？

不能把它当成无条件的最终配置。它适合发现资源映射和未翻译字段，复杂注解、策略、正则和控制器专属行为仍需要按目标实现复查。

官方资料

Gateway API 总览：https://kubernetes.io/docs/concepts/services-networking/gateway/

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

Ingress-NGINX 迁移入口：https://gateway-api.sigs.k8s.io/guides/getting-started/migrating-from-ingress-nginx/

转换工具：https://github.com/kubernetes-sigs/ingress2gateway