📚 课程目录第3章回滚护栏概念详解

3. Gateway API 基础：资源模型与传统 Ingress 对比

Gateway API 是 Kubernetes 社区推出的下一代入口流量管理标准，旨在解决传统 Ingress 在表达能力、角色划分和扩展性上的不足。本章聚焦其核心资源模型——GatewayClass、Gateway、HTTPRoute，并通过与传统 Ingress 的对比，帮助学员建立清晰的架构认知。

3.1 三大核心资源模型

Gateway API 将流量治理拆解为三个独立且可组合的资源层，每一层对应不同的关注点与角色。

资源名称	作用域	核心职责	典型管理者
GatewayClass	集群级	定义网关的实现类型（如：nginx、istio、contour）	平台管理员 / 基础设施团队
Gateway	命名空间级	声明网关实例的监听端口、协议、证书及关联的 GatewayClass	平台运维 / 网络管理员
HTTPRoute	命名空间级	定义 HTTP 流量的路由规则（路径匹配、Header 改写、后端转发）	应用开发者 / 业务团队

角色解耦设计： 传统 Ingress 将所有配置集中在一个资源中，导致平台团队与应用团队职责不清。Gateway API 通过三层模型实现了关注点分离，平台团队管控 GatewayClass 和 Gateway，应用团队仅需操作 HTTPRoute，互不干扰。

3.2 资源模型关系图

下图展示了 GatewayClass、Gateway、HTTPRoute 之间的层级关联与数据流方向：

3.3 核心资源详解

3.3.1 GatewayClass

GatewayClass 是集群的入口点，类似于 StorageClass 之于存储。它声明了网关控制器的实现名称和参数。平台管理员只需安装一次 GatewayClass，后续所有 Gateway 实例均可引用。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx-gateway-class
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: ""
    kind: ConfigMap
    name: nginx-gateway-config
    namespace: gateway-system

3.3.2 Gateway

Gateway 代表一个具体的网关实例，负责监听指定的端口和协议。它通过 gatewayClassName 字段关联 GatewayClass，并通过 listeners 数组声明监听规则。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: default
spec:
  gatewayClassName: nginx-gateway-class
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - name: example-tls

3.3.3 HTTPRoute

HTTPRoute 是应用团队最常操作的资源，它定义了 HTTP 流量的匹配条件和后端转发目标。支持路径前缀匹配、精确匹配、Header 匹配、权重分流等高级特性。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-route
  namespace: default
spec:
  parentRefs:
  - name: prod-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api-service
      port: 8080
      weight: 90
    - name: api-service-canary
      port: 8080
      weight: 10

3.4 与传统 Ingress 的对比

传统 Ingress 资源在 Kubernetes 早期解决了外部流量接入问题，但随着微服务规模和治理需求的增长，其局限性日益明显。下表从多个维度进行对比：

对比维度	传统 Ingress	Gateway API
资源模型	单一资源，所有配置耦合	三层解耦：GatewayClass / Gateway / HTTPRoute
角色分离	平台与应用共用同一资源，权限难控制	平台管 Gateway，应用管 HTTPRoute，天然隔离
协议支持	仅 HTTP/HTTPS，扩展需注解	原生支持 HTTP、HTTPS、TCP、UDP、TLS 直通
路由匹配	仅 Host + Path 前缀	支持 Path 前缀/精确/正则、Header、QueryParam、Method
流量分发	仅简单轮询	支持权重分流、镜像、重定向、自定义过滤器
跨命名空间	不支持，需手动复制规则	HTTPRoute 可引用其他命名空间的 Service（需 ReferenceGrant）
扩展性	依赖注解，无标准扩展点	提供 Policy 资源、自定义过滤器、BackendTLSPolicy 等标准扩展
回滚能力	无原生回滚，需手动恢复旧 Ingress	结合 HTTPRoute 版本管理，支持声明式回滚（本课程核心主题）

  关键结论： Gateway API 并非简单替代 Ingress，而是将入口治理从“单资源配置”升级为“面向角色的声明式架构”。对于平台门户联动和回滚护栏设计，Gateway API 的三层模型提供了天然的策略注入点和版本控制边界。

3.5 传统 Ingress 的痛点图示

下图直观对比了传统 Ingress 的“扁平耦合”架构与 Gateway API 的“分层解耦”架构：

3.6 迁移建议与避坑指南

不要一次性替换所有 Ingress： Gateway API 支持与 Ingress 共存，建议从非核心业务开始灰度迁移。
注意 GatewayClass 的 controllerName 唯一性： 集群中不能存在两个相同 controllerName 的 GatewayClass，否则 Gateway 无法确定使用哪个实现。
HTTPRoute 的 parentRefs 必须指向已存在的 Gateway： 如果 Gateway 尚未就绪，HTTPRoute 将处于 Accepted=False 状态，流量不会生效。
跨命名空间引用需配合 ReferenceGrant： 默认 HTTPRoute 只能引用同命名空间的 Service，跨命名空间必须显式授权。

常见陷阱： 部分 Gateway 实现（如旧版 Contour）对 HTTPRoute 的 path 匹配类型支持不完整。迁移前务必查阅实现文档，确认 PathPrefix 和 Exact 是否都受支持，避免生产环境路由失效。