《Kubernetes 分布式系统原理深入解析》11.2 failurePolicy 与 webhook 幂等

webhook 是外部服务,会超时、会挂。准入链对 webhook 故障的策略由 failurePolicy 决定:Ignore 是故障不阻塞(请求继续),Fail 是故障拒绝请求。两者各有一份代价。webhook 还必须幂等——被反复调用不能产生重复效果(如 sidecar 注入只注入一次)。本节解剖 failurePolicy 的权衡与 webhook 幂等的必要性。lab 用 admission/admission.go 验证两种策略与幂等注解。

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 节):

  1. 重试:webhook 超时后 apiserver 可能重试,同一个请求打两次。
  2. 重放:客户端用同一对象反复 apply,每次写都触发 webhook。
  3. 多副本: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:三次调用只注入一次——「重复无害」的幂等注解。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图