《Kubernetes 分布式系统原理深入解析》1.1 一次 kubectl apply 的完整旅程

一条 kubectl apply 命令在集群里走完整条分布式数据面:客户端生成 object、经认证与准入、apiserver 写 etcd 完成一次线性一致写、发布 watch 事件、控制器订阅后进入调谐循环。本节沿这条链路拆解每个环节的一致性承诺,并说明 apiserver 在整个系统里扮演的『分布式数据面』角色。lab 用 api/store.go 模拟 apiserver 的写入路径与事件发布。

1.1 一次 kubectl apply 的完整旅程

卷二的主角是 K8s 的控制面。卷一回答了「集群状态怎么被一致地存储起来」,答案核心是 etcd + Raft。现在要问的问题是:状态是怎么变成事件流、事件流怎么驱动系统收敛到期望状态。这条链路的起点,就是 apiserver——它把「存储」变成了「数据面」。

本节从一条最普通的命令出发,把 kubectl apply 从客户端到 etcd 再到控制器的整条链路拆开。每经过一个环节,都标注它的一致性承诺。理解这条链路,是理解卷二全部内容(list-watch、乐观并发、控制器、调谐)的观察起点。

apply 不是「写一个文件」

kubectl apply 与 kubectl create 的本质区别,不在「能不能更新已存在的对象」,而在语义:

  • create 是命令式:告诉 apiserver「创建一个对象」,对象已经完整定型,apiserver 不需要理解它。
  • apply 是声明式:告诉 apiserver「我希望集群里有这样一个对象」,apiserver(以及后续的控制器)负责把它变成现实。

声明式的关键机制在客户端:kubectl apply 会记录对象上一次 apply 时的字段值(存在对象的 kubectl.kubernetes.io/last-applied-configuration 注解里),然后计算「当前对象」与「上一次 apply」的差异,把差异以 JSON Patch 形式提交。这样多次 apply 不会互相覆盖未声明的字段——这正是卷二第 2.3 节 Patch 语义的客户端来源。

链路第一段:客户端到 apiserver

一次 apply 的第一个动作是请求的序列化与路由:

  1. 版本与路径:kubectl 读取集群配置,把对象序列化为 JSON,生成请求 PUT /apis/apps/v1/namespaces/default/deployments/nginx。
  2. 认证:请求携带客户端证书或 Bearer token,apiserver 的认证链验证身份,得到 user 与 groups。
  3. 授权:RBAC 检查 user 对 deployments 资源是否有 update 权限。
  4. 准入:经过 mutating webhook(可修改对象)→ 内置校验(schema 校验、字段合法性)→ validating webhook(可拒绝)。这一步在卷二第 11 章展开。
  5. 写入 etcd:对象被序列化、分配 resourceVersion、执行一次 Raft 提交。这一步是整个链路上唯一保证线性一致的环节。

前三步是「过程控制」,第四步是「内容控制」,第五步是「持久化」。kubectl 拿到的响应(200 OK + 带 resourceVersion 的对象)只代表第五步成功了。

链路第二段:apiserver 到 etcd

apiserver 收到写请求后,并不把对象「存进数据库」那么简单。它要做的事对应卷一的完整机制栈:

环节对应卷一机制一致性承诺
分配 resourceVersionmvcc revision单调递增
写入键值etcd Put线性一致(Raft 提交)
构造事件watch 事件与写入同一 revision
返回对象带新 RV已提交即已持久化

关键点:apiserver 自己不是存储。它把对象序列化后写入 etcd 的某个 key(如 /registry/deployments/default/nginx),事件与 resourceVersion 都源自 etcd 的 mvcc。apiserver 是「存储之上的数据面」,它负责把 etcd 的键值世界翻译成 K8s 的 REST 世界。

链路第三段:etcd 发布事件

写入 etcd 不只是「改了一个 key」。etcd 的 mvcc 会为这次写入生成一条记录,任何 watch 该 key(或前缀)的客户端都会收到一条带 revision 的事件。apiserver 自己 watch 着 etcd 的这些 key:

  • apiserver 里的 storage 层对 etcd 维护着 list-watch:写请求走「写路径」,其他 apiserver 副本的变更通过 watch 事件回传。
  • 对下游(controller-manager、scheduler、kubelet),apiserver 再把「etcd 事件」翻译成「K8s 对象事件」,通过 /apis/apps/v1/watch/... 推给所有 informer。

所以一条 apply 会触发两级事件:etcd 级(apiserver 收到)和 apiserver 级(控制器收到)。卷二第 3 章讨论的就是后者。

链路第四段:控制器订阅与调谐

Deployment 对象一写入,controller-manager 里的 informer 立刻感知(毫秒到百毫秒级,取决于 watch 连接与缓存)。接下来:

  1. Deployment 控制器看到新的/更新的 Deployment,读取 spec,对比现状,创建或更新对应的 ReplicaSet。
  2. ReplicaSet 控制器看到新的 RS,对比期望副本与实际副本,创建 Pod。
  3. Scheduler 看到 Pending 的 Pod,做 Filter + Score,写 nodeName。
  4. Kubelet 看到绑定的 Pod,拉镜像、启动容器。

这四段各自都是一轮「读取 → 对比 → 写回」的循环,每一轮写回都再次触发 etcd 事件与 apiserver 事件,形成级联的事件风暴。卷二第 5-10 章专门讨论这级联里的控制回路。

一条链路,四种一致性

把整条链路的一致性承诺列成表,是理解卷二最重要的坐标系:

观察点读到什么滞后原因
kubectl apply 返回对象已写入(线性一致)0Raft 提交
apiserver 直读 etcd最新已提交值0线性一致读
informer 缓存可能旧几毫秒~几秒有界watch 传播 + 缓存
控制器执行的「当前状态」自己缓存里的快照有界同 informer

记住:apply 返回成功 ≠ 控制器已经看到。控制器看到的永远是自己缓存里的版本,而缓存是异步更新的。这是「声明式系统」与「命令式系统」在观察层面最大的区别,也是卷二整卷反复出现的主线。

apply 的客户端侧:差异是怎么算出来的

kubectl apply 与 kubectl replace 的区别,要在客户端代码里找。kubectl apply 的流程可以伪代码化为:

func Apply(obj []byte) {
    lastApplied := obj.GetAnnotation("kubectl.kubernetes.io/last-applied-configuration")
    // 合并策略:只有本次声明覆盖上一次声明;未声明的字段交给服务器端保留。
    patch := threeWayMerge(lastApplied, currentLive, obj)
    // 更新注解:把本次完整配置存回去,供下次 diff 用。
    obj.SetAnnotation("last-applied-configuration", string(obj))
    PATCH(apiServer, patch)
}

关键在 threeWayMerge:三个输入分别是「上一次声明的配置」「服务器上的实时对象」「本次声明的配置」。合并结果只包含「本次与上一次相比发生了变化的字段」,未变化的字段(可能是控制器写入的 status、其他工具写入的字段)不进入 patch。这就是「apply 不覆盖未声明字段」的机制来源——它不是靠运气,而是每次 apply 都精确计算差异。

注意这个设计有一个著名的行为:kubectl apply 用注解记录上次配置,属于「客户端三方合并」(client-side apply)。K8s 1.18 之后推荐的 server-side apply(SSA)把差异计算与字段属主搬进 apiserver(卷二 2.3 节),不再依赖注解,但「声明式差异计算」的精神一致:apply 的本质是「算出我声明了什么变化,只提交这些变化」。

从 apply 到 watch 的一秒:事件风暴的开端

一次 apply 之后,集群里会快速发生一串事件。以「把 Deployment 从 2 个副本扩到 5 个」为例:

时刻事件谁处理
t=0Deployment 更新(replicas 2→5)Deployment 控制器
t+几 ms新建 ReplicaSet(desired=5)RS 控制器
t+几 ms创建 3 个新 Podkubelet/scheduler
t+几百 msPod 调度(nodeName 写入)scheduler
t+几 sPod 就绪(Ready 上报)kubelet/RS 控制器

每一步都产生至少一次 etcd 写入、一次 watch 事件、一次控制器 reconcile。这个「一次 apply 引发一串事件」的过程,就是卷二 5-10 章级联调谐的内容。理解 apply 的旅程,就是理解事件从哪里来:一切事件都起源于一次声明式写入,而写入本身又始于 kubectl apply 这样一条命令。

链路里能卡住的每一环

把故障诊断也挂在链路上,是理解 apply 旅程的实用收尾。请求可能卡在五个环节:

环节典型症状常见原因
认证/授权403 ForbiddenRBAC 缺失、证书过期
准入请求被 webhook 拒绝validating webhook 拦截、mutating webhook 异常
写入 etcd超时/重试etcd 慢盘、leader 抖动、quorum 不足
事件发布控制器没反应watch 断连、informer 缓存落后
调谐对象卡在中间态控制器 panic、workqueue 退避过长

诊断时先问「在哪一环断了」:kubectl apply 报错是前四环;命令成功但没生效是第五环。这条链路对照表在后续章节里会反复引用——每章解决其中一环(第 2 章写路径、第 3 章事件、第 4 章选主、第 5-10 章调谐)。

apply 在对象生命周期里的坐标

把 kubectl apply 放进对象生命周期的完整序列里,才能看清它的位置:

阶段动词语义apply 是否适用
创建create首次声明一个对象是(不存在则创建)
演进apply声明式更新,只提交差异是(本专题主线)
演进replace命令式全量替换否(会覆盖未声明字段)
演进edit交互式命令式修改否
删除delete删除对象否

apply 相比 create 的独特之处:apply 是幂等的。对已存在对象再次 apply 相同配置,产生的 patch 为空,什么也不发生;create 重复执行则 409。这使 apply 成为「声明期望状态」的天然载体——CI/CD 流水线可以反复 apply 同一份清单,而不必关心对象是否已存在。

还有一个容易忽略的边界:apply 一个已被删除的对象会重新创建它。此时 UID 是全新的(卷二 2.1 节:UID 随创建分配、终身不变)。如果你用 kubectl delete 删了 Deployment 又 apply 同样的 YAML,集群里会出现一个新 Deployment——名字相同、UID 不同、从 0 开始收敛。判断「是不是同一个对象」要用 UID,而不是名字。

三个常见误解

  • 「apply 返回成功 = 集群已生效」——错误。返回成功只代表 etcd 已提交;从提交到控制器收敛、再到节点执行,还有一条异步链路。见上面的一致性表。
  • 「kubectl apply 是全量覆盖」——错误。apply 计算的是「上一次 apply 与本次的差异」,未声明的字段(如控制器写进去的 status)不会被覆盖。它比 create/update 更精确。
  • 「apiserver 宕机 = etcd 数据丢」——错误。apiserver 是无状态的,数据全在 etcd;apiserver 挂掉后新副本从 etcd 恢复。但 etcd 挂掉则整个控制面停止写——这是卷二第 1.3 节要讨论的「单点依赖」。

从应用到事件:两级事件的时间线

把 1.1 节的时间线压缩成一次完整的两级传播:

时刻发生一致性承诺
t0kubectl PATCH 提交写成功 = 已提交
t0+δetcd 写 revision 并发布事件线性一致
t0+εapiserver watch 到,翻译成 K8s 事件单调
t0+ζ控制器 informer 收到,key 入队有界滞后
t0+η控制器 reconcile 读取缓存快照

δ/ε/ζ/η 每个都是毫秒级,加起来是控制器看到事件的「年龄」。这条时间线是理解「apply 返回成功 ≠ 控制器已看到」的最直观形式:成功的写只承诺 t0 那一刻,控制器看到的永远是 t0+η。

本节 lab

本节不写算法,lab 验证的是 apiserver 写入路径的最小语义:对象分配 UID/RV、spec 变化递增 Generation、status 更新不递增 Generation:

cd private/labs/k8s-ctrl-lab
go test ./api -run 'TestRVMonotonic|TestGenerationStatus' -v

两个用例覆盖:TestRVMonotonic(Create→Update 后 UID 不变、RV 递增、Generation 递增)、TestGenerationStatus(status 更新递增 RV 但不递增 Generation)。这正是本节「写成功 = 已提交」背后的对象模型基础。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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