Kubernetes Gateway API 生产落地与 Ingress 迁移指南

Gateway API 是 Kubernetes SIG Network 推动的服务网络 API，通过 GatewayClass、Gateway 和 Route 等资源分离基础设施提供者、平台管理员与应用团队职责。它不是某个具体代理，也不同于传统“API 管理网关”。本文覆盖模型、TLS、跨命名空间授权、流量治理、实现选择、Ingress 迁移与生产排障。

Gateway API 只是接口规范，实际数据面行为由所选 Controller 决定。任何字段支持程度、性能、升级和故障行为，都必须结合实现的 Conformance 与版本文档验证。

一、为什么不只使用 Ingress

Ingress 核心模型简单，大量高级能力依靠实现特有注解，导致迁移困难、权限边界模糊。Gateway API 提供角色化、协议化和可扩展模型。

基础设施团队：GatewayClass
平台团队：Gateway、Listener、证书与地址
应用团队：HTTPRoute / GRPCRoute / TCPRoute

它支持核心能力、扩展能力和实现特定能力。不能因为 CRD 接受字段，就假设数据面已经实现。

二、核心资源

GatewayClass：描述由哪个 Controller 管理；
Gateway：实例化入口、地址和 Listener；
HTTPRoute：HTTP 路由、匹配、过滤和后端；
GRPCRoute：gRPC 服务与方法路由；
ReferenceGrant：显式允许跨 Namespace 引用；
其他协议 Route：稳定级别与实现支持需核对。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shared-public
  namespace: gateway-system
spec:
  gatewayClassName: production
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: public

三、实现选择

选择 Controller 时比较：

Gateway API Conformance Profile；
HTTP、gRPC、TCP、UDP 和 Mesh 支持；
云负载均衡、裸金属和多集群能力；
TLS、WAF、认证、限流和可观测性；
配置下发模型与控制面故障行为；
升级、备份和商业支持；
与现有 Ingress/API Gateway 的迁移能力。

生产不要同时让两个 Controller 认领同一 GatewayClass。

四、Listener 与路由绑定

Route 是否生效取决于 ParentRef、Hostname、SectionName、Namespace 允许范围和 Controller 状态。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: retail
spec:
  parentRefs:
    - name: shared-public
      namespace: gateway-system
      sectionName: https
  hostnames: ["shop.example.com"]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: shop-api
          port: 8080

排障时查看 Route status.parents.conditions，不要只看对象创建成功。

五、跨命名空间安全

跨 Namespace 绑定和后端引用需要明确授权。allowedRoutes 控制哪些 Route 可以挂载 Listener；ReferenceGrant 由被引用方创建，防止应用越权引用其他团队的 Service 或 Secret。

安全原则：

默认同 Namespace；
使用标签选择器限制可挂载团队；
证书 Secret 由平台 Namespace 管理；
ReferenceGrant 最小到类型、组和来源；
审计所有跨 Namespace 授权。

六、TLS 模式

常见为 Gateway 终止 TLS，也可采用透传或后端 TLS。需要区分：

客户端到 Gateway；
Gateway 到 Backend；
mTLS 客户端认证；
SNI 与 Hostname；
证书来源、轮换和加载。

证书 Secret 更新后必须从外部检查实际证书，不能只看 cert-manager Ready。

七、HTTP 匹配与过滤

Gateway API 支持 Path、Header、Query、Method 等匹配，以及重定向、重写、Header 修改和镜像等能力。优先级和冲突解析按规范与实现处理。

治理建议：

路由命名包含业务与环境；
避免大范围通配覆盖；
/api 与 /api/ 行为测试；
重写前后路径写入访问日志；
Filter 支持程度在预生产验证；
Route 所有者与 SLO 纳入标签。

八、流量拆分与灰度

backendRefs:
  - name: shop-v1
    port: 8080
    weight: 90
  - name: shop-v2
    port: 8080
    weight: 10

权重是长期统计期望，小样本可能偏差。灰度还需要版本指标、会话、数据库兼容、自动/人工回退和连接排空。Gateway API 不会自动完成业务验证。

九、Backend 健康与超时

不同实现对健康检查、超时和重试的扩展方式不同。需要确认：

连接、请求和空闲超时；
Retry 条件、次数和幂等性；
Backend 全部不健康时的响应；
慢启动和排空；
HTTP/2、gRPC 长连接；
WebSocket 与大文件。

客户端、Gateway 和应用三层超时必须协调，避免上层已超时、下层仍继续执行。

十、GRPCRoute

gRPC 基于 HTTP/2，可按 Service/Method 和 Header 路由。生产验证：

TLS/ALPN；
Unary 与 Streaming；
超时与 Keepalive；
消息大小；
健康检查协议；
gRPC Status 到指标和日志的映射。

普通 HTTP 200 不能代表 gRPC 调用成功，应记录 gRPC Status。

十一、策略扩展

BackendTLSPolicy 等策略资源用于描述后端 TLS。标准与实验通道的稳定性不同。安装/升级 CRD 前：

读取版本升级说明；
盘点现有对象；
核对 Controller 支持版本；
备份 CRD 与资源；
不在资源仍使用时删除 CRD。

删除 CRD 会连同 Custom Resource 一起删除，风险很高。

十二、状态与可观测性

重点 Condition：Accepted、Programmed、ResolvedRefs 等。对象存在不等于已下发。

kubectl get gateway -A
kubectl describe gateway -n gateway-system shared-public
kubectl get httproute -A -o yaml
kubectl logs -n gateway-system deploy/<controller>

指标应覆盖配置下发、拒绝资源、路由数量、证书、请求量、状态码、Gateway 延迟、Backend 延迟、连接和重试。

十三、多租户治理

共享 Gateway 节省成本，但故障域大。建议：

按公网/内网、环境和风险等级拆分；
Listener Hostname 与 Namespace 标签绑定；
设置 Route/证书/域名配额；
防止应用团队修改 GatewayClass；
对关键租户提供独立 Gateway；
变更审计与冲突检测。

十四、从 Ingress 迁移

盘点 IngressClass、Controller、注解、TLS、重写和认证；
将标准能力映射到 Gateway/HTTPRoute；
对特有注解寻找标准 Filter 或实现扩展；
并行部署新入口；
使用测试域名回放流量；
对比状态码、Header、Source IP、延迟和日志；
小比例切换 DNS/负载均衡；
保留回退窗口；
最后删除旧 Ingress。

不要直接批量转换 YAML 后一次性切换。

十五、入口 NGINX 迁移常见遗漏

Regex Path 与 PathType 语义；
Rewrite Target；
Body Size；
Proxy Buffer；
Session Affinity；
Backend Protocol；
External Auth；
Canary Annotation；
Snippet 中隐藏的安全与路由逻辑。

Snippet 往往无法一对一迁移，需要重新评估是否应该保留。

十六、常见故障

Route 未 Accepted

检查 ParentRef、Namespace、allowedRoutes、Hostname、SectionName 和 GatewayClass Controller。

ResolvedRefs=False

检查 Service/Port、Secret、ReferenceGrant、对象 Group/Kind 和权限。

Programmed=False

检查 Controller、负载均衡地址、云配额、数据面 Pod 和配置下发错误。

404

确认 DNS 到正确 Gateway，Host/Path/Method 匹配，Listener 与 Route 绑定且配置已下发。

502/503/504

分别排查后端连接、健康实例、协议/TLS 和超时；结合 Gateway 与应用日志定位。

十七、升级与灾备

备份 CRD、GatewayClass/Gateway/Route、策略、证书引用、Controller 配置与云资源关系。升级顺序遵循实现文档，先验证 CRD 兼容，再灰度 Controller 和数据面。

灾备集群应能重新创建 Gateway 地址、证书和 DNS；若依赖云静态 IP，要记录资源归属和恢复流程。

十八、上线清单

Controller Conformance 和能力矩阵已确认；
GatewayClass、Gateway、Route 权限按角色分离；
跨 Namespace 引用最小授权；
TLS、证书轮换和后端 TLS 已验证；
HTTP、gRPC、WebSocket 和大文件完成测试；
灰度、超时、重试与回滚符合业务语义；
Ingress 注解已逐项迁移或废弃；
状态 Condition、数据面和业务指标均有告警；
CRD 与 Controller 升级完成演练。

参考资料

Gateway API Introduction：https://gateway-api.sigs.k8s.io/docs/introduction/
Gateway API Guides：https://gateway-api.sigs.k8s.io/guides/
Gateway API Reference：https://gateway-api.sigs.k8s.io/reference/spec/

Kubernetes Gateway API 生产落地与 Ingress 迁移指南

Kubernetes Gateway API 生产落地与 Ingress 迁移指南

一、为什么不只使用 Ingress

二、核心资源

三、实现选择

四、Listener 与路由绑定

五、跨命名空间安全

六、TLS 模式

七、HTTP 匹配与过滤

八、流量拆分与灰度

九、Backend 健康与超时

十、GRPCRoute

十一、策略扩展

十二、状态与可观测性

十三、多租户治理

十四、从 Ingress 迁移

十五、入口 NGINX 迁移常见遗漏

十六、常见故障

Route 未 Accepted

ResolvedRefs=False

Programmed=False

404

502/503/504

十七、升级与灾备

十八、上线清单

参考资料

results matching ""

No results matching ""