Ingress可通过nginx.ingress.kubernetes.io/canary-by-header等注解基于请求头实现灰度路由，需同时配置canary: "true"和canary-by-header指定Header名，支持固定值、always/never布尔值、正则匹配三种策略，且灰度Ingress须与主Ingress的host和path完全一致。
Ingress 可以通过 nginx.ingress.kubernetes.io/canary-by-header 等注解，基于请求头实现灰度流量的精准路由。核心在于：启用 Canary 模式后，用 Header 名称 + 值匹配规则，把符合条件的请求定向到新版本服务，其余请求仍走主服务。
必须配置的两个基础注解
要启用 Header 灰度，以下两个 annotation 缺一不可：
- nginx.ingress.kubernetes.io/canary: "true" —— 标识该 Ingress 是灰度入口（Canary Ingress），必须单独创建一个专用于新版本的 Ingress 资源
-
nginx.ingress.kubernetes.io/canary-by-header: X-Env —— 指定要检查的请求头字段名，比如
X-Env、X-User-ID或X-Release-Stage
Header 值匹配的三种方式
仅指定 Header 名称还不够，还需定义如何判断是否命中灰度条件。支持三种策略，按优先级顺序生效：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
-
固定值匹配：配合
canary-by-header-value使用，例如：nginx.ingress.kubernetes.io/canary-by-header-value: "staging"
当请求含X-Env: staging时，流量进入灰度服务 -
布尔关键字匹配：直接使用
"always"或"never"（无需额外 value 注解）：nginx.ingress.kubernetes.io/canary-by-header: X-Is-Gray
若请求头为X-Is-Gray: always→ 强制灰度；X-Is-Gray: never→ 强制跳过灰度 -
正则表达式匹配：用
canary-by-header-pattern，例如：nginx.ingress.kubernetes.io/canary-by-header-pattern: "^v2\..*"
匹配X-Version: v2.1.0或X-Version: v2.3-alpha等
实际配置示例（YAML 片段）
假设你已部署了 v1-service（主版本）和 v2-service（灰度版本），需为 v2 单独创建 Canary Ingress：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ingress-canary
annotations:
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "X-Release-Stage"
nginx.ingress.kubernetes.io/canary-by-header-value: "preview"
spec:
ingressClassName: nginx
rules:
- http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: v2-service
port:
number: 80
此时，所有带 X-Release-Stage: preview 的请求都会被路由到 v2-service，其他请求继续由主 Ingress 的 v1-service 处理。
注意事项与常见陷阱
实际落地时要注意几个关键点：
- Header 名称区分大小写，但 HTTP 协议规范中 Header 字段名不区分大小写；建议统一用
kebab-case格式（如X-User-Id），避免因客户端大小写不一致导致匹配失败 - 多个 Canary 规则共存时，
canary-by-header优先级最高，会覆盖canary-by-cookie和canary-weight；若同时配置了 header 和 weight，header 匹配成功就走灰度，不看权重 - Header 值中若含空格或特殊字符（如中文、下划线），需确保客户端发送时未被编码或截断；建议在测试时用
curl -H "X-Env: staging" http://your.domain/直接验证 - 灰度 Ingress 必须和主 Ingress 的 host + path 完全一致，否则无法参与同一组路由决策
