4. Ingress-Nginx 的 Canary 特性：注解详解与流量切分

Ingress-Nginx 的 Canary 特性通过一组专用的 nginx.ingress.kubernetes.io/canary-* 注解，在不修改主 Ingress 资源的前提下，动态创建一条灰度流量规则。其核心设计遵循“主规则 + 灰度规则”的叠加模型：主 Ingress 承载稳定版本，Canary Ingress 承载灰度版本，两者通过注解建立关联。

4.1 核心注解清单与功能

4.2 基于权重的流量切分

权重模式是最直观的灰度策略。通过 canary-weight 指定进入灰度版本的流量百分比，剩余流量全部转发至主版本。适用于小流量验证、性能基准对比等场景。

# 主 Ingress（稳定版）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-main
spec:
  ingressClassName: nginx
  rules:
  - host: demo.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-stable
            port:
              number: 80
---
# Canary Ingress（灰度版，承接 10% 流量）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-canary
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "10"
spec:
  ingressClassName: nginx
  rules:
  - host: demo.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-canary-svc
            port:
              number: 80

4.3 基于 Header 的流量切分

Header 模式允许通过 HTTP 请求头精确控制灰度流量，适用于内部测试、QA 验证、A/B 测试等场景。该模式不依赖随机概率，而是由客户端显式声明。

# Canary Ingress（基于 Header 精确匹配）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-canary-header
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "X-Canary"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v2"
spec:
  ingressClassName: nginx
  rules:
  - host: demo.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-canary-svc
            port:
              number: 80

4.4 流量切分决策流程

下图展示了 Ingress-Nginx 在处理请求时，如何根据 Canary 注解依次判断并路由流量：

4.5 多规则组合策略

在实际生产环境中，通常将权重与 Header 组合使用，形成“内部灰度 + 外部小流量”的混合策略：

• 内部测试通道：通过 canary-by-header: X-Canary 为 QA 团队提供固定灰度入口，不受权重影响。
• 渐进式放量：权重从 1% 开始，逐步增加至 5%、10%、20%，配合监控指标决定是否继续放量。
• 紧急回退：通过 canary-by-header-value: never 让特定请求强制走主版本，用于快速绕过灰度问题。