11.2 failurePolicy 与 webhook 幂等
webhook 是外部 HTTP 服务——它会超时、会挂、会被网络故障隔开。准入链必须决定「webhook 故障时请求怎么办」。这个决定由 failurePolicy 表达。而 webhook 自身还有一个硬要求:幂等。本节解剖这两件事。
webhook 故障是常态,不是意外
webhook 是 apiserver 通过 HTTPS 调用的外部服务。故障来源与控制器调用 apiserver 的故障来源对称(6.3 节):
| 故障 | 表现 |
|---|---|
| webhook 服务超时 | 请求在 timeout 内无响应 |
| webhook 崩溃/重启 | 连接失败、5xx |
| 网络分区 | 请求根本到不了 webhook |
| 证书过期 | TLS 握手失败 |
apiserver 不能假设 webhook 永远可用——它是分布式系统里的一个外部依赖,会以各种方式失败。准入链对「webhook 不可用」必须有明确的、可配置的行为。
failurePolicy 的两端:Ignore 与 Fail
failurePolicy 决定 webhook 出错时请求的命运:
| 策略 | webhook 故障时的行为 | 代价 |
|---|---|---|
Ignore | 跳过该 webhook,请求继续 | 校验/加工可能缺失 |
Fail | 拒绝请求 | 一个故障 webhook 阻塞所有写 |
lab 的 Hook.Faulty 与 FailOnError 模拟这两种策略:
case Validating:
if h.Faulty {
if h.FailOnError {
return Result{Allowed: false, Reason: ...} // Fail:拒绝
}
continue // Ignore:跳过
}
...
两个测试对应两种策略:
TestFailurePolicyIgnore:faulty 的 mutating hook 在 Ignore 下被跳过,请求照常放行。TestFailurePolicyFail:faulty 的 validating hook 在 Fail 下拒绝请求。
两种策略的权衡:要正确还是要可用
选择 failurePolicy 是「正确性 vs 可用性」的经典权衡:
| 策略 | 优先保证 | 风险 |
|---|---|---|
| Ignore | 请求可用性 | 该 webhook 的校验/加工失效 |
| Fail | 校验/加工完整性 | webhook 挂 = 写路径全堵 |
真实世界的选法:
- Validate 类用 Fail:安全策略(如「禁止特权容器」)的 webhook 挂了还让请求通过,等于安全洞。宁可暂时堵住写路径,也不让危险请求过去。
- Mutate 类默认 Ignore:默认值、sidecar 注入这种「锦上添花」的加工,挂了不该阻塞业务——请求不带 sidecar 也能用,只是少了增强。
- 可降级的校验用 Ignore:像「建议型限制」——不强制,webhook 挂了也可以放行。
选型判据:这个 webhook 的行为是「安全必需」还是「增强可选」。安全必需 → Fail;增强可选 → Ignore。K8s 的惯例正是如此:validating 默认 Fail、mutating 默认 Ignore——这与「mutating 加的东西是增强」的直觉一致。
webhook 幂等:为什么必须「重复无害」
webhook 会被反复调用,原因与 reconcile 被重复执行相同(6.2 节):
- 重试:webhook 超时后 apiserver 可能重试,同一个请求打两次。
- 重放:客户端用同一对象反复 apply,每次写都触发 webhook。
- 多副本:apiserver 多副本(第 14 章)各自调用 webhook,同一对象可能被多个 apiserver 处理。
如果 webhook 不幂等,重复调用会产生重复效果。最典型的例子:sidecar 注入器每次调用都加一个 sidecar 容器——重复调用会让 Pod 带 3 个 sidecar。
lab 的 TestWebhookIdempotent 演示幂等的做法:
Mutate: func(obj map[string]any) map[string]any {
annotations := obj["annotations"].(map[string]any)
if annotations["injected"] != "true" {
annotations["injected"] = "true" // 只在没有时注入
added++
}
return obj
}
核心:先检查「是否已处理过」,已处理则不再重复。lab 用「注入标记注解」实现:对象已带 injected=true 就不再注入。三次调用只注入一次(added==1)。
幂等的实现模式
webhook 幂等常见的三种模式:
| 模式 | 做法 | 适用 |
|---|---|---|
| 标记注解 | 处理过就写个注解,再调用检查注解 | sidecar 注入、label 添加 |
| 检查-再改 | 先看对象里有没有,没有才加 | 默认值、环境变量 |
| 幂等写入 | 写的值本身是「已收敛」的(重复写结果相同) | 状态字段 |
关键认识(6.2 节同源):幂等不是「只执行一次」,而是「执行多次结果相同」。webhook 不能假设「自己只被调一次」——它必须对「被调多次」免疫。这是 webhook 作为「写路径上的外部服务」的生存前提:apiserver 无法保证只调一次,webhook 就必须自己扛住多次。
failurePolicy 与幂等的组合
把两件事合起来看:
webhook 被调 → 成功 → 结果幂等(重复无害)
→ 失败 → failurePolicy 决定请求命运(Ignore/Fail)
- 幂等管「成功后重复无害」:防的是「重试/重放产生重复效果」。
- failurePolicy 管「失败时怎么办」:防的是「故障阻塞或绕过校验」。
两者缺一不可:不幂等,重复调用出错;没策略,故障时行为未定义。一个生产级 webhook 必须同时满足「成功幂等」与「失败有策略」。
webhook 的 timeout 与重试:故障的两个层次
webhook 调用还有两个参数,与 failurePolicy 配合:timeout 与 重试。
| 参数 | 含义 | 默认 |
|---|---|---|
timeoutSeconds | 单次调用等待上限 | 30s(可调小) |
| 重试 | apiserver 对失败调用的重试 | 有上限 |
故障的两个层次:
超时/网络错误(调用层失败)→ 重试?→ 仍失败 → failurePolicy 决定
业务拒绝(webhook 返回 deny)→ 不是故障,是策略结果 → 直接拒绝
关键区分:webhook 返回「拒绝」(业务校验不过)不是故障——它是策略执行的结果,不受 failurePolicy 管辖(本来就要拒绝)。failurePolicy 只管「webhook 没回应」(超时/崩溃/网络)这类调用层故障。
lab 的 Faulty 标记模拟的正是「调用层故障」(超时),FailOnError 对应 failurePolicy。分清「webhook 拒绝了」与「webhook 挂了」,是准入排障的第一步——前者看策略,后者看服务健康。
幂等与 mutating 的确定性:同一输入同一输出
webhook 幂等还有一个容易被忽略的维度:确定性。同一个对象进来,webhook 应该产生相同的修改。
| 要求 | 含义 | 违反的后果 |
|---|---|---|
| 幂等 | 重复调用结果相同 | 重复注入、重复加工 |
| 确定性 | 同一输入产生同一输出 | 同一对象两次写入结果不同 |
不幂等 = 重复调用出错;不确定 = 单次调用结果随机。webhook 的实现不能依赖「随机值」「当前时间戳」(除非写进对象的字段)——否则同一个对象,第一次 apply 加一个随机值,第二次 apply 又换成另一个,永远无法收敛。
lab 的 TestWebhookIdempotent 验证幂等;确定性的检查更简单:同一个对象调两次 webhook,结果应该逐字节一致。这回到 5.2 节的收敛——webhook 不确定,控制器的收敛就被破坏(它看到的 spec 每次都不一样)。
三个常见误解
- 「failurePolicy=Fail 最安全,全用 Fail」——错误。Fail 会让一个挂掉的 webhook 阻塞整个写路径——可用性灾难。选型看「必需还是增强」。
- 「webhook 只被调用一次」——错误。重试、重放、多副本都会导致多次调用,必须幂等。
- 「Ignore 就是忽略错误」——不准确。Ignore 是「跳过该 webhook」,但请求继续走链上其余 webhook——不是整体跳过准入。
本节 lab
本节验证 failurePolicy 两种策略与 webhook 幂等:
cd private/labs/k8s-ctrl-lab
go test ./admission -run 'TestFailurePolicyIgnore|TestFailurePolicyFail|TestWebhookIdempotent' -v
TestFailurePolicyIgnore:Ignore 下 faulty hook 被跳过、请求放行——「故障不阻塞」。TestFailurePolicyFail:Fail 下 faulty hook 拒绝请求——「故障即拒绝」。TestWebhookIdempotent:三次调用只注入一次——「重复无害」的幂等注解。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。