Kubernetes Gateway API按Header拆分路由的配置方法

Kubernetes Gateway API按Header拆分路由，核心就是把条件写进HTTPRoute.spec.rules.matches.headers，再为不同Header值绑定不同的Service。比如灰度请求带上 x-release: canary 时进入新版本，普通请求进入稳定版本；没有Header时再落到默认Service。Gateway API官方地址：https://gateway-api.sigs.k8s.io/

先把 Header 匹配拆成规则与回退服务

这类路由最容易写错的地方，是把“一个请求需要满足的条件”和“多个候选路由”混在一起。HTTPRoute里，一个match内的path、method、headers会一起判断；如果rules下有多个match，则任意一个match成立即可。因而可以把两个版本标记拆成两个独立规则，再用不写matches的规则承接剩余流量。

下面的例子假设Gateway名为edge-gateway，三个Service都在当前命名空间。Header名称匹配不区分大小写，但值仍按你指定的匹配类型判断。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: release-route
spec:
  # 这里引用承载入口流量的Gateway，名称需与集群资源一致
  parentRefs:
    - name: edge-gateway
  rules:
    # 同一个match中的path和Header必须同时满足
    - matches:
        - path:
            type: PathPrefix
            value: /api
          headers:
            - type: Exact
              name: x-release
              value: canary
      backendRefs:
        - name: demo-v2
          port: 8080
    # 稳定版本使用另一个明确的Header值
    - matches:
        - path:
            type: PathPrefix
            value: /api
          headers:
            - type: Exact
              name: x-release
              value: stable
      backendRefs:
        - name: demo-v1
          port: 8080
    # 不写matches时，使用默认的根路径匹配承接未命中请求
    - backendRefs:
        - name: demo-default
          port: 8080

用 Exact 保持灰度标记可控

Exact适合版本标记、租户标识这类离散值：规则看得懂，行为也容易在发布记录里复述。不要一开始就用正则把多个版本揉成一条规则，因为Gateway API对RegularExpression的支持取决于具体实现，正则方言也可能不同。

如果请求还要限制方法，可以把method: GET放进同一match；如果还要限制路径，继续放在同一match里。这样“只有GET请求、路径以/api开头且Header为canary”才会命中，而不是让三个条件各自触发。

应用后检查 Accepted 与后端引用

配置文件能被API Server接受，不等于路由控制器已经接管。先应用，再查看Route的父资源状态和后端引用状态：

# 应用HTTPRoute，让Gateway控制器读取新的路由规则
kubectl apply -f release-route.yaml

# 查看Accepted与ResolvedRefs，分别关注是否已被Gateway接受、后端是否解析成功
kubectl get httproute release-route -o jsonpath='{range .status.parents[*].conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'

正常情况下应能看到Accepted=True，并且后端引用相关条件为True。若Accepted为False，先看parentRefs、Gateway listener的hostname与allowedRoutes；若ResolvedRefs为False，检查Service名称、端口和跨命名空间授权。不要只盯着HTTP 404，因为请求可能根本没有进入这条Route。

用三组请求确认分流没有串线

验证时固定同一个路径，只改变Header，最容易判断规则是否真正按预期工作。下面的命令是复现用示例，返回体中的版本标识应由各Service自行提供：

# 灰度标记应到新版本Service
curl -H 'x-release: canary' http://gateway.example.com/api/health

# 稳定标记应到稳定版本Service
curl -H 'x-release: stable' http://gateway.example.com/api/health

# 不带标记应走默认Service，作为未参与灰度流量的回退路径
curl http://gateway.example.com/api/health

如果三组请求都落到默认服务，先检查请求是否真的到达声明的Gateway地址，再确认控制器是否支持当前Gateway API版本。若canary与stable都命中同一后端，重点看Header拼写、值的大小写、规则缩进以及多个HTTPRoute之间是否存在更具体的匹配。

延伸问答

Header匹配能和路径匹配一起使用吗？

可以。它们写在同一个HTTPRouteMatch中时需要同时满足；如果拆成两个match，就会变成两个可独立命中的候选条件。

Header名称大小写不同会影响匹配吗？

规范要求Header名称匹配不区分大小写，但Header值是否大小写敏感要按具体匹配语义处理，工程上建议统一值的写法。

为什么不建议直接使用正则？

正则属于实现相关能力，不同Gateway控制器的方言和支持程度可能不同。版本灰度通常用多个Exact规则更容易迁移和排查。

跨命名空间后端需要额外配置吗？

需要按Gateway API和控制器规则配置跨命名空间引用权限，例如检查Gateway的allowedRoutes及后端引用所需的ReferenceGrant，不能只改Service名称。