Kubernetes Gateway API 怎样用 HTTPRoute 按请求头分流

在灰度发布里，常见目标是把带有 env: canary 请求头的请求送到 canary Service，其余请求继续走稳定 Service。Kubernetes Gateway API 的 HTTPRoute 可以同时按主机名、路径和请求头匹配；请求头规则只负责选择路由，真正的后端仍由 backendRefs 指向 Kubernetes Service。

官方地址：https://gateway-api.sigs.k8s.io/guides/user-guides/http-routing/

先把生产目标拆成匹配条件和后端

不要一开始就堆完整 YAML。先把目标写成一张小表：主机名限定在 bar.example.com，请求头 env=canary 命中灰度后端，其他同主机请求进入稳定后端。这样做的好处是，后续每个字段都能回到一个明确的业务条件，而不是靠规则顺序猜测。

这里的“普通请求”不是再写一个否定条件，而是用一条没有 matches 的规则承接剩余流量。它比把所有可能的请求头值逐个列出来更容易维护。

用 ParentRefs 把 HTTPRoute 挂到 Gateway

官方用户指南明确要求，HTTPRoute 需要通过 parentRefs 引用父 Gateway，才能接收该 Gateway 的流量。Gateway 负责监听入口，HTTPRoute 负责描述主机名、匹配条件和后端引用；两者不要混成一个对象理解。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-web
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: http
      protocol: HTTP
      port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: bar-route
spec:
  # 把路由挂到入口 Gateway；名称要与目标对象一致
  parentRefs:
    - name: prod-web
  # 先按主机名筛选，再进入下面的请求头匹配
  hostnames:
    - "bar.example.com"
  rules: []

上面的骨架只表达对象边界。实际部署前，还要确认监听器协议、端口和实现该 Gateway API 的控制器都符合当前集群配置；示例中的类名和域名只是可替换占位符。

用 Exact HeaderMatch 建立精确分流规则

把规则补完整时，第一条只匹配 env 请求头的 canary 值，第二条作为同一主机的默认后端。Gateway API 用户指南展示了同类的“带请求头进入专用 Service、未带请求头进入普通 Service”结构；更具体的匹配会优先于更宽的匹配。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: bar-route
spec:
  # HTTPRoute 必须引用接收流量的父 Gateway
  parentRefs:
    - name: prod-web
  hostnames:
    - "bar.example.com"
  rules:
    - matches:
        - headers:
            - type: Exact
              name: env
              value: canary
      backendRefs:
        - name: bar-svc-canary
          port: 8080
    - backendRefs:
        - name: bar-svc
          port: 8080

第一条规则的关键是 headers 下的 type: Exact、name 和 value 三个字段。它表达的是“请求头 env 的值恰好为 canary”，不是模糊包含。第二条规则没有 matches，因此承担该主机下没有命中第一条规则的请求。

复查命名空间、路由合并和发布检查

规则写对后，还要复查三个边界。第一，parentRefs 与后端 Service 的命名空间关系必须符合控制器和 Gateway API 的权限约束；不要因为 YAML 能提交就默认跨命名空间引用已经被授权。第二，同一个 Gateway 可以绑定多个 Route，但只有不冲突的规则才适合合并。第三，发布检查应关注对象状态和引用条件，而不是只看 kubectl apply 返回成功。

# 先提交路由文件；文件名只是示例，不代表本机已执行
kubectl apply -f bar-route.yaml

# 查看 HTTPRoute 的父引用、条件和后端引用状态
kubectl describe httproute bar-route

# 发布前确认 canary 与 stable Service 都存在于预期命名空间
kubectl get service bar-svc-canary bar-svc

排查时优先看 HTTPRoute 的父引用是否已接纳、后端引用是否被拒绝，以及请求实际使用的主机名和请求头是否符合规则。若把多个 HTTPRoute 绑定到同一 Gateway，还要检查它们是否为同一主机定义了互相冲突的匹配条件。

常见问题

请求头没有带 env，为什么还能命中 HTTPRoute？

只要主机名符合，第二条没有 matches 的规则就可以承接剩余流量。它的作用是默认后端，不代表请求头匹配失败。

能不能用一个 HTTPRoute 同时匹配多个主机名？

可以在 hostnames 中声明一组主机名，但不同主机有不同路由要求时，拆成多个 HTTPRoute 通常更容易读和维护。

为什么 apply 成功，流量却没有按请求头分流？

提交成功只说明资源被 API Server 接收。继续查看父引用、后端引用和 Route 条件，并确认请求的主机名、请求头名称和值与规则完全一致。

把入口 Gateway、匹配 HTTPRoute、灰度 Service 和稳定 Service 分开看，按请求头分流就变成了可复查的配置边界：先绑定入口，再精确匹配，最后为剩余请求保留默认后端。