2.3 Update 与三种 Patch:merge、JSONPatch、Apply
「更新一个对象」在 K8s 里有四种写法,语义完全不同。本节的核心问题是:更新时,对象里那些你没提到的字段会怎样? 四种写法给出四个答案:被覆盖、被保留、逐条指定、按属主裁决。
四种写语义一表对比
| 方式 | 未声明字段的处理 | 语义 | 典型使用方 |
|---|---|---|---|
| Update(PUT) | 全部被覆盖 | 全量替换 | kubectl replace、控制器 update |
| Merge Patch | 递归合并保留 | 深度合并 | kubectl patch、控制器 patch |
| JSONPatch | 逐 op 精确指定 | 操作序列 | 高级客户端 |
| Server-side Apply | 按属主合并 | 字段所有权 | kubectl apply、GitOps |
Update:全量替换
PUT 的语义是「把我给的对象存进去」,对象里没写的字段(如默认值、控制器写进的 status)会被清空或按默认值重建。所以:
- 客户端必须提供完整对象(通常先 GET 再改再 PUT)。
- 必须携带 RV(乐观锁,见 2.2 节)。
- 危险场景:GET 与 PUT 之间对象被控制器改了 status,PUT 会把 status 冲掉——除非客户端重新 GET 合并。
实际中 kubectl apply 不用 Update,因为它不希望「未声明的字段被覆盖」。控制器也多用 Patch 而非 Update 来只改自己负责的字段。
Merge Patch(RFC 7386)
merge patch 的语义:深度合并。
{"spec": {"replicas": 3}} // patch
+ {"spec": {"replicas": 1, "labels": {"app": "x"}}} // 原对象
= {"spec": {"replicas": 3, "labels": {"app": "x"}}} // 结果
规则:
- 对象(map)字段递归合并:patch 里的键覆盖原值,未提到的键保留。
- 数组字段整体替换(不能按索引合并)。
null表示删除该键。
merge patch 是 kubectl patch 的默认行为。它的优点是不需要先 GET 完整对象,只提交差异;缺点是数组替换语义可能误伤(比如要往数组加一个元素,必须带上整个数组)。
JSONPatch(RFC 6902)
JSONPatch 是一系列操作:add / remove / replace / test,每条指定路径:
[
{"op": "test", "path": "/spec/replicas", "value": 1},
{"op": "replace", "path": "/spec/replicas", "value": 3},
{"op": "add", "path": "/spec/labels/tier", "value": "web"}
]
特点:
- 原子性:整个数组要么全部成功要么全部失败。op 中的
test就是「前提条件」,test 失败则整批不执行(CAS 的 REST 形态)。 - 精确性:可以操作任意嵌套路径,包括数组下标。
- 对客户端要求高:必须自己构造操作序列,出错率高于 merge。
适用场景:需要精细控制(如只改某个嵌套字段)、或实现 CAS(用 test 断言当前值)。代价是心智负担。
Server-side Apply(SSA)
SSA 是 kubectl apply 的现代实现,它解决的问题是 merge patch 与多写者冲突:
- 每个字段记录属主(manager)与字段路径。
- 多个写者(用户、控制器、HPA)可以各自声明字段,不冲突则各改各的。
- 冲突(两个属主都要同一个字段且值不同)→ 409,须显式夺回。
kubectl.kubernetes.io/last-applied-configuration注解被替代为内置的字段所有权跟踪。
SSA 的三个层次进步:
- 更精确的合并:merge patch 用「键级」合并,SSA 用「字段级」合并,能区分「这字段是 A 设的」。
- 属主可移交:删除某属主后其字段可被回收。
- 更好处理协调:控制器声明字段,用户声明字段,互不覆盖。
控制器该用哪种?
控制器实践中的选型:
| 控制器写的内容 | 推荐方式 | 原因 |
|---|---|---|
| status(observedGeneration 等) | Patch status 子资源 | 不碰 spec,减少冲突 |
| spec 里自己负责的字段 | SSA 或 merge patch | 只改自己声明范围 |
| 全量重同步 | Update | 需要覆盖全部字段时 |
绝大多数控制器遵循「只写自己该写的字段」原则:用 Patch 而非 Update,用子资源而非主对象。这从设计上把 409 冲突率压到最低(呼应 2.2 节)。
merge patch 的数组陷阱与实战对策
merge patch 最大的语义弱点在数组。看一个典型场景:要给 spec.tolerations 加一条容忍规则:
{
"spec": {"tolerations": [{"key": "gpu", "operator": "Exists"}]}
}
如果原对象已经有 2 条 tolerations,这个 patch 会把 3 条整体替换成 1 条——因为你没带上原来的那 2 条。merge patch 对数组是「替换」而非「合并」,这是 RFC 7386 的定义,不是 bug。
| 场景 | merge patch 的行为 | 是否安全 |
|---|---|---|
| 改对象(map)里的标量 | 键级覆盖 | 安全 |
| 改嵌套 map | 递归合并 | 安全 |
| 改数组 | 整体替换 | 危险(须带全量) |
| 删一个键 | 写 null | 安全 |
实战对策:
- 数组用 JSONPatch:精确到下标,
add /spec/tolerations/2插入一条,不影响其余。 - 数组用 SSA:字段级所有权让多个写者各声明各的元素,K8s 的 list 合并(
patchMergeKey)能按唯一键合并,而非整体替换。 - 避免用 merge patch 改数组:只用于 map 字段的递归合并。
理解这个陷阱后,再看三种 Patch 的选型就清楚了:merge 适合 map、JSONPatch 适合数组与精细操作、SSA 适合多写者共管。「merge patch 把数组冲了」也是控制器工程里最常见的 bug 之一。
SSA 字段所有权的一次实例
用一个例子看 SSA 怎么解决「多个写者各管各的字段」:
第一次 apply(用户,manager=alice):
spec.replicas=3 → 属主 alice
spec.template.image=nginx → 属主 alice
控制器写 status(manager=kube-deployment-controller):
status.observedGeneration=1 → 属主 controller
status.readyReplicas=3 → 属主 controller
第二次 apply(用户,manager=bob):
spec.replicas=5 → 属主 alice(bob 声明同字段)
spec.template.image=nginx → 属主 alice(值相同,无冲突)
关键行为:
- bob 声明
replicas=5时,apiserver 检查该字段当前属主 alice 的旧值是 3,bob 声明的值不同 → 409,除非 bob 用--force-conflicts显式夺回所有权。 - bob 声明
image=nginx(与 alice 相同)→ 不冲突,正常合并。 - 控制器写的
status字段属主是 controller,用户 apply 不碰 status → 各写各的,互不 409。
这就是 SSA 相对 merge patch 的根本进步:冲突检测从「键级」细化到「字段级 + 属主级」。没有 SSA 时,用户与控制器并发写同一个对象会频繁 409;有 SSA 后,只要字段不重叠就相安无事。
三个常见误解
- 「patch 比 update 快所以用它」——不是性能问题,是语义问题:update 覆盖未声明字段,patch 保留。选型应基于「我想不想保留未声明的字段」。
- 「JSONPatch 一定比 merge 精确所以更好」——JSONPatch 精确但笨重,merge 简洁但数组语义弱;SSA 才是兼顾精确与简洁的现代方案。
- 「SSA 就是 merge patch 的别名」——错误。SSA 引入了字段所有权与冲突检测,merge patch 没有;两者底层实现完全不同。
本节 lab
本节验证 merge patch 与 JSONPatch 的核心语义:
cd private/labs/k8s-ctrl-lab
go test ./api -run 'TestMergePatch|TestJSONPatch|TestJSONPatchTestFail' -v
TestMergePatch:嵌套字段递归合并、标量覆盖、未声明键保留。TestJSONPatch:test→add→replace→remove 依序应用,路径精确。TestJSONPatchTestFail:test 前提失败整批原子失败,且不修改原对象——CAS 的 REST 形态。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。