《Kubernetes 分布式系统原理深入解析》11.1 准入链:写请求的必经关卡

写请求进入 apiserver 后、落盘 etcd 前,要经过准入链(Admission Chain):Mutating webhook 先改对象(加默认值、注入 sidecar),Validating webhook 后校验(拒绝非法请求)。任一 validating 拒绝则整体拒绝,apiserver 不会执行后续步骤。本节解剖准入链的位置、顺序与拒绝语义。lab 用 admission/admission.go 验证 mutating 先于 validating、拒绝即整体拒绝。

11.1 准入链:写请求的必经关卡

前 10 章讲了「控制器怎么读、怎么写」。本节回到写请求本身:一个写请求进入 apiserver 后、真正落盘 etcd 前,还要经过一道「准入链」。它决定这个请求「能不能进、以什么形态进」。本节解剖准入链的位置、顺序与拒绝语义。

准入在 REST 流程中的位置

一个写请求(Create/Update/Delete)在 apiserver 内的完整旅程:

请求 → 鉴权(你是谁)→ 准入(能不能做、改成什么样)→ 存储(落盘 etcd)→ watch 通知
阶段回答的问题
鉴权这个用户有没有权限
准入这个请求的内容允不允许、要不要改
存储把它写到 etcd
watch通知 informer

准入在鉴权之后、存储之前。它的职责:在对象进入持久层之前,做「最后的把关与加工」。这个位置很关键——任何想「拦下请求」或「改写对象」的策略,都放在这一层。

两种 webhook:先改后验

准入链由两种 hook 组成,顺序固定:

hook职责能否改对象
MutatingAdmissionWebhook改(加默认值、注入 sidecar)能
ValidatingAdmissionWebhook验(校验合法性)不能

Mutating 先执行,Validating 后执行。为什么顺序必须这样:Validating 要校验的是「最终要落盘的对象」——如果 mutating 还没加默认值,validating 校验的是一个「不完整对象」,会误判。先改完、再校验最终形态。

lab 的 Chain.Admit 忠实实现这个顺序:

func (c *Chain) Admit(obj map[string]any) Result {
    cur := obj
    for _, h := range c.Hooks {
        switch h.Kind {
        case Mutating:
            cur = h.Mutate(cur)   // 先改
        case Validating:
            if err := h.Validate(cur); err != nil {
                return Result{Allowed: false, Reason: err.Error(), Object: cur}
            }
        }
    }
    return Result{Allowed: true, Object: cur}
}

测试 TestMutatingThenValidating 验证的正是这条语义:一个「加 finalizer」的 mutating hook 先执行,后一个「要求 finalizer 存在」的 validating hook 看到的是改后对象——validating 必须观察 mutating 的结果。

任一拒绝,整体拒绝

准入链的拒绝语义:任一 validating hook 拒绝,整个请求被拒,后续 hook 与存储都不执行。

情形结果
全部 hook 通过Allowed,进入存储
任一 validating 拒绝整体拒绝(deny),不落盘

lab 的 TestValidatingReject:validating hook 校验 replicas != 0,请求带 replicas: 0 被拒——哪怕链上只有这一个 hook,也足以拦下请求。

拒绝的分布式意义:准入是「写路径上唯一的全量校验点」。控制器自己写对象(第 7 章 RS 建 Pod)也经过它——所以准入策略一次配置,保护所有写者。它是对「所有客户端(用户 + 控制器)」的统一守门,这正是它位于「写路径必经处」的原因。

为什么准入存在:校验与加工的集中化

没有准入链,每个控制器、每个客户端都要自己做校验与默认值——散落、易漏、不一致。准入链把它们集中到一处:

  1. 集中校验:Pod 必须有某某 label、资源必须有 finalizer——一次配置,处处生效。
  2. 集中加工:所有 Pod 都注入 sidecar、都加默认值——写路径统一处理。
  3. 统一审计:拦下的请求有统一记录(audit log)。

准入链是「写路径的策略层」:鉴权管「谁能写」,准入管「写什么、怎么写」。前者是安全,后者是治理。

准入与控制器:一条写路径,两类写者

第 7 章说过 RS 控制器创建 Pod 也走 apiserver。结合本节:

  • 用户 kubectl apply 一个 Deployment → 经过准入链。
  • RS 控制器 创建 Pod → 同样经过准入链。

两类写者走同一条路径、受同一套准入策略约束。这对控制器有实际影响:控制器创建的 Pod 也可能被准入拒绝(比如缺某个强制 label)——控制器收到拒绝错误,重试也无效(请求内容没变)。所以控制器作者要知道:准入是写路径上「可能会拒绝你」的一环,对象模板必须满足准入策略。

子资源写:status/scale 也走准入吗

写请求不止整体 PUT/PATCH。K8s 还有子资源写(status、scale),它们也走准入——但有差别:

写路径经过的准入
主资源写(spec)全部 mutating + validating
status 写只有部分(如「不允许改 status 的某些字段」的策略)

status 写也经过准入链,但通常策略不同:主资源写要过「校验 spec 合法性」的 webhook,status 写主要受「字段保护」策略约束。控制器写 status(第 7 章)同样会被准入链看到——一个「禁止改某字段」的 validating hook 也会拦下控制器的 status 写。

子资源准入口径的意义:它让「spec 写」与「status 写」可以被分别治理——比如只校验用户的声明、不过度校验控制器的汇报。准入链不是「所有写都一视同仁」,而是「按写路径分层施治」。

准入链的延迟与故障面

准入链是写路径上的一段外部调用(webhook 是 HTTP 服务),它给写请求带来两样成本:

成本来源缓解
延迟每个写请求要调用 N 个 webhook超时限制、并行化(validating 可并行)
故障面webhook 挂了影响写路径failurePolicy(11.2 节)、多副本

延迟的叠加:一个写请求要穿过 webhook-1 → webhook-2 → ... → 存储,每个 webhook 一次网络往返。webhook 越多,写路径越慢。所以生产上避免「为做而做」的 webhook——每个 webhook 都要有明确的策略价值。

故障面的传导:webhook 是外部依赖,它的故障按 failurePolicy 决定影响范围(Ignore 局部、Fail 全局)。准入链的可用性上限,取决于链上「Fail 策略」的 webhook 的可用性——一个 Fail 的 webhook 挂了,整个写路径堵住(11.2 节的权衡)。

准入与审计:写路径的可观测性

准入链不止把关,它还是写路径上的审计点。被准入处理的请求会留下记录:

审计维度内容
谁被拒了被准入拒绝的请求、拒绝原因、哪个 hook 拒的
谁被改了mutating hook 改了什么字段(before/after)
谁通过了通过准入的请求继续进入存储

「为什么这个写请求被拒」的第一手答案在准入层:kubectl describe 里看到的拒绝原因、kubectl get events 里的事件,很多都来自准入链的报错。排障写请求时,第一步不是翻 apiserver 日志,而是看准入链有没有拦——拦的原因通常直接写在拒绝消息里。

准入与审计的关系:准入决定「能不能进」,审计记录「发生了什么」。两者是写路径上「把关 + 留痕」的组合——把关防错,留痕可查。生产集群里「我的写请求被神秘拒绝了」,十有八九是准入链里某个 hook 写的拒绝消息。

准入链的配置对象:两个 CRD

webhook 不是「写代码注册」的,而是通过两个配置对象声明:

配置对象声明什么
MutatingWebhookConfigurationmutating webhook 列表(改对象的)
ValidatingWebhookConfigurationvalidating webhook 列表(验对象的)

每个配置对象里列一个或多个 webhook:名称、地址、规则、failurePolicy、timeout。apiserver 加载这些对象,构建准入链。

配置对象的两个意义:

  1. 热注册:创建/更新配置对象 = 注册/调整 webhook,不用重启 apiserver。
  2. 审计可见:集群里「配了哪些准入」可查(kubectl get mutatingwebhookconfigurations)。

准入链的扩展是「声明式」的——和 13 章 CRD 一样,用对象表达配置。这解释了为什么第 11 章放在「扩展」语境:准入链是 K8s 可声明的策略层,写请求的把关也能声明式管理。

三个常见误解

  • 「准入在鉴权之前」——错误。顺序是鉴权 → 准入 → 存储;准入假设你已通过鉴权。
  • 「mutating 和 validating 可以并行」——错误。mutating 必须全部先执行完,validating 才能看到最终对象;乱序会误判。
  • 「webhook 拒绝只影响用户请求」——错误。控制器创建的对象同样经过准入链,被拒会阻塞控制器收敛。

本节 lab

本节验证准入链的「先改后验」与「任一拒绝整体拒绝」:

cd private/labs/k8s-ctrl-lab
go test ./admission -run 'TestMutatingThenValidating|TestValidatingReject' -v
  • TestMutatingThenValidating:mutating 加 finalizer → validating 看到改后对象放行——「先改后验」的顺序。
  • TestValidatingReject:validating 校验 replicas 拒绝 0——「任一拒绝,整体拒绝」。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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