Meshery Catalog 部署模式解析:基于 hello-app 理解 Kubernetes 组件、关系与 mesheryctl 导入部署
Meshery Catalog 部署模式解析:基于 hello-app 理解 Kubernetes 组件、关系与 mesheryctl 导入部署
本文以 Meshery Catalog 中发布的 hello-app 部署模式(Deployment Design,ID:ec6a41d2-d2bd-4089-b1c2-72a5c76b9313)为标本,拆解一个 Catalog 条目的完整组成:从前置元数据(frontmatter)到结构化设计文件 design.yml 中每个 Kubernetes 组件与组件间关系的含义,再到如何用 mesheryctl 将该模式导入并部署到自己的集群。读完本文,你将能够读懂任意一个 Meshery Design 的内部结构,并掌握 Catalog 模式从发布、审核到本地落地的完整路径。
一、Catalog 条目是什么:hello-app 的档案
hello-app 是 Meshery Catalog 中一个典型的 deployment 类型条目。在 docs/catalog/deployment/ec6a41d2-d2bd-4089-b1c2-72a5c76b9313.md 中,它以 YAML frontmatter 形式记录了该模式的全部档案信息。Meshery Catalog 本身是一个类似云市场(cloud marketplace)的发布与发现平台,用于浏览、共享和部署云原生基础设施配置,其数据模型遵循 Meshery 的 Catalog Schema(见 docs/content/en/concepts/architecture/catalog/index.md)。
该条目的核心字段如下:
| 字段 | 值 | 含义 |
|---|---|---|
layout |
item |
使用 item 布局渲染该 Catalog 页面 |
name |
hello-app |
模式名称 |
publishedVersion |
0.0.1 |
已发布的版本号 |
type |
deployment |
Catalog 分类类型(还有 security、resiliency、observability 等) |
compatibility |
kubernetes、nginx-ingress |
兼容的运行时/网格 |
patternId |
ec6a41d2-... |
模式的全局唯一 ID,与 design.yml 中 id 一致 |
patternInfo |
hello app 应用,使用 nginx 与 kubernetes 组件 | 模式用途描述 |
patternCaveats |
No caveats | 使用注意事项(本模式无) |
createdAt |
2024-03-01T03:37:50Z |
创建时间 |
permalink |
catalog/deployment/hello-app-ec6a41d2-...html |
页面稳定链接 |
downloadLink |
ec6a41d2-.../design.yml |
设计文件下载路径 |
注意 compatibility 字段声明了 nginx-ingress,而实际 design.yml 中使用的是标准 networking.k8s.io/v1 Ingress 组件,这说明该模式在集群中依赖 Ingress Controller(如 nginx-ingress)来承载流量入口,是部署该模式时需要考虑的前提条件。
与该条目配套的发布元数据记录在 docs/data/catalog/ec6a41d2-d2bd-4089-b1c2-72a5c76b9313/0.0.1/artifacthub-pkg.yml 中,它遵循 Artifact Hub 的包描述规范,包含 version、displayName、description、license: Apache-2.0 以及安装提示 install: mesheryctl design import -f 等信息。这印证了 Meshery Designs 支持在 Artifact Hub 类仓库中列出与分发的能力(见 docs/content/en/concepts/logical/designs.md)。
二、design.yml:一个 Deployment 设计模式的内部结构
模式的真正实体是结构化设计文件 docs/data/catalog/ec6a41d2-d2bd-4089-b1c2-72a5c76b9313/0.0.1/design.yml。它是符合 designs.meshery.io/v1beta1 Schema 的 JSON 文档,由 Components(组件) 与 Relationships(关系) 两大部分构成——这正是 Meshery 中 "Design 是可部署单元" 的核心体现:Design 由组件与关系组成,用以声明期望的基础设施状态(见 docs/content/en/concepts/logical/designs.md)。
hello-app 模式实际定义了 4 个 Kubernetes 业务组件和 2 个画布辅助组件:
| # | kind | displayName | namespace | 关键配置 |
|---|---|---|---|---|
| 1 | Namespace |
default |
— | 系统默认命名空间 |
| 2 | Namespace |
helloweb |
— | 应用专属命名空间 |
| 3 | Ingress |
helloweb |
default |
强制 HTTPS、默认后端指向 helloweb-backend:443 |
| 4 | Service |
helloweb-backend |
default |
NodePort 类型,443→8443,selector app=hello, tier=web |
| 5 | GenericNode |
Generic Node | — | meshery-core 注解节点(画布注释) |
| 6 | NodeGroupInventoryWallet |
Node Group Inventory Wallet | helloweb |
组件分组容器 |
2.1 Ingress:HTTPS 入口
helloweb Ingress(networking.k8s.io/v1)是该模式的流量入口,配置要点:
"configuration": {
"metadata": {
"annotations": { "kubernetes.io/ingress.allow-http": "false" },
"labels": { "app": "hello" },
"namespace": "default"
},
"spec": {
"defaultBackend": {
"service": { "name": "helloweb-backend", "port": { "number": 443 } }
},
"tls": [ { "secretName": "yourdomain-tls" } ]
}
}
- 注解
kubernetes.io/ingress.allow-http: "false"表明该入口只接受 HTTPS,禁止 HTTP 明文流量。 defaultBackend将未匹配任何规则的请求路由到helloweb-backend服务的 443 端口。tls.secretName: yourdomain-tls指向 TLS 证书 Secret。这是一个占位符,实际部署前必须替换为你自己域名对应的 Secret 名称,这是该模式落地时的一个必改项。
2.2 Service:后端服务暴露
helloweb-backend Service(v1)承担后端负载均衡与暴露:
"configuration": {
"metadata": {
"annotations": {
"service.alpha.kubernetes.io/app-protocols": "{\"helloweb-tls\":\"HTTPS\"}"
},
"labels": { "app": "hello" },
"namespace": "default"
},
"spec": {
"ports": [
{ "name": "helloweb-tls", "port": 443, "protocol": "TCP", "targetPort": 8443 }
],
"selector": { "app": "hello", "tier": "web" },
"type": "NodePort"
}
}
- 端口命名
helloweb-tls,监听 443 并转发到 Pod 的 8443,协议为 TCP。 - 注解
service.alpha.kubernetes.io/app-protocols声明该端口承载的是 HTTPS 应用协议(alpha 特性,属历史兼容注解)。 selector为app=hello, tier=web,即只有同时带这两个标签的 Pod 才会被纳入后端。type: NodePort将服务暴露到集群每个节点的固定端口上,供集群外访问。
值得留意的是:该 Service 的 selector 期望的是 app=hello, tier=web 标签的 Pod,而整个 design.yml 中并未包含 Deployment/Pod 组件。从源码结构看,这是一个面向存量工作负载的部署模式——假设你的 hello 应用(nginx 容器)已以相应标签运行在集群中,本模式只负责补齐 Namespace、Service 与 Ingress 这三层"暴露面",这也与条目描述"hello app 应用,使用 nginx 与 kubernetes 组件"相吻合。
2.3 两个辅助组件
GenericNode(core.meshery.io/v1alpha1):来自meshery-core模型的注解型组件,仅用于画布上的视觉占位(样式标注visibility: hidden、z-index: 9),不参与真实资源下发。NodeGroupInventoryWallet(core.meshery.io/v1alpha1):组件分组容器,其configuration.metadata.namespace为helloweb,在画布上把helloweb命名空间下的资源归组展示。
每个业务组件还携带完整的 capabilities 列表(如 Performance Test、Workload Configuration、Labels and Annotations Configuration、Relationships、Json Schema、Styling 等),这些能力描述决定了组件在 Meshery UI 中可执行的操作与可配置项,例如 Service/Ingress 上均带 perf-test 操作能力,说明可直接对这类工作负载发起性能测试。
三、Relationships:组件之间的血缘关系
design.yml 的另一半是 relationships 数组,hello-app 中共声明了 7 条关系,分两类:
3.1 matchlabels 兄弟关系(sibling)
4 条 type: sibling、subType: matchlabels、kind: hierarchical 的关系,分别在 Ingress↔Service 与 GenericNode↔NodeGroupInventoryWallet 之间建立按标签匹配的兄弟关联,其 selectors[].allow 中 match.refs 指向 configuration.metadata.labels,即通过比对两者标签来判定是否同组。这类关系让画布能将 Ingress 与后端 Service 视觉上与逻辑上关联起来,也驱动依赖图与资源归属的可视化。
3.2 inventory 父子关系(parent)
3 条 type: parent、subType: inventory 的关系,实现父组件向子组件注入配置:
NodeGroupInventoryWallet → Namespace helloweb:通过patch.mutatedRef指向configuration.metadata.namespace,把 Wallet 的命名空间注入到归属资源中;Ingress helloweb → Namespace default:将 Ingress 的metadata.namespace修正/约束为default;Service helloweb-backend → Namespace default:同理约束 Service 所在命名空间。
这正是 Meshery 关系机制中"层级化清单关系"(hierarchical inventory relationship)的典型用法:父组件(Namespace 或分组容器)的配置会被 patch 到子组件上,确保所有子组件归属正确的命名空间。Meshery 在部署时会按此关系解析每个组件应落入哪个 Namespace(详见 docs/content/en/concepts/logical/relationships/index.md 与 docs/content/en/concepts/architecture/deployment-engine/index.md 中的 Deployment Engine 解析逻辑)。
四、从 Catalog 到集群:导入与部署该模式
4.1 用 mesheryctl 导入 design
官方推荐的导入方式是 mesheryctl design import,这在 artifacthub-pkg.yml 的 install 字段中直接给出:mesheryctl design import -f。完整命令为:
# 从本地文件导入(该文件即 downloadLink 指向的 design.yml)
mesheryctl design import -f docs/data/catalog/ec6a41d2-d2bd-4089-b1c2-72a5c76b9313/0.0.1/design.yml
# 指定源格式导入(manifest / compose / helm)
mesheryctl design import -f [file-path] -s [manifest | compose | helm]
mesheryctl design 子命令族还支持对导入后的 design 进行全生命周期管理(见 docs/content/en/concepts/architecture/catalog/index.md):
# 应用(部署)design
mesheryctl design apply --file [design 文件路径 | 文件 URL]
# 查看/列出/删除 design
mesheryctl design view [design 名称 | ID]
mesheryctl design list
mesheryctl design delete --file [design 文件路径]
前置条件:本机安装 Meshery CLI(mesheryctl)并配置连接到你自己的 Meshery 实例,且该实例已接入目标 Kubernetes 集群。部署前还应确认集群中已就绪 nginx-ingress 等 Ingress Controller,并准备好 TLS Secret(替换 yourdomain-tls)。
4.2 在 Meshery UI 中操作
在 Meshery 界面的 Designs 页面中,可以通过"Import Design"导入该文件,导入后你会看到 helloweb Ingress、helloweb-backend Service 与两个 Namespace 组成的画布图,组件间的 sibling/parent 连线即来自上文所述 relationships。随后可对其进行验证(Validation)、Dry-Run 试运行(确保不会产生意外变更)后再实际部署,这些能力在 docs/content/en/concepts/logical/designs.md 中有明确说明。
五、模式如何进入 Catalog:发布与审核工作流
hello-app 能出现在 Catalog 中,背后是一套明确的发布流程(详见 docs/content/en/concepts/architecture/catalog/index.md):
- 请求发布:作者提交发布请求,附带描述与注意事项(对应 frontmatter 的
patternInfo、patternCaveats); - 管理员审核:Workspace 管理员审阅,可批准、拒绝或要求修改;
- 批准与校验:批准后校验设计数据准确性,然后发布并自动版本化(
publishedVersion: 0.0.1即由此而来); - 持续管理:作者/Workspace 所有者保留编辑、删除、取消发布的权限;
- GitHub 工作流集成:批准后由 GitHub 工作流自动发布到 Meshery Catalog。
在 Meshery UI 中,作者只需在 Designs 页编辑设计、补齐技术与描述信息、点击 "Publish to Catalog" 即可进入上述队列。
六、小结
hello-app 虽然是一个小型示例模式,却完整覆盖了 Meshery Design 体系的核心要素:Catalog 条目的元数据规范、designs.meshery.io/v1beta1 下的组件(Components)与关系(Relationships)建模、matchlabels 兄弟关系与 inventory 父子关系的实际写法,以及 mesheryctl design 从导入到部署的命令路径。以此模式为模板,你可以继续阅读 docs/content/en/concepts/logical/components.md 理解组件 Schema,或对照 docs/content/en/concepts/logical/models/index.md 弄清组件来源模型,进而创作并发布属于自己的 Catalog 模式。