📚 课程目录第4章灰度发布策略概述

4、灰度发布策略概述：基于权重、基于 Header、基于 Cookie、基于 IP 子网的灰度路由原理

灰度发布（Canary Release）是集群升级中最核心的风险控制手段。其本质是让一小部分流量先经过新版本集群，验证稳定后再逐步扩大范围，最终完成全量切换。Gateway API 通过 HTTPRoute 和 BackendTLSPolicy 等资源，提供了四种主流的灰度路由策略：权重、Header、Cookie 和 IP 子网。本章将逐一剖析它们的原理、适用场景与配置要点。

核心原则：灰度策略可以组合使用。例如，先按 IP 子网限制灰度范围，再在范围内按权重分配流量。Gateway API 的匹配规则支持 AND/OR 逻辑，为复杂场景提供了灵活的基础。

4.1 基于权重的灰度路由

权重路由是最直观的灰度策略。它通过为每个后端服务（BackendRef）分配一个权重值，控制进入该服务的流量比例。Gateway API 的权重是相对权重，即所有后端权重之和作为分母，单个后端权重作为分子。

权重路由的典型配置如下：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-weight
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - backendRefs:
    - name: app-v1
      port: 80
      weight: 90
    - name: app-v2
      port: 80
      weight: 10

特性	说明
调整粒度	1% 起步，可逐步递增（如 1% → 5% → 20% → 50% → 100%）
适用场景	无状态服务、API 接口、微服务调用链
优势	配置简单，实时生效，无需客户端配合
局限	无法区分用户身份，同一用户可能在不同请求中访问不同版本

4.2 基于 Header 的灰度路由

Header 路由通过检查 HTTP 请求头中的特定字段（如 X-Canary、X-Version）来决定流量去向。这种方式允许测试人员或特定客户端通过携带特定 Header 来精确访问灰度版本，实现定向验证。

Header 路由的典型配置：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-header
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - headers:
      - name: X-Canary
        value: "true"
    backendRefs:
    - name: app-v2
      port: 80
  - backendRefs:
    - name: app-v1
      port: 80

  最佳实践：在灰度验证阶段，QA 团队或内部测试人员可以在浏览器插件或 curl 命令中固定添加 X-Canary: true 头，确保每次请求都命中灰度版本。生产环境建议配合权重路由兜底，防止 Header 缺失时流量无法处理。

4.3 基于 Cookie 的灰度路由

Cookie 路由通过检查请求中的 Cookie 值（如 canary_id）来分配流量。与 Header 路由不同，Cookie 由服务端在首次响应时设置，后续请求自动携带，因此可以实现会话保持（Session Stickiness）——同一用户在灰度期间始终访问同一版本。

对比维度	Header 路由	Cookie 路由
客户端控制	客户端主动设置	服务端设置，客户端自动携带
会话保持	不支持（每次请求独立）	支持（Cookie 持久化）
适用场景	API 测试、内部工具	面向用户的 Web 应用、需要体验一致性的场景
配置复杂度	低	中（需配合权重或 Header 使用）

Cookie 路由通常与权重路由配合使用：先按权重将用户分组，再通过 Cookie 标记用户所属版本。Gateway API 的 matches 规则支持直接匹配 Cookie 值：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-cookie
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - headers:
      - name: Cookie
        value: "canary_group=B"
    backendRefs:
    - name: app-v2
      port: 80
  - backendRefs:
    - name: app-v1
      port: 80

注意：Cookie 路由依赖客户端正确携带 Cookie。如果用户清除了浏览器 Cookie 或使用隐私模式，可能会被重新分配到不同版本，导致体验不一致。建议设置较长的 Cookie 过期时间，并在灰度期间避免清除操作。

4.4 基于 IP 子网的灰度路由

IP 子网路由通过检查客户端源 IP 地址是否属于特定 CIDR 范围来决定流量去向。这种方式最适合内部员工验证或特定办公网络先行升级的场景。例如，只允许公司 VPN 网段（10.0.0.0/8）的请求访问灰度版本。

IP 子网路由的配置示例：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-ip
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - sourceIPs:
      - "10.0.0.0/8"
      - "172.16.0.0/12"
    backendRefs:
    - name: app-v2
      port: 80
  - backendRefs:
    - name: app-v1
      port: 80

  安全提示：IP 子网路由依赖客户端源 IP 的真实性。如果网关前面有 CDN 或反向代理，需要确保 X-Forwarded-For 头被正确传递，并在 Gateway API 中启用 trustedProxies 配置，否则所有流量都会被视为代理 IP，导致路由失效。

4.5 四种策略对比总结

策略	匹配依据	会话保持	客户端配合	典型场景
权重	随机概率	否	无需	无状态服务、API 逐步放量
Header	请求头字段	否	需主动设置	QA 定向测试、内部工具
Cookie	Cookie 值	是	自动携带	Web 应用、用户体验一致性
IP 子网	源 IP 地址	是（基于 IP）	无需	内部网络先行升级、办公网验证

组合使用建议：在集群升级的灰度验证中，推荐先使用 IP 子网 + 权重 组合：内部员工通过 IP 子网直接进入灰度版本，外部用户按权重逐步导入。待内部验证通过后，再逐步提升外部用户的权重比例，最终完成全量切换。这种组合既能保证内部体验，又能控制外部风险。