企业官网建设流程全解析

• 云原生
• DevOps
• 运维
• 微服务

KubeVela 的 Addon（插件）机制允许把一组关联的 OAM 定义、Kubernetes 资源与应用骨架打包成可一键安装、可升级、可依赖的交付单元。本文以仓库内置的示例插件pkg/addon/testdata/example-legacy及其 readme.md 为骨架，逐文件拆解经典（legacy）插件的目录规范、元数据字段、参数暴露方式与组件渲染规则，并结合pkg/addon的源码揭示底层渲染链路，帮助读者掌握编写或迁移一个合规 KubeVela 插件所需的完整知识。

一、example-legacy：一个基于 FluxCD 的经典插件样例

example-legacy是一个用于说明插件目录规范的测试样例，其定位是"基于 FluxCD 的示例插件"（见 readme.md）。它演示的是一套经典的（legacy）插件打包方式：目录内只包含template.yaml、metadata.yaml、definitions/与resources/这几类文件，由 Addon 安装器把其中的定义与资源渲染进一个 KubeVela Application，再通过该 Application 的工作流完成安装。

该样例在仓库中的完整文件清单如下：

pkg/addon/testdata/example-legacy/ ├── Chart.yaml # Helm chart 元信息（addon 以 helm library chart 形式打包） ├── metadata.yaml # 插件元数据 ├── template.yaml # 应用骨架（Application） ├── readme.md # 插件说明文档 └── definitions/ ├── helm.yaml # ComponentDefinition（X-Definition） └── dummy.txt # 非 yaml/cue 文件，会被读取逻辑忽略

值得注意的是，样例目录中并没有独立的resources/目录与parameter.cue，但 readme 仍然完整描述了它们在标准插件中的角色——这两类文件属于可选能力，缺省时插件依然可以安装。

二、目录结构总览：每个文件的职责

readme 对插件目录结构做了如下划分（readme.md）：

这套文件规范在源码中被定义为一组Pattern，见 pkg/addon/addon.go：合法的插件文件必须至少匹配README.md、metadata.yaml、template.yaml、resources/parameter.cue、resources/、definitions/、schemas/、views/、godef/、template.cue、parameter.cue、NOTES.cue、readme.md等模式之一，其余文件在扫描阶段会被直接忽略。这也解释了definitions/dummy.txt存在的原因——它用于验证"非 yaml/cue 后缀文件不参与渲染"这一边界行为。

三、template.yaml：插件应用骨架与安装工作流

样例的 template.yaml 定义了一个非常典型的基础 Application：

apiVersion: core.oam.dev/v1beta1 kind: Application metadata: name: example-legacy namespace: vela-system spec: workflow: steps: - name: apply-ns type: apply-component properties: component: ns-example-system - name: apply-resources type: apply-remaining components: - name: ns-example-system type: raw properties: apiVersion: v1 kind: Namespace metadata: name: example-system

它演示了两个关键设计：

1. 先决资源用工作流显式控制顺序：apply-ns先执行apply-component创建名为example-system的 Namespace，随后apply-resources通过apply-remaining把其余组件一并应用。这是插件安装时常见的"先建命名空间、再装业务资源"模式。
2. 骨架只负责最小能力：readme 明确指出，开发者可以在该模板基础上添加任意组件与工作流步骤以满足自身需求，而definitions/与resources/中渲染出的组件会被自动追加到spec.components。

从源码看，template.yaml由readTemplate通过 Kubernetes 的 YAML 解码器直接解析为v1beta1.Application（pkg/addon/addon.go）；最终渲染时，generateAppFramework会强制把 Application 的 name 改写为addon-name（Addon2AppName）、namespace 改写为vela-system，并自动打上addon.oam.dev/name与addon.oam.dev/version标签（pkg/addon/render.go）。因此插件作者在模板中手写的metadata.name与metadata.namespace最终都会被覆盖，仅作为可读性提示存在。

四、metadata.yaml：插件元数据字段逐一拆解

样例的 metadata.yaml 展示了元数据文件的完整形态：

name: example-legacy version: 1.0.1 description: Extended workload to do continuous and progressive delivery icon: https://raw.githubusercontent.com/fluxcd/flux/master/docs/_files/weave-flux.png url: https://fluxcd.io tags: - extended_workload - gitops - only_example deployTo: control_plane: true runtime_cluster: false dependencies: [] #- name: addon_name # set invisible means this won't be list and will be enabled when depended on # for example, terraform-alibaba depends on terraform which is invisible, # when terraform-alibaba is enabled, terraform will be enabled automatically # default: false invisible: false

对应到源码中的Meta结构体（pkg/addon/type.go），各字段的含义与行为如下：

deployTo对应源码中的DeployTo结构体（pkg/addon/type.go），包含三个字段：

• control_plane：是否部署到控制面集群（对应DisableControlPlane的反义逻辑）；
• runtime_cluster：是否部署到运行时集群（对应RuntimeCluster），这是新字段；
• legacyRuntimeCluster：兼容旧版的runtime_cluster字段（对应LegacyRuntimeCluster）。

当插件声明需要部署到运行时集群、但template.yaml中又没有显式声明 topology 策略时，渲染器会自动为 Application 追加拓扑策略：未指定集群时生成deploy-addon-to-all-clusters策略（空 labelSelector 表示部署到所有集群），指定集群时生成deploy-addon-to-specified-clusters策略并自动补上本地集群（见 pkg/addon/render.go 的attachPolicyForLegacyAddon）。而checkNeedAttachTopologyPolicy（pkg/addon/render.go）会在检测到冲突时打印告警，提示删除deployTo字段以免与已有 topology 策略冲突。

此外，样例还提供了 Chart.yaml，这是一个type: library的 Helm 库 chart，通过annotations.addon.name声明所属插件，并同步了name、version、description、icon、keywords等信息。这印证了插件在发布侧同时以 Helm 库包和目录两种形态存在的设计。

五、definitions/：X-Definition 如何变成组件

definitions/目录存放 X-Definition 文件（yaml 或 cue）。样例中的 helm.yaml 是一个完整的ComponentDefinition，其 CUE 模板会依据parameter.repoType的值动态生成三类 FluxCD 资源：

• git：生成GitRepository，支持git.branch分支参数与secretRef认证；
• oss：生成Bucket，支持bucketName、provider（默认generic，可选aws）、region；
• helm：生成HelmRepository。

同时在outputs.release中生成HelmRelease，指向sourceRef引用的仓库/桶，并支持targetNamespace、releaseName、values、pullInterval、timeout等参数；status.healthPolicy用context.outputs.release.status.conditions判定资源健康状态，workload.type声明为autodetects.core.oam.dev。整个模板通过parameter: {...}区块定义参数类型、默认值与// +usage=描述，例如pullInterval: *"5m" | string表示默认 5 分钟拉取间隔，version: *"*" | string表示 chart 版本默认取最新。

从渲染链路看，definitions/中的文件由readDefFile读取（pkg/addon/addon.go）：.cue后缀进入CUEDefinitions，.yaml/.yml后缀进入Definitions，其他后缀直接跳过。安装时，RenderDefinitions会把 YAML 定义直接解码为 unstructured 对象，把 CUE 定义通过definition.FromCUEString编译成 X-Definition，并将两者的 namespace 统一强制为vela-system（pkg/addon/addon.go）——插件安装的 X-Definition 只落在控制面集群。

六、resources/：参数暴露与两类组件渲染规则

resources/目录是插件参数与运行时资源的集中地，包含两种角色：

1. parameter.cue：参数即 Schema

resources/parameter.cue以 CUE 文件形式声明插件的可配置参数。安装器读取该文件后，会通过schema.ParsePropertiesToSchema（pkg/schema/schema.go）把它转换为 OpenAPI JSON Schema，再进一步生成 UI Schema 用于 VelaUX 等控制台渲染表单（见genAddonAPISchema，pkg/addon/addon.go）。这意味着插件参数的表单能力完全由这一个 CUE 文件驱动，参数定义里写清楚类型、默认值与描述，用户界面便自动生成对应输入控件。

2. 其余文件：两种组件渲染方式

readResFile（pkg/addon/addon.go）在读取时会先跳过parameter.cue，然后按扩展名分发：.cue进入CUETemplates，.yaml/.yml进入YAMLTemplates，其余后缀忽略。

• YAML 文件（单资源）：按 readme 的经典描述，每个只含单个资源的 YAML 会被渲染为raw组件；当前源码实现则会把目录下所有 YAML 资源统一打包进一个类型为k8s-objects、名为<addon-name>-resources的组件，属性为{"objects": [...]}（见renderK8sObjectsComponent，pkg/addon/render.go）。这两种表述分别对应经典文档语义与当前实现，读者在阅读旧文档与源码时需注意这一演进。
• CUE 模板文件：可以读取用户在parameter.cue中定义的parameter.XXX输入。渲染时，CUE 上下文会把参数 JSON 注入为parameter字段、把插件元数据注入为context.metadata，再与parameter.cue联合编译（见formatContext，pkg/addon/render.go）；模板的output字段被解析为组件对象，outputs字段中的对象则会作为辅助资源附加并打上addon.oam.dev/auxiliary标签。在这个格式里，CUE 模板可以直接指定组件的type与trait——这正是 readme 强调的"you can specify the type and trait in this format"能力的来源。若组件未显式命名，则默认以文件名为名（去掉扩展名、点号转连字符），见 pkg/addon/render.go。

七、渲染链路：从目录到最终 Application

把上述规则串起来，经典插件的完整渲染链路如下（核心代码位于 pkg/addon/render.go 的RenderApp）：

1. generateAppFramework：加载template.yaml（或 CUE 模板）作为应用骨架，强制改写 name/namespace 并打上 addon 标签；
2. renderNeededNamespaceAsComps：根据needNamespace等元数据自动生成 Namespace 组件；
3. renderResources（pkg/addon/render.go）：把所有 YAML 资源打包为k8s-objects组件，逐个渲染 CUE 模板组件（带package main头或缺少output的模板会被跳过，避免误渲染）；
4. attachPolicyForLegacyAddon：按deployTo与集群参数自动追加拓扑策略；
5. 最终 Application 连同definitions/渲染出的 X-Definition、schemas/渲染出的 UI Schema ConfigMap、views/渲染出的 VelaQL 视图等一起提交安装（参见RenderDefinitions、RenderConfigTemplates、RenderViews，pkg/addon/addon.go）。

安装器（Installer）随后执行版本校验（checkAddonVersionMeetRequired）、依赖安装（installDependency）、资源分发（dispatchAddonResource）与工作流继续（continueOrRestartWorkflow）四步（pkg/addon/addon.go）。安装时传入的参数还会被序列化进vela-system命名空间下的 Secret（RenderArgsSecret），用于重启或升级时恢复用户配置（pkg/addon/addon.go）。

八、从经典结构到新式结构：演进与兼容

example-legacy名称中的 "legacy" 暗示了它是被兼容保留的旧式结构。从Patterns列表（pkg/addon/addon.go）可以看到，新式插件引入了几类经典结构没有的文件：

• template.cue：以 CUE 方式编写整个 Application 骨架（与template.yaml二选一，两者同时提供会报ErrBothCueAndYamlTmpl，见 pkg/addon/render.go）；
• 根目录parameter.cue：全局参数文件，优先级高于resources/parameter.cue（两者同时存在时只采用全局参数并输出告警，见GetUIDataFromReader，pkg/addon/addon.go）；
• NOTES.cue：安装完成后输出给用户的提示信息；
• schemas/、views/、godef/：分别承载 UI Schema、VelaQL 视图与 Go 语言定义。

同时，readReadme（pkg/addon/addon.go）兼容README.md与readme.md两种大小写命名，且只读取其中之一作为插件详情。这意味着沿用经典目录结构编写的旧插件仍然可以被正常发现、展示与安装，为插件生态的渐进迁移提供了保障。

结语

通过example-legacy这份样例及其配套源码，可以完整掌握 KubeVela 经典插件的打包规范：template.yaml提供应用骨架与工作流，metadata.yaml声明元数据与部署目标，definitions/贡献 OAM 定义，resources/暴露参数并渲染运行时组件。理解这套规则，既能为存量插件做排查与迁移，也能为编写符合规范的新插件打下坚实基础；若需进一步验证渲染行为，可参考 pkg/addon/render_test.go 与 pkg/addon/addon_test.go 中的测试用例，或在本地通过vela addon enable命令对插件目录进行实装验证。

• 云原生
• DevOps
• 运维
• 微服务