Gateway API 基础概念：GatewayClass、Gateway、HTTPRoute、ReferenceGrant

Gateway API 是 Kubernetes 社区推出的下一代入口流量管理标准，旨在替代传统的 Ingress 资源，提供更丰富的路由语义、更清晰的职责分离以及跨命名空间的资源引用能力。在集群升级场景中，Gateway API 的流量切分与无损切换能力正是建立在其核心资源模型之上。本章将逐一剖析四个最基础的概念：GatewayClass、Gateway、HTTPRoute 和 ReferenceGrant。

2.1 资源模型概览

Gateway API 采用分层抽象模型，将基础设施提供者、集群运维人员和应用开发者的职责解耦。下表展示了四个核心资源的分层关系与职责归属：

2.2 GatewayClass —— 网关实现的抽象

GatewayClass 是集群级别的资源，类似于 StorageClass 对存储后端的抽象。它声明了一种可用的网关实现，并指向对应的控制器。一个集群中可以存在多个 GatewayClass，每个 GatewayClass 对应不同的实现或配置模板。

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

• controllerName：唯一标识控制器的字符串，用于匹配实际运行的网关控制器。
• parametersRef：可选字段，引用一个 ConfigMap 或自定义资源，用于传递实现特定的配置参数。
• description：可选的人类可读描述。

2.3 Gateway —— 网关实例的声明

Gateway 资源代表一个具体的网关实例，它绑定到一个 GatewayClass，并声明监听地址、端口和协议。Gateway 是流量进入集群的入口点，所有路由规则最终都附着在 Gateway 上。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: my-nginx-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            kubernetes.io/metadata.name: default
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: my-tls-secret

• gatewayClassName：引用集群中已存在的 GatewayClass。
• listeners：定义监听端口、协议、TLS 配置以及允许哪些命名空间的路由附着。
• addresses：可选字段，指定网关绑定的 IP 地址或主机名。

2.4 HTTPRoute —— 流量路由规则的核心

HTTPRoute 是 Gateway API 中最常用的路由资源，它定义了如何匹配进入 Gateway 的 HTTP 请求，并将其转发到后端服务。HTTPRoute 支持丰富的匹配条件、过滤器以及流量切分能力，是集群升级中实现无损切换的关键工具。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app-route
  namespace: default
spec:
  parentRefs:
  - name: my-gateway
    sectionName: http
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: app-v1
      port: 8080
      weight: 90
    - name: app-v2
      port: 8080
      weight: 10
  - matches:
    - headers:
      - name: X-Canary
        value: "true"
    backendRefs:
    - name: app-v2
      port: 8080
      weight: 100

• parentRefs：指定该路由附着到哪个 Gateway 的哪个监听器。
• matches：定义匹配条件，支持路径、请求头、查询参数、HTTP 方法等。
• backendRefs：定义后端服务引用，支持权重分配（weight）实现流量切分。
• filters：可选，支持 URL 重写、请求头修改、重定向等高级功能。

2.5 ReferenceGrant —— 跨命名空间引用的安全闸门

Gateway API 默认不允许跨命名空间引用资源（例如：命名空间 A 的 HTTPRoute 引用命名空间 B 的 Service）。ReferenceGrant 资源提供了一种显式的授权机制，允许资源所有者开放特定跨命名空间引用。

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-cross-ns-ref
  namespace: backend-ns
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: frontend-ns
  to:
  - group: ""
    kind: Service

• from：指定允许哪些来源资源（group、kind、namespace）发起引用。
• to：指定允许被引用的目标资源类型（group、kind）。
• 作用范围：ReferenceGrant 只能授权其所在命名空间内的资源被外部引用。

2.6 四个核心资源的协作关系

在集群升级的流量切分场景中，这四个资源按照以下流程协同工作：

1. 基础设施层：平台管理员创建 GatewayClass，指定网关控制器类型（如 nginx、istio）。
2. 入口层：运维人员创建 Gateway 实例，绑定 GatewayClass，声明监听端口和 TLS 配置。
3. 路由层：应用开发者创建 HTTPRoute，附着到 Gateway，定义流量匹配规则和后端权重。
4. 授权层：如果后端服务位于不同命名空间，目标命名空间管理员创建 ReferenceGrant 授权跨命名空间引用。