Meshery Relationship 定义编写实战从 kind/type/subType 组合到 schema 校验与注册【免费下载链接】mesheryMeshery, the cloud native manager项目地址: https://gitcode.com/GitHub_Trending/me/meshery本篇文章是围绕 Meshery 仓库内 .agents/skills/gen-relationship/SKILL.md 编写的技术指南完整讲解如何创建与精炼 schema 驱动的 Meshery relationship 定义models/**/relationships/*.json。读完本文你将掌握 relationship 的版本体系与来源真相、kind/type/subType组合的选择依据、selectors与mutatorRef/mutatedRef补丁机制、从零创建与精炼既有定义的完整流程以及用mesheryctl与评估 API 验证注册的实操方法。Relationship 是什么语义连接与纯设计标注在 Meshery 中Relationship关系描述的是同一模型或不同模型之间组件component的关联方式并区分两类本质不同的关系语义semantic关系组件之间真实相互影响例如PersistentVolumeClaim挂载进Pod、Service选择Deployment的 Pod、Role通过RoleBinding赋权给ServiceAccount。这类关系会被 Meshery 的策略引擎评估并可能在设计上产生实际的补丁patch动作。非语义 / 纯设计annotation关系仅存在于设计者的心智模型或画布标注中例如用Shape到Shape的注释连线说明设计意图Meshery不会对其求值也不会执行任何补丁。该技能Skill用于两个场景创建全新定义与精炼既有定义。当你在 Meshery 开发中需要添加一个 relationship、修复某个 relationship JSON、判断这个关系应该是什么 kind/type/subType时即可按本文流程操作。Source of Truth以 schema 为准不凭空造字段关系定义的权威来源是meshery/schemas 仓库写作关系 JSON 时不得发明字段、枚举或路径形状。以下是官方 schema 文档与仓库内实体的对应关系内容位置Relationship 对象定义schemas/constructs/v1beta3/relationship/relationship.yamlSelectors、patch、mutator/mutated 定义schemas/constructs/v1beta3/relationship/api.yml起始模板文档schemas/constructs/v1beta3/relationship/templates/relationship_template.json仓库内的语料库in-tree corpusmodels/model/model-version/definition-version/relationships/官方概念文档Concepts: Relationships贡献关系文档Contributing to RelationshipsschemaVersion 的现状v1beta2 与 v1beta3v1beta3是写作目标版本但仓库内 in-tree 的模型文件绝大多数仍是v1beta2少量为v1alpha3。例如 kubernetes 模型的 in-tree 关系文件 models/kubernetes/v1.37.0/v1.0.0/relationships/sibling-tagsets.json 就声明了schemaVersion: relationships.meshery.io/v1beta2。版本之间的形状是兼容的Meshery Server 在将已注册的关系定义桥接给 Go 策略引擎时会执行版本转换具体实现见 server/models/pattern/utils/relationship_version_bridge.go。该文件提供了RelationshipV1alpha3ToV1beta2与RelationshipV1beta2ToV1alpha3双向桥接函数把v1alpha3/v1beta2的形状转换为策略引擎所需的v1beta2结构浅拷贝共享 map 与指针字段仅对跨版本类型不同的字段显式复制。但有一个关键限制注册网关registration gate目前只接受v1beta2/v1alpha3文档直到 server 所用 meshkit 升级后才接受v1beta3。因此需要在当前服务器上成功注册的定义包括 in-tree 播种、mesheryctl model import应声明v1beta2待注册网关接受v1beta3后再切换到v1beta3精炼既有文件时保留其schemaVersion除非你刻意在做迁移。kind是 schema 枚举hierarchical | edge | sibling。type与subType是开放字符串但只有下表列出的组合是 Meshery 当前会可视化并求值的。新增一个subType需要具备两个前提Kanvas 中有对应的可视化范式需要先在画板中提报设计以及有能理解该 subType 的求值策略Rego policy。v1beta3 要求的对象必填字段为schemaVersion、version、model、kind、type、subType、id。实践中任何可用的定义都会额外携带status、metadata含description、selectors以及一个空的evaluationQuery——请从 registry 模板或 .agents/skills/gen-relationship/examples/ 中的示例起步而不是只写最小必填字段。kind/type/subType 组合速查表kindtypesubType三者共同决定可视化范式与求值策略。复制已有的组合不要自行混搭只打开与你所选组合对应的示例文件其余示例对你的场景没有增量信息。kindtypesubType含义典型示例示例文件edgenon-bindingreference逻辑名称/id 指针无流量、挂载或 RBACDeployment → ConfigMapexamples/edge-non-binding-reference.jsonedgenon-bindingnetwork文档化的 L3/L4/L7 选择关系无实际配置的附加动作Service → Deploymentexamples/edge-non-binding-network.jsonedgenon-bindingfirewall允许/拒绝对端之间流量的策略NetworkPolicy → Podexamples/edge-non-binding-firewall.jsonedgenon-bindingpermission提及某身份或角色但不绑定它IAM Policy → Roleexamples/edge-non-binding-permission.jsonedgenon-bindingalias具名的替身非嵌套属主关系Secret → Secretexamples/edge-non-binding-alias.jsonedgenon-bindingannotation仅设计者可见的连线metadata.isAnnotation: true无补丁Shape → Shapeexamples/edge-non-binding-annotation.jsonedgenon-bindinginventory少见。对等索引/列表非父子包含Cluster → Databaseexamples/edge-non-binding-inventory.jsonedgebindingpermission分配身份Role/RoleBinding/ServiceAccountRole → ServiceAccount经 RoleBindingexamples/edge-binding-permission.jsonedgebindingmount存储或设备被附加PVC → Podexamples/edge-binding-mount.jsonedgebindingnetwork少见。连接会配置/重写网络身份Listener → Domainexamples/edge-binding-network.jsonhierarchicalparentinventory父级划定/包含子级父身份被补丁到子级上*→ Namespaceexamples/hierarchical-parent-inventory.jsonhierarchicalparentalias子级是父级内部的嵌套对象Container → Podexamples/hierarchical-parent-alias.jsonhierarchicalparentwallet子级配置被持有/补丁进父级WASMFilter → EnvoyFilterexamples/hierarchical-parent-wallet.jsonhierarchicalsiblingmatchlabelsin-tree 的 tagsets 编码共享标签无补丁*↔*examples/hierarchical-sibling-matchlabels.jsonsiblingmatchlabelstagsetsschema 原生 tagsetskind枚举值为sibling*↔*examples/sibling-matchlabels.json注意badge只作为可视化范式出现在贡献文档里仓库内没有 in-tree 编码不要发明subType: badge。Sibling 编码的坑schema 的kind枚举是hierarchical | edge | sibling而 Kubernetes in-tree 文件使用kind: hierarchical、type: sibling、subType: matchlabels参见 models/kubernetes/v1.37.0/v1.0.0/relationships/sibling-tagsets.json。因此精炼 kubernetes 文件或复制其模式保持hierarchical/sibling/matchlabels三件套新建模型、向 schema kind 标准化使用kind: sibling如 examples/sibling-matchlabels.json切勿在同一模型内混用两种编码。Binding 与 non-binding 的区别binding形成关系即执行赋值、挂载或授权有生命周期副作用。挂载mount与 RBAC 赋权属于此类。non-binding链接是真实存在的选择器、名称引用、策略匹配但本身不配置这个附加关系。经验法则绝大多数 Service → 工作负载workload的边是non-binding/network挂载和 RBAC 赋值才是binding。Semantic 与 annotation 的区别当metadata.isAnnotation: true或组件是 shape/annotation 组件时表示 Meshery不得求值或打补丁。Edge-annotation 是常规编码方式annotation 关系上不要添加mutatorRef/mutatedRef。层次关系的 from/to 方向from永远是子级childto永远是父级parent。这一点是固定的不要记反。subType数据流inventory父级修改子级Namespace 名称 → 子级metadata.namespacealias子级修改父级Container spec → Podspec.containers._wallet子级修改父级filter 配置 → EnvoyFilter 补丁历史上一版 gen-relationship 示例把 Namespace 放进from是错误的写法在 examples/hierarchical-parent-inventory.json 中正确结构是from为kind: *的任意子组件其mutatedRef指向[[configuration, metadata, namespace]]to为kind: Namespace其mutatorRef为[[displayName]]——命名空间的名字作为 mutator被写入每个子级的metadata.namespace作为 mutated 槽位。动作ActionsmutatorRef 与 mutatedRefmutatorRef与mutatedRef在api.yml中被定义为字符串路径段组成的嵌套数组string[][]。两侧的序列长度必须一致mutatorRef的第i个路径段序列补丁到mutatedRef的第i个路径段序列上mutatorRef: [[config, url], [config, name]], mutatedRef: [[configPatch, value], [name]]即[config, url]被拷贝到[configPatch, value][config, name]被拷贝到[name]。字段角色mutatorRef来源Source。要读取的值的 JSON 路径。mutatedRef目标Sink。要被补丁的字段的路径段。patchStrategy应用方式。schema 枚举merge、strategic、add、remove、replace、copy、move、test。in-tree 语料库与求值引擎只使用replace无特殊需求时默认replace。路径相对于Meshery 存储的组件文档configuration、displayName、component.kind等字段不是原始 Kubernetes YAML 的根。以 examples/edge-binding-mount.json 为例PVC 侧的mutatorRef为[[configuration, metadata, name]]声明名Pod 侧的mutatedRef为[[configuration, spec, volumes, _, persistentVolumeClaim, claimName]]卷声明名槽位。路径书写规则来自贡献文档至今仍然成立_只能标记路径中第一个数组位置后续数组必须写显式索引0、1……。mutatedRef目前不支持把数组本身作为被补丁的值。每条 mutator 路径都必须配对一条 mutated 路径不允许留下不成对的一侧。每一条路径都要对照models/model/.../components/Kind.json或 schemas 构造中的组件 schema 验证不要凭猜测写路径。部分 selector 使用嵌套的match块match.from/match.to/match.refs替代或补充patch。tagsets 在 labels 上使用match.refspermission/mount 常用kind: self的match配合在 match item 上的mutatorRef/mutatedRef。精炼时直接复制 kubernetes 中同组合已使用的结构。当关系只做匹配tagsets、annotation时完全省略patch。Selectors 语义selectors复数是一个 selector-set 项的数组每一项包含allow与可选的deny两者各自含from和to一个 selector-set 项 一条独立的匹配规则项与项之间是OR关系。同一项内部每一个from条目与每一个to条目都会产生关联——这是笛卡尔积不是 1:N 关系。deny负责扣除匹配。allow与deny不得描述同一对组件。缺失的 selector 字段视为*通配。kind、model、version的值区分大小写。selector 项上的model.name: *让该关系可以跨模型而关系层级的model仍标识所属模型。旧文档中会出现错误名称单数selector、core.meshery.io/v1alpha2。请使用selectors与relationships.meshery.io/v1beta3。evaluationQuery已废弃置空即可evaluationQuery已被 schema 标为废弃deprecated。统一置为——仓库内约 3860 个 in-tree 定义全部如此。求值引擎通过固定的策略包data.relationship_evaluation_policy进入并依据kind/type/subType分发从不读取该字段。若遗留工具强制要求填写规则名历史默认值是{kind}_{subType}_relationship小写源自 meshery/schemas 的GetDefaultEvaluationQuery()——注意其中没有{type}段且 Rego 规则名只允许字母、数字与下划线因此non-binding这类带连字符的 type 永远不可能出现在规则名中。创建新定义的 8 步流程确定两个或多个组件 kind 及所属模型确认它们在models/下真实存在。判断它们是否互相影响语义关系还是只影响图面annotation。从上表挑选kind/type/subType。若没有合适的组合停下来提出可视化方案不要自创组合。设置from/to层次关系子级在from父级在to。若需要值流动先阅读组件 JSON schema再加配对的mutatorRef/mutatedRef若只做匹配用match.refs或省略 patch。设置evaluationQuery: 、status: enabled以及注册网关能接受的schemaVersion当前为v1beta2meshkit#1096 落地后才用v1beta3。每个关系写一个 JSON 文件或一小簇内聚的文件放到models/model/model-version/def-version/relationships/下。文件命名约定{kind}-{type}-{subType}-后缀.json与仓库 in-tree 的命名如edge-non-binding-network-duixv.json、edge-binding-mount-cnndn.json保持一致。与 examples/ 中对应的示例文件、以及 kubernetes 中同组合的 in-tree 邻居文件逐一对比。精炼既有定义的 7 步流程打开 in-tree 文件记录schemaVersion、kind、type、subType。不要升级这三个字段除非原分类本身是错的。保持from/to方向。已经是子级在from的层次文件必须维持原状。优先放宽或收窄allow/deny的 kinds而不是克隆一个近似重复的关系——除非补丁路径确实不同。向from或to添加组件 kind 时复制一个既有 selector 项修改kind与补丁路径并重新验证路径。不要颠倒mutatorRef与mutatedRef——来源 vs 目标是最常见的 bug。冲突的重叠定义取并集互补的重叠定义也取并集。不要添加一条用不同 kind 重述同一对组件的关系。保留全零 UUID00000000-0000-0000-0000-000000000000原样不动——registry 会分配真实 id。常见错误清单schemaVersion写成v1beta1或core.meshery.io/v1alpha2——错误新写应使用relationships.meshery.io/v1beta3。层次 inventory 关系中把父级放进from。type: network却不带subType或把inventory当成kind用。写成selector而非selectors。用扁平路径spec.containers[0].name而非嵌套数组[[configuration,spec,containers,_,name]]。mutator/mutated 序列不成对。不读组件 schema 就瞎猜 JSON 路径。不检查必填字段就盲目把 v1beta2 样板抄进 v1beta3 文件或反向。在同一模型内混用kind: sibling与 in-tree 的kind: hierarchical, type: sibling。验证与注册机器检查不要只靠肉眼每个定义在交付前都要走机器校验流程JSON 可解析性检查python3 -m json.tool file——先确认能解析。打包mesheryctl model init model --version ver会脚手架出model/ver/{model.json,components/,relationships/}结构把你的文件放进relationships/并复制 in-tree 的model.json然后执行mesheryctl model build model/ver --path .生成 OCI tar——文档格式非法时该命令会失败。注册对着运行中的 server 执行mesheryctl model import -f model-ver.tar。亲自验证注册结果——永远不要只信 import 的摘要输出。查询/api/meshmodels/models/model/relationships或mesheryctl relationship view model确认你的定义真的出现了。有一个已知坑在 server 已认识的模型中导入关系若相关 schema 修复尚未合入关系会被静默孤立model_id为全零 UUID而摘要却报告成功。用求值证明行为向/api/meshmodels/relationships/evaluatePOST 一个设计design其组件配置已满足该关系名称/路径匹配确认响应中出现你的定义且status: approved。关于严格文档校验器meshkitschema.Validate它目前会因为与你的写作无关的语料约定问题拒绝 corpus 常规文件因此在当下model buildimport 求值才是真正有效的关卡。输出约定完成定义后需要返回完整的关系 JSON或对既有文件的 unified diff并说明你选择的kind/type/subType及理由、mutator 与 mutated 路径的名称、以及所引用的 schema 文件。若组合是全新的表中没有停下来明确说明而不是硬造。仓库内可继续深挖的路径技能全文与全部示例.agents/skills/gen-relationship/SKILL.md、.agents/skills/gen-relationship/examples/in-tree 关系语料库kubernetes 模型models/kubernetes/v1.37.0/v1.0.0/relationships/关系定义的版本桥接实现server/models/pattern/utils/relationship_version_bridge.go组件 JSON schema验证路径用models/model/.../components/Kind.json如 models/kubernetes/v1.37.0/v1.0.0/components关系概念文档docs/content/en/concepts/logical/relationships、docs/content/en/project/contributing/contributing-relationships【免费下载链接】mesheryMeshery, the cloud native manager项目地址: https://gitcode.com/GitHub_Trending/me/meshery创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考