《Kubernetes 分布式系统原理深入解析》2.3 Update 与三种 Patch:merge、JSONPatch、Apply

更新一个对象有多种写法:Update 是全量替换、merge patch 是深度合并、JSONPatch 是逐 op 应用、server-side apply 是字段级所有权管理。它们的差异在于『未声明的字段怎么办』:覆盖、保留、还是按属主裁决。本节对比四种写语义并说明各自适用场景。lab 用 api/patch.go 验证 MergePatch 的深度合并与 JSONPatch 的原子语义。

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 的三个层次进步:

  1. 更精确的合并:merge patch 用「键级」合并,SSA 用「字段级」合并,能区分「这字段是 A 设的」。
  2. 属主可移交:删除某属主后其字段可被回收。
  3. 更好处理协调:控制器声明字段,用户声明字段,互不覆盖。

控制器该用哪种?

控制器实践中的选型:

控制器写的内容推荐方式原因
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安全

实战对策:

  1. 数组用 JSONPatch:精确到下标,add /spec/tolerations/2 插入一条,不影响其余。
  2. 数组用 SSA:字段级所有权让多个写者各声明各的元素,K8s 的 list 合并(patchMergeKey)能按唯一键合并,而非整体替换。
  3. 避免用 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 形态。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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