3. Gateway API 核心概念回顾：GatewayClass、Gateway、HTTPRoute、BackendRef 等资源模型

在深入网格延迟场景的观测标签体系之前，必须统一对 Gateway API 核心资源模型的理解。Gateway API 采用分层解耦的设计哲学，将基础设施、网关实例、路由规则与后端服务分离，为可观测性标签的注入提供了天然的挂载点。

3.1 四层资源模型概览

Gateway API 的核心资源模型由四个关键对象构成，它们共同定义了从集群入口到后端服务的完整流量路径：

资源对象 作用域 核心职责 观测标签挂载点
GatewayClass 集群 定义网关实现类型（如 Istio、Contour、NGINX） 实现版本、控制器名称
Gateway 命名空间 实例化网关，绑定监听器与地址 网关名称、监听器端口、协议
HTTPRoute 命名空间 定义 HTTP 流量路由规则（匹配、转发、重试） 路由名称、主机名、匹配路径
BackendRef 命名空间 引用后端 Service 或 自定义资源 后端名称、端口、权重
关键理解： 这四层资源构成了一个声明式流量治理栈。每一层都可以附加标签（Labels）和注解（Annotations），这些元数据在网格延迟场景中会被自动提取为观测标签，形成从入口到后端的全链路上下文。

3.2 资源关系与流量流向

下图展示了 Gateway API 四层资源之间的引用关系与流量流向。理解这一拓扑是后续配置观测标签的基础。

Gateway API 四层资源模型与流量流向 GatewayClass istio-gateway-class spec.controllerName Gateway listeners[0].port: 80, protocol: HTTP spec.parentRefs HTTPRoute hostnames: ["api.example.com"], matches: ["/users/*"] spec.rules[0].backendRefs BackendRef name: users-svc, port: 8080, weight: 100
流量路径总结： 外部请求 → Gateway（监听端口） → HTTPRoute（路由匹配） → BackendRef（后端转发）。GatewayClass 作为工厂类，决定了网关实例的行为实现。

3.3 核心资源详解

3.3.1 GatewayClass：基础设施抽象

GatewayClass 是集群级别的资源，类似于 StorageClass 对存储的抽象。它定义了网关的控制器实现和参数引用。在网格延迟场景中，GatewayClass 的标签可用于区分不同网格控制面的版本。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: istio
  annotations:
    # 观测标签：标识控制器版本
    mesh.observability.io/controller-version: "1.20.0"
spec:
  controllerName: istio.io/gateway-controller
  parametersRef:
    group: istio.io
    kind: IstioGatewayConfig
    name: default

3.3.2 Gateway：流量入口实例

Gateway 资源实例化一个具体的网关，绑定监听器（Listener）并分配地址。每个监听器可以关联多个 HTTPRoute。在延迟观测中，Gateway 的 listeners 字段直接决定了入口延迟的采集维度。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: mesh-ingress
  labels:
    # 观测标签：网关环境与用途
    mesh.observability.io/env: "production"
    mesh.observability.io/gateway-role: "ingress"
spec:
  gatewayClassName: istio
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            mesh.observability.io/route-scope: "external"

3.3.3 HTTPRoute：路由规则引擎

HTTPRoute 是流量治理的核心，它定义了主机名匹配、路径匹配、过滤器（如重定向、重写）以及后端转发。在网格延迟场景中，HTTPRoute 的匹配规则直接对应观测标签中的 route_name、host 和 path 维度。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: users-api-route
  namespace: mesh-ingress
  labels:
    # 观测标签：路由所属服务与版本
    mesh.observability.io/service: "users-api"
    mesh.observability.io/route-version: "v2"
spec:
  parentRefs:
  - name: prod-gateway
    sectionName: http
  hostnames: ["api.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /users
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: X-Mesh-Route
          value: "users-api-v2"
    backendRefs:
    - name: users-svc
      port: 8080
      weight: 100

3.3.4 BackendRef：后端服务引用

BackendRef 是路由规则的终点，它引用 Kubernetes Service 或其他自定义资源。BackendRef 支持权重分配和条件转发，是网格延迟场景中后端延迟分布观测的关键对象。

注意： BackendRef 的 weight 字段在灰度发布和金丝雀部署中直接影响延迟百分位分布。观测标签体系需要将 backendRef.name 和 backendRef.weight 作为核心维度，以便区分不同版本后端的延迟表现。

3.4 资源模型与观测标签的映射关系

下表总结了四层资源模型与网格延迟观测标签之间的直接映射关系，这是后续章节配置标签采集规则的理论基础：

资源层 K8s 元数据字段 映射的观测标签 延迟场景用途
GatewayClass metadata.name, spec.controllerName gateway_class, controller 区分不同网格控制面的延迟基线
Gateway metadata.name, metadata.namespace, spec.listeners[].port gateway, gateway_namespace, listener_port 按入口网关维度聚合延迟
HTTPRoute metadata.name, spec.hostnames[], spec.rules[].matches[].path route_name, host, path 按路由规则维度分析延迟
BackendRef name, port, weight backend_name, backend_port, backend_weight 按后端服务维度对比延迟

3.5 资源模型在网格延迟场景中的协作关系

为了更直观地展示四层资源在延迟观测中的协作方式，下图以一次完整的 HTTP 请求为例，标注了每一层资源贡献的观测标签：

延迟观测标签在资源模型中的注入与传递 HTTP 请求 Gateway 标签: gateway, listener_port HTTPRoute 标签: route_name, host, path BackendRef 标签: backend_name 延迟观测标签注入点 每一层资源在请求处理时，将其元数据注入到请求上下文的观测标签中，形成完整的延迟链路。 标签传递示例（请求 api.example.com/users/profile） 1. Gateway 注入: gateway=prod-gateway, listener_port=80 2. HTTPRoute 注入: route_name=users-api-route, host=api.example.com, path=/users/* 3. BackendRef 注入: backend_name=users-svc, backend_port=8080, backend_weight=100 最终观测标签集: {gateway, listener_port, route_name, host, path, backend_name, backend_port, backend_weight}
核心结论： Gateway API 的四层资源模型天然支持分层标签注入。在网格延迟场景中，每一层资源都可以独立贡献观测维度，最终汇聚成一个包含 8 个以上核心标签的上下文对象，为延迟分析提供精细化的数据基础。
← 上一章 📖 返回目录 下一章 →