CI/CD / 系统课时
实现灰度发布
实现灰度发布
灰度发布的目标不是让两个版本简单地同时在线,而是把新版本暴露给可控的一小部分流量,并在每次放量前用指标门禁决定继续、暂停或回退。完成本节后,你可以把比例放量、定向流量和快速回退串成一条可执行发布链路。
学习目标
- 能用比例与请求特征把流量稳定地分到旧版和新版。
- 能为 10%→25%→50%→100% 的放量过程设置可观测门禁。
- 能在异常出现时快速把流量切回稳定版本,限制故障影响范围。
先定义放量单位和停止条件
灰度前先把“谁进入新版本”与“什么情况下停止”写清楚。比例灰度适合大多数无状态服务;用户灰度适合让固定人群持续体验同一版本;请求特征灰度则适合内部测试、特定租户或特定渠道。
一个常用节奏是 10%→25%→50%→100%。每一档都要观察能够覆盖典型请求波动的时间窗口,并同时比较新旧版本的错误率、P95/P99 延迟、资源使用和关键业务成功率。任何关键指标越过阈值,都应暂停或回退,而不是继续扩大影响面。
配置比例与定向路由
下面使用 Kubernetes NGINX Ingress 演示。稳定版本正常接收流量,灰度 Ingress 通过 canary-weight 接收约 10%;带有受信任请求头 X-Canary: always 的请求则强制定向到新版本,便于内部验证。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app-stable
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-stable
port:
number: 80
---
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"
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: app-canary
port:
number: 80配置生效后,未携带定向请求头的流量按权重进入灰度版本,携带 X-Canary: always 的请求优先进入灰度 Service。应用配置并确认两个 Ingress 都已创建:
kubectl apply -f gray-ingress.yaml && kubectl get ingress app-stable app-canary预期输出:
ingress.networking.k8s.io/app-stable configured
ingress.networking.k8s.io/app-canary configured
NAME CLASS HOSTS ADDRESS PORTS AGE
app-stable nginx app.example.com <IP> 80 <VALUE>
app-canary nginx app.example.com <IP> 80 <VALUE><IP> 和 <VALUE> 由实际集群状态决定。若要按用户灰度,不应直接信任公网客户端自行设置的“用户标记”请求头;更安全的做法是由认证网关根据用户 ID、租户或白名单生成可信标记,再交给路由层处理。

验证流量确实进入两个版本
只看到 Ingress 对象存在还不够,还要证明请求真正到达不同版本。可以让应用在响应头中暴露版本标识,例如 X-App-Version,然后分别发送普通请求和强制定向请求。
for i in $(seq 1 20); do curl -sS -o /dev/null -D - https://app.example.com/ | grep -i '^X-App-Version:'; done
curl -sS -o /dev/null -D - -H 'X-Canary: always' https://app.example.com/ | grep -i '^X-App-Version:'预期结果:
普通请求中大多数返回 X-App-Version: stable,少量返回 X-App-Version: canary
定向请求返回 X-App-Version: canary20 次请求只适合确认路由行为,不能据此证明统计比例精确等于 10%。真正的比例验证应读取网关或应用监控,在足够请求量下比较两个版本的请求计数。
用指标门禁决定放量还是回退
每次放量都应满足“新版没有明显劣于稳定版”的条件。不要只设置一个全局错误率阈值;更稳妥的方式是同时比较绝对值和新旧版本差异,例如新版 5xx 必须低于既定上限,同时 P99、关键业务成功率和资源使用不能持续恶化。
CI/CD 流程可以把下一档权重作为显式变更:门禁通过后把 canary-weight 从 10 调整为 25、50,最终完成全量;失败则立即把灰度权重归零或撤销灰度路由,并保留失败窗口内的日志、指标和追踪数据。
什么时候应该直接回退
出现数据错误、身份权限异常、持续大量 5xx、不可接受的 P99 抖动或资源快速失控时,应优先回退流量,不要继续扩大样本。对于只影响非关键功能的小问题,可以暂停在当前比例观察,但必须规定观察时限和明确负责人。
灰度发布真正控制的是风险暴露速度。路由配置只解决“分多少流量”,发布系统还要固化“观察什么、观察多久、什么条件继续、什么条件回退”,才能把一次人工操作变成可重复的风险控制能力。