2. 核心概念详解：GatewayClass、Gateway、HTTPRoute、ReferenceGrant、BackendTLSPolicy

Gateway API 的资源模型采用分层解耦设计，将基础设施、流量路由与安全策略分离。本章深入剖析五个核心资源：GatewayClass（基础设施抽象）、Gateway（入口点）、HTTPRoute（路由规则）、ReferenceGrant（跨命名空间授权）和 BackendTLSPolicy（后端 TLS 安全策略）。理解这些资源的关系是掌握 Gateway API 架构的关键。

2.1 资源模型总览

Gateway API 的资源模型遵循“提供者-消费者”模式，通过分层抽象实现基础设施与应用的解耦。下表总结了五个核心资源的作用域与职责：

2.2 GatewayClass：基础设施抽象层

GatewayClass 是 Gateway API 的顶层抽象，类似于 Ingress 中的 IngressClass。它定义了一类网关实现（如：基于 Envoy 的 Contour、基于 Nginx 的 ingress-nginx、基于 Istio 的 Istio Gateway），并指定了对应的控制器名称和参数。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: custom-envoy-proxy
    namespace: envoy-gateway-system

• controllerName：唯一标识控制器的字符串，决定了哪个控制器负责管理该 GatewayClass 的实例。
• parametersRef：可选字段，引用一个自定义资源（CRD）来传递控制器特定的配置参数。
• description：可选，用于描述该 GatewayClass 的用途。

2.3 Gateway：流量入口点

Gateway 资源声明了一个具体的网络入口点，它绑定到一个 GatewayClass，并定义监听器（Listener）的协议、端口和 TLS 配置。Gateway 是基础设施与路由规则的桥梁。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: infra
spec:
  gatewayClassName: eg
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            environment: production
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: prod-tls
    allowedRoutes:
      namespaces:
        from: All

Gateway 的核心字段包括：

• gatewayClassName：引用一个已存在的 GatewayClass。
• listeners：定义监听器列表，每个监听器包含协议、端口、TLS 配置和路由访问控制。
• addresses：可选，指定网关的 IP 地址或主机名。

2.4 HTTPRoute：流量路由规则

HTTPRoute 是应用开发者最常操作的资源，它定义了 HTTP 流量的匹配条件、转发目标和高级路由特性（如：重定向、重写、镜像）。HTTPRoute 通过 parentRefs 字段绑定到一个或多个 Gateway 监听器。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-route
  namespace: apps
spec:
  parentRefs:
  - name: prod-gateway
    namespace: infra
    sectionName: https
  hostnames:
  - "api.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1/
    backendRefs:
    - name: v1-svc
      port: 8080
    - name: v2-svc
      port: 8080
      weight: 10
  - matches:
    - headers:
      - type: Exact
        name: env
        value: canary
    backendRefs:
    - name: canary-svc
      port: 8080

HTTPRoute 的核心特性：

• parentRefs：指定该路由绑定到哪个 Gateway 的哪个监听器（通过 sectionName）。
• hostnames：定义路由匹配的域名列表。
• rules：路由规则列表，每个规则包含匹配条件（路径、头、查询参数、方法）和后端引用。
• backendRefs：支持权重分配、跨命名空间引用（需 ReferenceGrant）和过滤器。

2.5 ReferenceGrant：跨命名空间授权

Gateway API 默认不允许跨命名空间引用资源（如：apps 命名空间的 HTTPRoute 引用 infra 命名空间的 Gateway）。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
    name: backend-svc

ReferenceGrant 的字段说明：

2.6 BackendTLSPolicy：后端 TLS 安全策略

BackendTLSPolicy 用于配置网关到后端服务之间的 TLS 连接。当后端服务要求 TLS 加密时（如：mTLS、自定义 CA 证书），通过该资源定义网关的 TLS 客户端行为。

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendTLSPolicy
metadata:
  name: backend-tls-policy
  namespace: apps
spec:
  targetRef:
    group: ""
    kind: Service
    name: secure-backend
  tls:
    caCertRefs:
    - name: custom-ca
      group: ""
      kind: ConfigMap
    hostname: backend.internal.example.com

BackendTLSPolicy 的关键配置：

• targetRef：指定该策略应用的目标 Service。
• tls.caCertRefs：引用包含 CA 证书的 ConfigMap 或 Secret，用于验证后端服务证书。
• tls.hostname：用于 SNI（Server Name Indication）和证书验证的主机名。

2.7 资源关系与数据流

下图展示了五个核心资源之间的引用关系和流量处理流程：

数据流路径：

1. 客户端请求到达 Gateway 定义的监听器（IP:Port）。
2. Gateway 根据 hostnames 和监听器配置，将请求分发给匹配的 HTTPRoute。
3. HTTPRoute 根据 matches 规则（路径、头、查询参数）选择对应的 backendRefs。
4. 请求被转发到 Backend Service，如果配置了 BackendTLSPolicy，则使用 TLS 加密连接。
5. ReferenceGrant 确保跨命名空间引用的合法性，防止未授权访问。

2.8 资源依赖与生命周期

理解资源的创建顺序和依赖关系对于正确部署至关重要：

2.9 常见问题与避坑指南

• Gateway 状态未就绪：检查 GatewayClass 的 controllerName 是否与集群中部署的控制器匹配。使用 kubectl get gatewayclass 确认控制器已注册。
• HTTPRoute 未生效：确认 parentRefs 中的 sectionName 与 Gateway 监听器的 name 完全匹配（区分大小写）。
• 跨命名空间引用失败：检查目标命名空间中是否存在正确的 ReferenceGrant，且 from 和 to 字段配置正确。
• 后端 TLS 连接失败：确认 BackendTLSPolicy 中的 caCertRefs 引用的 ConfigMap 或 Secret 存在且包含正确的 CA 证书。
• 权重路由不生效：确保所有 backendRefs 的 weight 字段都显式设置，未设置权重的后端默认权重为 1。