2. Gateway API 基础回顾：GatewayClass、Gateway、HTTPRoute 核心资源模型

在深入集群升级场景下的路由冲突排查之前，必须牢固掌握 Gateway API 的三大核心资源：GatewayClass、Gateway 和 HTTPRoute。这三者构成了从“基础设施抽象”到“流量路由规则”的完整分层模型，理解它们的关系是诊断优先级冲突的前提。

2.1 三层资源模型概述

Gateway API 的设计哲学是“关注点分离”，将网络基础设施的声明、流量入口的配置、路由规则的编写分别交给不同的角色（基础设施运维、集群管理员、应用开发者）。

2.2 GatewayClass：基础设施的抽象层

GatewayClass 类似于 Ingress 中的 IngressClass，但它更加强调“实现”的概念。它描述了一类可以由特定控制器（Controller）管理的负载均衡器。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example-gateway-class
spec:
  controllerName: "example.io/gateway-controller"
  parametersRef:
    group: example.io
    kind: ConfigMap
    name: gateway-config
    namespace: gateway-system
  description: "用于生产环境的示例 GatewayClass，基于 Nginx 实现"

• controllerName：唯一标识实现该 GatewayClass 的控制器。集群中不能有两个 GatewayClass 使用相同的 controllerName。
• parametersRef：可选字段，引用一个包含控制器特定配置的对象（如 ConfigMap），用于定制该 GatewayClass 的行为。
• description：人类可读的描述，用于文档化。

2.3 Gateway：流量入口的声明

Gateway 资源代表一个具体的网络流量入口点。它定义了监听器（Listener）的端口、协议、TLS 配置，并关联到一个 GatewayClass。

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

• gatewayClassName：引用集群中已存在的 GatewayClass。
• listeners：定义监听端口和协议。每个监听器可以独立控制哪些命名空间的路由可以绑定到它（通过 allowedRoutes）。
• addresses：可选字段，可以请求特定的 IP 地址或主机名。

Gateway 的状态（Status）字段会反映其是否被控制器成功调和（Reconciled），以及每个监听器的就绪状况。这是排查升级后路由不可达问题的第一站。

2.4 HTTPRoute：路由规则的载体

HTTPRoute 是应用开发者最常接触的资源。它定义了如何匹配进入 Gateway 的 HTTP 请求，并将其转发到后端服务。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app-route
  namespace: default
spec:
  parentRefs:
  - name: prod-gateway
    sectionName: http
  hostnames:
  - "app.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api-service
      port: 8080
      weight: 90
    - name: api-service-canary
      port: 8080
      weight: 10
  - matches:
    - headers:
      - type: Exact
        name: X-Environment
        value: staging
    backendRefs:
    - name: staging-service
      port: 8080

• parentRefs：指定该路由要绑定到哪个 Gateway 的哪个监听器（通过 sectionName）。这是路由与入口点关联的关键。
• hostnames：定义该路由匹配的域名。多个路由可以绑定到同一个 Gateway，通过 hostname 进行区分。
• rules：核心路由规则。包含匹配条件（路径、Header、查询参数、方法）和后端引用（支持权重分配）。

2.5 核心资源关系图

下图展示了 GatewayClass、Gateway、HTTPRoute 之间的绑定与依赖关系，以及它们在集群中的角色划分。

2.6 路由优先级与冲突基础

当多个 HTTPRoute 绑定到同一个 Gateway 监听器时，Gateway API 定义了明确的优先级规则。理解这些规则是排查冲突的基础。

• Hostname 精确匹配优先：精确匹配的 hostname 优先级高于通配符（如 *.example.com）。
• 路径匹配长度优先：在相同 hostname 下，路径匹配规则按“最长匹配”原则排序。例如 /api/v2 的优先级高于 /api。
• 规则顺序：如果匹配条件完全相同，则按照 HTTPRoute 规则在 spec.rules 中出现的顺序进行匹配。
• 跨命名空间冲突：如果多个命名空间的 HTTPRoute 都绑定到同一个 Gateway，且 hostname 和路径匹配重叠，则优先级由 spec.parentRefs 中的 group 和 sectionName 决定，但最终行为取决于控制器的实现。

2.7 资源状态与就绪性

每个核心资源都有丰富的状态字段，用于反映其当前是否就绪。在升级后，检查这些状态是诊断问题的第一步。