云原生DevOps运维微服务【免费下载链接】kubevelaThe Modern Application Platform.项目地址https://gitcode.com/gh_mirrors/ku/kubevela点击查看免费下载KubeVela 内置的json-merge-patchtrait 允许你以 Application 声明的形式对组件渲染出的工作负载Workload执行符合 [RFC 7396] 语义的 JSON Merge Patch实现字段的新增add、替换replace与删除delete而无需为每种改动编写新的组件定义。本文以官方示例文档 json-merge-patch.eg.md 为骨架结合 trait 定义源码、CUE 渲染测试与端到端e2e测试完整讲解该 trait 的声明写法、底层原理与验证方式读完即可在自己的 Application 中安全使用它完成 Deployment、Pod 标签、副本数、容器镜像等任意字段的原地修补。一、trait 是什么一次看懂定义与声明在 KubeVela 中trait 是对组件输出Output进行修饰的能力单元。json-merge-patch是系统内置 trait 之一其定义位于 vela-templates/definitions/internal/trait/json-merge-patch.cue完整内容如下json-merge-patch: { type: trait annotations: {} labels: { ui-hidden: true } description: Patch the output following Json Merge Patch strategy, following RFC 7396. attributes: { podDisruptive: true appliesToWorkloads: [*] } } template: { parameter: {...} // patchStrategyjsonMergePatch patch: parameter }从中可以读出三个关键事实适用面极广appliesToWorkloads: [*]表示它可挂载到任意类型的工作负载上Deployment、StatefulSet、DaemonSet 乃至自定义 CRD 工作负载可能引起 Pod 重建podDisruptive: true声明该 trait 会修改 Pod 模板因此变更可能触发滚动更新这与pkg/controller中对 disruptive trait 的处理逻辑相呼应模板极其轻量parameter: {...}允许接收任意结构patch: parameter将用户传入的参数整体作为补丁内容// patchStrategyjsonMergePatch则告诉渲染引擎采用 JSON Merge Patch 策略进行合并。该 CUE 定义会在安装时被渲染为正式的TraitDefinition资源产物见 charts/vela-core/templates/defwithtemplate/json-merge-patch.yaml其spec.schematic.cue.template与上述 CUE 模板完全一致命名空间与appliesToWorkloads: [*]、podDisruptive: true均被保留。二、使用姿势一份完整的 Application 示例官方示例文档 json-merge-patch.eg.md 给出了一份可直接落地的 Application。同一个示例也以可执行形式保存在 docs/examples/traits/json-merge-patch/example.yaml被 e2e 测试直接引用apiVersion: core.oam.dev/v1beta1 kind: Application metadata: name: busybox spec: components: - name: busybox type: webservice properties: image: busybox cmd: [sleep, 86400] labels: pod-label-key: pod-label-value to-delete-label-key: to-delete-label-value traits: # the json merge patch can be used to add, replace and delete fields # the following part will # 1. add deploy-label-key to deployment labels # 2. set deployment replicas to 3 # 3. set pod-label-key to pod-label-modified-value in pod labels # 4. delete to-delete-label-key in pod labels # 5. reset containers for pod - type: json-merge-patch properties: metadata: labels: deploy-label-key: deploy-label-added-value spec: replicas: 3 template: metadata: labels: pod-label-key: pod-label-modified-value to-delete-label-key: null spec: containers: - name: busybox-new image: busybox:1.34 command: [sleep, 864000]示例组件是webservice类型的busybox其底层渲染产物是 KubernetesDeployment。trait 的properties直接对应 Deployment 对象中需要修改的字段路径——metadata.labels对应 Deployment 顶层标签spec.replicas对应副本数spec.template.metadata.labels对应 Pod 模板标签spec.template.spec.containers对应 Pod 容器列表。这种补丁结构即目标对象结构的写法正是 JSON Merge Patch 的最大优点无需学习 JSON Patch 的op/path/value操作符语法。对照注释逐条解读五个修补动作原文档注释明确列出了本次补丁将完成的 5 个操作逐条展开如下#目标字段补丁写法语义最终效果1Deployment 顶层标签metadata.labels.deploy-label-key: deploy-label-added-valueadd新增deploy-label-keydeploy-label-added-value2Deployment 副本数spec.replicas: 3replace副本数变为 33Pod 标签spec.template.metadata.labels.pod-label-key: pod-label-modified-valuereplacepod-label-key从pod-label-value改为pod-label-modified-value4Pod 标签spec.template.metadata.labels.to-delete-label-key: nulldelete删除to-delete-label-key值为null表示删除5Pod 容器spec.template.spec.containers: [...]replace容器列表整体重置为仅含busybox-new镜像busybox:1.34命令sleep 864000三、运行与端到端验证如何部署该示例是标准core.oam.dev/v1beta1Application可使用vela up直接部署示例文件位于 docs/examples/traits/json-merge-patch/example.yamlvela up -f docs/examples/traits/json-merge-patch/example.yaml部署完成后KubeVela 控制器会渲染 webservice 组件得到 Deployment再按 JSON Merge Patch 语义合并上述补丁并下发到集群。e2e 测试给出的预期结果仓库中的端到端测试 test/e2e-test/trait_test.go 完整验证了这份示例的最终形态可以当作权威的验收清单deploy.Labels[deploy-label-key]等于deploy-label-added-value新增标签生效deploy.Spec.Replicas等于3副本数被替换Pod 模板标签deploy.Spec.Template.ObjectMeta.Labels[pod-label-key]等于pod-label-modified-value标签被替换原标签to-delete-label-key不再存在null删除语义生效容器列表长度变为1且唯一容器名为busybox-new、镜像为busybox:1.34、命令为[sleep, 864000]容器整体被重置。这意味着你不需要人工核对示例中的 5 个动作全部有测试兜底可以作为自己编写类似补丁时的对照基准。四、底层原理patchStrategy 与 CUE 渲染// patchStrategyjsonMergePatch注解在 CUE 模板中patch字段前的行内注解// patchStrategyjsonMergePatch是渲染引擎识别补丁策略的关键。KubeVela 的 CUE 渲染单元测试 pkg/cue/definition/template_test.go 给出了直接证据parameter: {...} // patchStrategyjsonMergePatch patch: parameter配合参数spec: replicas: 5 template: spec: null # 关键点null 用于删除整个字段渲染后的 Deployment 中replicas被替换为5而spec.template.spec即容器定义被整体删除——这正是 RFC 7396 中值为null即删除该成员语义在字段级而非成员级的体现。该测试用例名为patch trait with json merge patch与jsonPatch基于operations数组的 RFC 6902 风格和retainKeys、replace等策略并列说明策略由注解驱动引擎按注解选择合并算法。从 SDK 生成角度看 trait 的构建从源码结构看defkit包为定义生成 SDK 提供了对应的构建设施pkg/definition/defkit/template.go 中Template结构体持有patchStrategy字段注释明确列出常用策略retainKeys,jsonMergePatch,jsonPatchpkg/definition/defkit/patch.go 中的Passthrough()方法专门生成patch: parameter形式的 CUE注释写明 Used for json-patch and json-merge-patch traits where the parameter IS the patch——即这类 trait 的参数本身就是补丁不需要任何额外的拼接逻辑对应的测试 pkg/definition/defkit/trait_test.go 断言生成的 CUE 包含// patchStrategyjsonMergePatch注解SDK 测试数据见 pkg/definition/gen_sdk/testdata/json-merge-patch.cue。运行时下发三路合并与 JSON Merge Patch在资源下发阶段pkg/utils/apply/patch.go 中可以看到控制器对自定义资源使用CreateThreeWayJSONMergePatch计算上次应用、当前实际、期望状态三者间的补丁与 trait 渲染阶段的 merge 语义形成呼应——整个链路都围绕 RFC 7396 的合并规则展开。五、语义边界与注意事项基于定义与测试使用json-merge-patchtrait 时有以下几点需要牢记null是删除符在补丁对象中任何成员的值写成null都会被解释为删除该成员。因此不要试图用null表达清空为无值以外的任何含义如果你需要的是将某个字段置为 JSON 意义上的空值如空对象{}、空数组[]、字符串请显式写出对应字面量。字段级整体删除同样适用把整个子对象设为null如template.spec: null会删除该子对象及其全部子成员如渲染测试所示。数组默认整体替换JSON Merge Patch 对数组不做逐元素合并——补丁中的数组会整体替换原数组。示例第 5 个动作正是利用这一特性重置containers列表若你需要按 key 合并数组如按容器名合并应改用内置的kustomize-strategy-merge或kustomize-json-patch等 trait或自行编写带// patchKeyname注解的 CUE 模板。对象深层合并除删除null与数组整体替换之外补丁中出现的对象成员会与目标对象递归合并因此你可以只修改某个深层字段而保留其余字段不变。Pod 破坏性该 trait 声明了podDisruptive: true修改 Pod 模板字段标签、容器等会触发工作负载的滚动更新生产环境请评估变更窗口仅修改 Deployment 顶层字段如replicas则不会重建 Pod。适用范围appliesToWorkloads: [*]意味着任何工作负载都可挂载但对非标准结构无spec.template的 CRD 工作负载需要先确认目标对象的实际字段路径避免补丁定位落空。六、总结json-merge-patchtrait 是 KubeVela 中零模板定制、纯声明式修补的代表性能力定义文件 vela-templates/definitions/internal/trait/json-merge-patch.cue 只有十余行核心就一句// patchStrategyjsonMergePatchpatch: parameter使用方只需在 Application 中按目标资源结构写出想增、改、删的字段即可。官方示例 json-merge-patch.eg.md 覆盖了 add、replace、delete 三类全部操作并且有 e2e 测试 与 渲染单元测试 双重背书。需要快速对既有工作负载做字段级微调、又不想新增维护一份 CUE trait 定义时它就是最直接的选择。赞分享云原生DevOps运维微服务【免费下载链接】kubevelaThe Modern Application Platform.项目地址https://gitcode.com/gh_mirrors/ku/kubevela点击查看免费下载相关推荐KubeEdge 中的 JSON Patch 完全指南基于 evanphx/json-patch 掌握 RFC 6902 与 RFC 7396KubeEdge 中的 JSON Patch 完全指南基于 evanphx/json patch 掌握 RFC 6902 与 RFC 7396 本文以 Kub云原生边缘计算物联网容器编排边缘网关KubeSphere 依赖解析用 evanphx/json-patch 玩转 RFC 6902 JSON Patch 与 RFC 7396 Merge PatchKubeSphere 依赖解析用 evanphx/json patch 玩转 RFC 6902 JSON Patch 与 RFC 7396 Merge Pat后端云原生容器编排微服务深入解析 evanphx/json-patch在 vcluster 中驾驭 RFC 6902 JSON Patch 与 RFC 7396 Merge Patch深入解析 evanphx/json patch在 vcluster 中驾驭 RFC 6902 JSON Patch 与 RFC 7396 Merge Patc云原生集群管理虚拟化多集群上一篇Stable Video Infinity移动端部署在手机上运行AI视频生成的方法下一篇基于JavaScript动态模板引擎的Obsidian自动化系统构建高效知识管理工作流创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考