2. 核心概念回顾：Gateway API 资源模型

在进入多版本路由切换演练之前，必须统一理解 Gateway API 的四个核心资源。它们构成了从“基础设施定义”到“流量路由策略”的完整分层模型，也是后续所有升级与切换操作的操作对象。

2.1 四层资源模型总览

Gateway API 将网络配置拆解为 基础设施提供方 和 服务使用方 两个角色，通过以下四种资源实现职责分离：

2.2 各资源详解

2.2.1 GatewayClass

GatewayClass 是集群范围的入口点，类似于 StorageClass 对存储的角色。它声明了可用的网关控制器实现。一个集群可以有多个 GatewayClass，但每个 Gateway 只能关联一个。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

2.2.2 Gateway

Gateway 资源代表一个具体的网络入口点。它通过 gatewayClassName 引用 GatewayClass，并定义监听器（listeners）的协议、端口、TLS 配置。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gw
  namespace: infra
spec:
  gatewayClassName: eg
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            kubernetes.io/metadata.name: apps

2.2.3 HTTPRoute

HTTPRoute 是应用团队最常操作的资源。它定义主机名、路径匹配、Header 匹配规则，以及将流量转发到哪个后端 Service。一个 HTTPRoute 可以关联多个 Gateway。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: store-route
  namespace: apps
spec:
  parentRefs:
  - name: prod-gw
    namespace: infra
  hostnames:
  - "store.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: store-svc
      port: 8080

2.2.4 ReferenceGrant

当 HTTPRoute 需要引用其他命名空间的 Service，或者 Gateway 需要引用其他命名空间的 Secret 时，必须由目标命名空间的管理员创建 ReferenceGrant 来显式授权。

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-apps-to-infra
  namespace: infra
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: apps
  to:
  - group: ""
    kind: Service

2.3 资源之间的绑定关系

理解以下绑定规则，是后续演练中判断“升级后路由是否生效”的基础：

• Gateway → GatewayClass： 通过 spec.gatewayClassName 绑定，一个 Gateway 只能绑定一个 GatewayClass。
• HTTPRoute → Gateway： 通过 spec.parentRefs 绑定，一个 HTTPRoute 可以绑定多个 Gateway。
• HTTPRoute → Service： 通过 spec.rules[].backendRefs 绑定，默认同命名空间，跨命名空间需要 ReferenceGrant。
• Gateway → Secret： 通过 spec.listeners[].tls.certificateRefs 绑定，跨命名空间同样需要 ReferenceGrant。

2.4 多版本共存时的关键差异

在集群升级过程中，Gateway API 的多个版本（v1alpha2、v1beta1、v1）可能同时存在于集群中。以下是三个主要版本在核心资源上的差异对比：