用注解做灰度
内置入口控制器支持通过注解声明金丝雀规则：在主入口对象之外再加一个带金丝雀标记的对象，把一部分流量导到新版本服务。分流方式可以是按比例随机，也可以按请求头匹配。相比额外部署一套网关，这种方式改动小，适合快速验证新版本表现。
基本信息
| 适用组件 | ingress-nginx 控制器 |
|---|---|
| 实现方式 | 金丝雀注解作用于入口对象 |
| 分流方式 | 按权重比例或按请求头 |
| 优先级 | 按请求头高于按权重 |
| 收尾动作 | 把主对象切到新版本后删除金丝雀对象 |
典型使用场景
- 新版本先放少量真实流量，观察错误率与延迟
- 内部测试人员用请求头命中新版本，其他用户不受影响
- 发布前验证新版本在真实流量下的兼容性
- 数据库或下游改造期间做双向对比
- 紧急回退时只需调整权重或删除金丝雀对象
金丝雀入口对象
金丝雀入口对象
metadata:
name: web-canary
annotations:
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-weight: "20" # 约 20% 请求
# 或按请求头匹配：
# nginx.ingress.kubernetes.io/canary-by-header: "x-canary"
# nginx.ingress.kubernetes.io/canary-by-header-value: "always"
spec:
ingressClassName: nginx
rules:
- host: app.example.com # 必须与主对象一致
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-v2
port:
number: 80观察与收尾
观察与收尾
kubectl get ingress -n prod | grep canary # 确认金丝雀对象存在
kubectl -n ingress-nginx logs deploy/ingress-nginx-controller --tail=100 | grep -i canary
curl -s -H 'x-canary: always' http://app.example.com/version # 验证命中新版本
# 验证通过后：把主对象切到新版本，删除金丝雀对象分流参数读法
| 注解 | 作用 | 注意点 |
|---|---|---|
| 启用标记 | 声明该对象为金丝雀规则 | 缺少它与主对象无异 |
| 权重 | 按比例随机分流 | 请求级分布，不保证会话粘性 |
| 按请求头 | 命中特定请求头才分流 | 优先级高于权重 |
| 主对象规则 | 承载基准流量 | 主机与路径必须与金丝雀一致 |
按请求头的分流方式优先级更高：命中请求头的请求会走新版本，其余请求按权重比例分配。测试人员可用固定请求头稳定命中新版本，便于复现问题。
权重是请求级随机分布，不代表会话粘性。有状态或强依赖会话的业务，用请求头方式分流更可控，也更便于回退。