Kubernetes Gateway API 替换 Ingress 时要核对哪些路由

Kubernetes Gateway API 替换 Ingress 时，最该核对的不是资源名称，而是每条请求最终会命中哪个 Listener、HTTPRoute 和 Service。Ingress 把入口和路由规则压在一个对象里；Gateway API 则把它拆成 GatewayClass、Gateway、HTTPRoute 等资源。迁移前应先逐条盘点域名、路径、后端端口、TLS 和注解，再检查新实现是否保留了原来的访问结果。

先建立“旧 host/path/backend → 新 listener/HTTPRoute/backendRefs”的映射表，再迁移。只要 hostname 没有交集、Route 没有成功附着，或注解行为没有替代方案，配置即使能通过 YAML 解析，也不代表请求会到达原来的 Service。

官方资料入口：https://kubernetes.io/docs/concepts/services-networking/gateway/

先把每条 Ingress 规则拆成三列

迁移清单的第一列写原 Ingress 的 host 与 path，第二列写它实际依赖的入口和控制器，第三列写 Service 名称、端口以及是否经过重写、跳转、鉴权或限流。这样能把“看起来只是换 API”的工作，变成一组可验证的请求契约。

GatewayClass、Gateway 与 HTTPRoute 要先对上层级

Ingress 控制器通常隐含提供 HTTP/HTTPS 入口；Gateway API 要显式创建 Gateway，并在 Listener 中声明协议、端口、hostname 和允许附着的 Route 类型。GatewayClass 决定由哪个控制器管理 Gateway，Gateway 代表实际承接流量的入口，HTTPRoute.parentRefs 决定路由要挂到哪个 Gateway 或 Listener。

先确认这条链路：GatewayClass 的控制器存在且被接受，Gateway 的 Listener 已进入可编程状态，HTTPRoute 的 parentRefs 指向正确对象。Gateway 默认只接受同命名空间的 Route；如果旧 Ingress 由多个命名空间共同维护，必须重新设计 allowedRoutes，而不是只复制原来的 host。

最容易漏的是 hostname、path 和默认行为

Gateway Listener 与 HTTPRoute 都可能写 hostname。两者没有交集时，Route 不会被接受；通配符也有边界，例如 *.example.com 不等于裸域名 example.com。把原来散落在多份 Ingress 中的域名合并成一条 Route 时，还要检查不同 Route 之间是否出现重叠，避免请求被更具体的规则抢先匹配。

路径也不能只看字符串。Gateway API 的 Exact 是大小写敏感的精确匹配，PathPrefix 按路径元素匹配，/api 会匹配 /api/v2，但不会匹配 /apiv2。Ingress 的 Prefix 通常可以对应 PathPrefix；ImplementationSpecific 则必须查所选控制器的实现说明。还要专门测试 /、带尾斜杠路径、未匹配路径，以及原 Ingress 的默认后端行为。

跨命名空间、TLS 和注解不能按名称硬搬

如果 HTTPRoute 要引用另一个命名空间的 Service，backendRefs.namespace 之外还需要在被引用资源所在命名空间创建 ReferenceGrant。没有授权时，Route 的 ResolvedRefs 应显示为失败，不能把这类问题当作后端暂时不健康。Gateway 引用其他命名空间的 Secret 也适用同样的显式授权思路。

TLS 迁移要核对 Listener 的 HTTPS 协议、终止模式、证书 Secret、SNI 域名和 HTTP 到 HTTPS 的跳转。原 Ingress 注解中的 URL 重写、请求头修改、灰度权重、鉴权、限流或 body 大小限制，不一定都有相同的核心字段；应逐条标记为 Gateway API 核心能力、扩展能力或控制器私有策略，并在选型文档里记录缺口。

用状态条件和灰度流量完成迁移验收

新对象部署后，先看 GatewayClass、Gateway 和 HTTPRoute 的状态条件，再发真实的 Host、路径、协议和异常请求。至少覆盖每个域名的首页、最具体路径、未匹配路径、HTTP/HTTPS、证书错误、后端不存在和跨命名空间引用失败场景。只有当日志中的 upstream、状态码和延迟与旧入口基线相符，才适合切换 DNS、LoadBalancer 地址或上游反向代理。

迁移最好保持一段时间的双轨运行：旧 Ingress 保留回退能力，新 Gateway 使用独立入口接收灰度流量。回退开关应明确写进发布流程，尤其是证书续期、重写规则和鉴权策略未完成时，不要因为 Gateway 对象显示 Programmed=True 就认定业务路由完全等价。

常见问题

Gateway API 能把 Ingress YAML 直接改名吗？

不能。Gateway API 是 Ingress 的后继 API，但资源模型、入口归属和 Route 附着方式不同，需要一次转换并重新验证实现特性。

HTTPRoute 的 hostnames 一定要写吗？

不一定。省略时可由路由规则匹配更广的流量，但仍受 Listener 的 hostname 和附着条件限制；生产迁移通常应明确写出业务域名。

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

优先检查 parentRefs、Listener 的 allowedRoutes、hostname 是否相交，以及后端引用的 ResolvedRefs。跨命名空间时再检查 ReferenceGrant。

真正的迁移完成标准，是同一组请求在新旧入口上得到一致的路由、TLS 和错误处理结果，而不是新资源已经成功提交。把这份逐条清单保留下来，后续更换 Gateway 控制器时仍可复用。