Meshery Catalog 部署模式解析:基于 hello-app 理解 Kubernetes 组件、关系与 mesheryctl 导入部署

原创2026-09-21 14:13:031,973 阅读
文章标签:云原生容器编排服务网格多集群微服务可观测性运维GitOps配置管理性能测试CLI后端前端DevOps

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):

  1. 请求发布:作者提交发布请求,附带描述与注意事项(对应 frontmatter 的 patternInfo、patternCaveats);
  2. 管理员审核:Workspace 管理员审阅,可批准、拒绝或要求修改;
  3. 批准与校验:批准后校验设计数据准确性,然后发布并自动版本化(publishedVersion: 0.0.1 即由此而来);
  4. 持续管理:作者/Workspace 所有者保留编辑、删除、取消发布的权限;
  5. 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 模式。

登录后查看全文
meshery