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 的第一个动作是请求的序列化与路由:
- 版本与路径:kubectl 读取集群配置,把对象序列化为 JSON,生成请求
PUT /apis/apps/v1/namespaces/default/deployments/nginx。 - 认证:请求携带客户端证书或 Bearer token,apiserver 的认证链验证身份,得到
user与groups。 - 授权:RBAC 检查
user对deployments资源是否有update权限。 - 准入:经过 mutating webhook(可修改对象)→ 内置校验(schema 校验、字段合法性)→ validating webhook(可拒绝)。这一步在卷二第 11 章展开。
- 写入 etcd:对象被序列化、分配 resourceVersion、执行一次 Raft 提交。这一步是整个链路上唯一保证线性一致的环节。
前三步是「过程控制」,第四步是「内容控制」,第五步是「持久化」。kubectl 拿到的响应(200 OK + 带 resourceVersion 的对象)只代表第五步成功了。
链路第二段:apiserver 到 etcd
apiserver 收到写请求后,并不把对象「存进数据库」那么简单。它要做的事对应卷一的完整机制栈:
| 环节 | 对应卷一机制 | 一致性承诺 |
|---|---|---|
| 分配 resourceVersion | mvcc 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 连接与缓存)。接下来:
- Deployment 控制器看到新的/更新的 Deployment,读取 spec,对比现状,创建或更新对应的 ReplicaSet。
- ReplicaSet 控制器看到新的 RS,对比期望副本与实际副本,创建 Pod。
- Scheduler 看到 Pending 的 Pod,做 Filter + Score,写
nodeName。 - Kubelet 看到绑定的 Pod,拉镜像、启动容器。
这四段各自都是一轮「读取 → 对比 → 写回」的循环,每一轮写回都再次触发 etcd 事件与 apiserver 事件,形成级联的事件风暴。卷二第 5-10 章专门讨论这级联里的控制回路。
一条链路,四种一致性
把整条链路的一致性承诺列成表,是理解卷二最重要的坐标系:
| 观察点 | 读到什么 | 滞后 | 原因 |
|---|---|---|---|
| kubectl apply 返回 | 对象已写入(线性一致) | 0 | Raft 提交 |
| 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=0 | Deployment 更新(replicas 2→5) | Deployment 控制器 |
| t+几 ms | 新建 ReplicaSet(desired=5) | RS 控制器 |
| t+几 ms | 创建 3 个新 Pod | kubelet/scheduler |
| t+几百 ms | Pod 调度(nodeName 写入) | scheduler |
| t+几 s | Pod 就绪(Ready 上报) | kubelet/RS 控制器 |
每一步都产生至少一次 etcd 写入、一次 watch 事件、一次控制器 reconcile。这个「一次 apply 引发一串事件」的过程,就是卷二 5-10 章级联调谐的内容。理解 apply 的旅程,就是理解事件从哪里来:一切事件都起源于一次声明式写入,而写入本身又始于 kubectl apply 这样一条命令。
链路里能卡住的每一环
把故障诊断也挂在链路上,是理解 apply 旅程的实用收尾。请求可能卡在五个环节:
| 环节 | 典型症状 | 常见原因 |
|---|---|---|
| 认证/授权 | 403 Forbidden | RBAC 缺失、证书过期 |
| 准入 | 请求被 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 节的时间线压缩成一次完整的两级传播:
| 时刻 | 发生 | 一致性承诺 |
|---|---|---|
| t0 | kubectl 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)。这正是本节「写成功 = 已提交」背后的对象模型基础。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。