容器与云原生 / 系统课时
设计灰度发布入口
设计灰度发布入口
灰度发布的关键不是“把一部分流量切过去”,而是让稳定版本、灰度版本、观测指标和回滚动作形成闭环。本课用 Gateway API 的加权路由设计一条可验证、可逐步放量,并能在异常时快速恢复稳定流量的入口灰度路径。
学习目标
- 使用
HTTPRoute的后端权重在稳定版与灰度版 Service 之间分配入口流量。 - 通过路由状态和数据面采样验证权重已经真正生效。
- 设计逐级放量与回滚条件,并验证当前 Gateway Controller 对零权重后端的处理。
把版本差异放在 Service 后面
入口层应面向两个稳定的 Service,而不是直接绑定某组 Pod。假设 web-stable 指向当前生产版本,web-canary 指向候选版本;两个 Service 提供相同的业务端口和接口契约。这样入口策略只负责“分多少流量”,版本实例的扩缩容仍由 Deployment 和 Service 管理。

Gateway API 的 backendRefs.weight 是相对权重。90:10 表示长期分布应接近 90% 与 10%,并不保证每连续 10 个请求恰好按 9:1 分配;低请求量时波动会更明显。weight: 0 的标准语义是不向该后端转发,请求会按其余正权重后端重新计算比例;如果只剩一个正权重后端,它应获得全部可转发流量。
配置并验证 90:10 加权路由
下面示例假设集群已经存在 web-gateway,以及监听 8080 端口的 web-stable、web-canary 两个 Service。为便于验证,实验应用的 /version 分别返回单行文本 stable 和 canary;生产环境可以用按后端标签聚合的访问日志或指标替代。
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: web
spec:
parentRefs:
- name: web-gateway
hostnames:
- app.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: web-stable
port: 8080
weight: 90
- name: web-canary
port: 8080
weight: 10这份配置把同一匹配规则的请求按相对权重分给两个 Service。保存为 httproute.yaml 后应用并确认对象存在。
kubectl apply -f httproute.yaml
kubectl get httproute web预期输出中应看到路由对象存在;列内容会随实现略有差异。
NAME HOSTNAMES AGE
web ["app.example.com"] <TIME>仅有对象并不代表数据面已经接受配置,还要检查父级状态条件。
kubectl get httproute web -o jsonpath='{range .status.parents[*].conditions[*]}{.type}={.status}{"\n"}{end}'预期结果应至少确认路由已被接受,并且后端引用已经解析。
Accepted=True
ResolvedRefs=True如果 ResolvedRefs=False,先检查 Service 名称、端口以及跨 Namespace 引用授权,不要继续放量。随后从能够访问 Gateway 的位置做请求采样;<GATEWAY_IP> 替换为实际入口地址。
for i in $(seq 1 100); do
result="$(curl -fsS -H 'Host: app.example.com' 'http://<GATEWAY_IP>/version')"
printf '%s\n' "$result"
done | sort | uniq -c预期输出的两项计数之和为 100,分布应大致接近 90:10,但单次样本不要求精确命中。
<VALUE> canary
<VALUE> stable用观测结果控制放量
灰度不应从 10% 直接跳到 100%。更稳妥的节奏是从足以获得有效样本的小比例开始,例如 1% 或 5%,再按 10%、25%、50%、100% 逐级推进。每一级都等待完整观测窗口,并比较稳定版与灰度版的错误率、P95/P99 延迟、超时比例以及关键业务成功率。
若灰度版错误率显著高于稳定版、延迟连续越过门槛,或关键业务成功率下降,应停止放量并执行预先验证过的回滚动作,而不是继续依赖“再观察一会儿”。
验证零权重回滚语义
对于 HTTPRoute 的 Service 后端,加权分流属于 Gateway API 的标准能力,但生产环境仍应验证当前 Gateway Controller 及其具体版本如何实现 weight: 0。CRD 接受 YAML、Accepted=True 都只能证明控制面状态,不能替代数据面验证。
先确定这条 Gateway 实际使用的 Controller。不同实现的版本查询方式不同,因此还应在部署清单、Helm Release 或托管服务信息中记录对应版本,并核对该版本的实现说明。
gateway_class="$(kubectl get gateway web-gateway -o jsonpath='{.spec.gatewayClassName}')"
kubectl get gatewayclass "$gateway_class" -o jsonpath='{.spec.controllerName}{"\n"}'预期输出为当前 GatewayClass 声明的控制器名称。
<CONTROLLER_NAME>在与生产使用相同 Controller 和版本的验证环境中,把稳定版改为 100、灰度版改为 0。
kubectl patch httproute web --type='json' -p='[
{"op":"replace","path":"/spec/rules/0/backendRefs/0/weight","value":100},
{"op":"replace","path":"/spec/rules/0/backendRefs/1/weight","value":0}
]'预期输出:
httproute.gateway.networking.k8s.io/web patched确认对象状态和最终权重都正确。
kubectl get httproute web -o jsonpath='{range .status.parents[*].conditions[*]}{.type}={.status}{"\n"}{end}{range .spec.rules[0].backendRefs[*]}{.name}={.weight}{"\n"}{end}'预期结果应包含以下关键信息;控制器可能同时返回其他条件。
Accepted=True
ResolvedRefs=True
web-stable=100
web-canary=0等待该 Controller 正常的配置传播窗口后,再次采样数据面。
for i in $(seq 1 30); do
result="$(curl -fsS -H 'Host: app.example.com' 'http://<GATEWAY_IP>/version')"
printf '%s\n' "$result"
done | sort | uniq -c预期结果只出现稳定版;若仍出现 canary,说明当前实现、版本或数据面尚未按预期完成零权重处理,不能把 weight: 0 当作已验证的生产回滚手段。
30 stable如果零权重验证失败,应改用当前 Controller 明确支持的切流方式,例如把该规则的 backendRefs 收敛为仅保留 web-stable,并重新检查路由条件与数据面流量。只有“控制器版本已确认、状态正常、灰度请求实际归零”三项都通过,才能把零权重写进入口回滚 Runbook。
设计可执行的回滚条件
真正可操作的灰度方案应在发布前写清触发条件。常见条件包括:灰度版本 5xx 相对稳定版超过约定阈值、P99 延迟连续多个观测窗口超标、关键业务成功率下降,或出现数据兼容性风险。触发后先恢复稳定流量,再保留灰度实例和现场用于排查。
如果新旧版本会同时写数据库、消息队列或外部系统,还必须确认两版协议和数据格式能够并存。入口回滚只能改变后续流量去向,不能自动撤销已经发生的数据副作用。灰度设计的完成标准不是“权重会调”,而是能用指标决定何时放量、何时停止,并且已经用当前 Controller 的真实数据面验证过回滚路径。