自定义插件

插件系统 - 图1提示

如果你喜欢手把手教程，你可以阅读这篇博客，它以 Redis Operator 为例教你如何制作一个插件并介绍用户的使用体验。

我们提供了 vela CLI 工具来帮助您快速生成含有样例的插件目录结构。另外，它也可以基于已有的 Helm Chart 或使用 引用资源 来引用在线资源生成插件。

例如，如果你想使用存储在仓库地址为：https://marketplace.azurecr.io/helm/v1/repo 中的 MongoDB 12.1.6 版本的 helm chart 来创建一个插件，你就可以执行下面的命令：

  1. vela addon init mongodb --helm-repo https://marketplace.azurecr.io/helm/v1/repo --chart mongodb --chart-version 12.1.16

运行此命令将会在您的本地路径中生成插件的基本目录：

  1. $ ls mongondb   
  2. NOTES.cue     README.md     definitions   metadata.yaml parameter.cue resources     schemas       template.cue  views

您也可以使用此工具基于一个存储在 OCI 仓库中的 helm chart 来生成插件文件。示例如下：

  1. vela addon init podinfo --helmrepo oci://ghcr.io/stefanprodan/charts --chart podinfo --chart-version 6.1.*

你也可以基于在线的 Kubernetes 对象创建插件，例如你可以这样直接引用数个在线 CRD ：

  1. vela addon init my-addon --url https://domain.com/crd1.yaml --url https://domain.com/crd2.yaml

上述的命令也可以组合使用，例如你可以同时基于 Helm Chart 和引用对象创建插件框架。

一个 KubeVela 插件就是一个主要包含了以下三类文件的集合:

  • 插件的基本信息文件 包括元数据文件（metadata.yaml）和插件介绍文档（README.md）。
  • 定义 KubeVela 的OAM 模型文件。包括模块化能力, UI 扩展，资源拓扑规则等。
  • 描述一个 KubeVela 应用（Application） 的 应用描述文件。通常插件中的模块化能力（Definition）背后需要一个 Kubernetes operator 的支撑，而应用描述文件的作用就是，定义一个包含相应的 Kubernetes 资源的 KubeVela 应用（application），进而由 KubeVela 控制器把 operator 安装到各个集群当中。

后面的章节会分别介绍这三类文件的作用和编写规则。

下图展示了在启用一个插件时，KubeVela 做了哪些事情, 主要包含以下三个步骤。

  • 当通过 UX/CLI 启用一个插件时，会从插件仓库把插件的源文件拉取下来。
  • 文件中OAM 模型文件文件会被直接下发到管控集群。 应用描述文件 会被用来渲染成一个 KubeVela 应用并创建。
  • 接下来运行在管控集群的 KubeVela 控制器完全按照应用（Application）的执行流程交付资源，与 KubeVela 其他的应用执行没有差别。

alt

接下来将介绍如何制作一个自己的插件。

通常，一个插件目录结构如下所示：

  1. ├── resources/
  2. │   ├── xxx.cue
  3. │   └── xxx.yaml
  4. ├── definitions/
  5. ├── schemas/
  6. ├── README.md
  7. ├── metadata.yaml
  8. ├── parameter.cue
  9. └── template.yaml

你也可以使用命令 vela addon init <your-addon-name> 帮你快速创建这个目录框架。

需要注意的是，上面的文件并不都是必须的。接下来将介绍每个文件和目录的详细作用。

这类文件在插件中是必须的。

首先你需要编写一个插件的元数据文件 (metadata.yaml) ，该文件描述了插件的名称、版本、描述等基本描述信息。只有包含这个文件，一个目录才会被识别为一个插件的文件目录, 一个元数据文件的例子如下所示：

  1. name: example
  2. version: 1.0.0
  3. description: Example addon.
  4. icon: xxx
  5. url: xxx
  7. tags:
  8.   - only_example
  10. deployTo:
  11.   runtimeCluster: false
  13. dependencies:
  14.   - name: addon_name
  16. system:
  17.   vela: ">=v1.4.0"
  18.   kubernetes: ">=1.19.0-0"
  20. invisible: false

所有的字段及其作用如下：

FieldRequiredTypeUsage
nameyesstring名称
versionyesstring版本，每次变更递增且符合 SemVer 规范
descriptionyesstring描述
iconnostring图标，图标将在 VelaUX 的插件页面展示
urlnostring插件所包含项目的官网地址
tagsno[]string标签
dependenciesno[]{ name: string, version: string}依赖的其他插件。你可以通过设置 version 字段来指定所依赖插件的版本，如果不设置将依赖最新版本。安装时 KubeVela 会保证依赖插件均已安装
system.velanostring环境中所要求的 KubeVela 的版本，如果不满足，安装将会被拒绝
system.kubernetesnostring环境中所要求的 Kubernetes 的版本
deployTo.runtimeClusternobool插件是否可以安装到子集群，默认不设置该字段插件不会安装在任何子集群中 （只在 YAML 描述插件应用时生效）

插件的介绍文档用于描述插件的主要功能，并且该文件会在 UX 的插件详情页面呈现给用户。所以介绍文档需要包含以下基本信息：

  • 这个插件是什么？
  • 为什么要使用该插件？使用案例或场景。
  • 如何使用？ End user 能够快速理解如何使用该插件。最好能够提供一个端到端的例子。
  • 安装了什么？ 插件中包含的模块化能力以及相关的 CRD 和 operator。

实验阶段的插件 通常没有这些非常严格的规则，但对于一个想要进阶到 认证仓库 的插件而言，介绍文档至关重要。

这类文件在插件中也是可以缺省的.

这个目录包含了插件所提供的模块化能力（Definition），安装插件之后这些能力就会被用户看到并使用。 该目录中的文件可以是一个 YAML 类型的 ComponentDefinition，TraitDefinitions 或 WorkflowStepDefinitions Kubernetes 资源对象（CustomResource）。也可以是 CUE 格式的 KubeVela def 文件，这类文件在启用时会被渲染成对应的 Kubernetes 资源对象再下发到集群。

需要注意的是，这些 Definition 只会被下发到管控集群。

该目录用于存放模块化能力（Definition）所对应的 UI-schema 文件，用于在 UX 中展示模块化能力（Definition）所需要填写参数时增强显示效果。需要注意的是，和模块化能力定义文件一样，这些文件仅会被下发到管控集群。

这类文件在插件中也是可以缺省的

经过上面介绍，我们知道插件中支撑某项模块化能力的 Kubernetes operator 需要通过一个 KubeVela 应用被安装。应用描述文件的作用就是定义这个插件应用。应用描述文件主要包含，应用模版文件（template.cue 或 template.yaml）和 资源文件（resources/ 目录下的文件 ）。这些文件可以通过 CUE 或 YAML 格式定义。

YAML 格式的应用描述文件的特点是编写简单，你只需要编写一系列包含 Kubernetes 资源对象的 YAML 文件来描述这个插件应用即可。而如果使用 CUE 格式的文件描述插件应用的话，插件将会具备以下能力：

  • 利用 CUE 语言灵活简洁的语法、丰富的内置函数及其参数校验能力，根据启动参数和插件元数据渲染和部署插件应用和附属资源。
  • 插件中可能包含多个模块化能力（Definition）及其背后支撑的 CRD Operator，他们能够根据启动参数被选择性安装。

文档使用 YAML 描述插件应用 详细介绍了 YAML 格式的应用描述文件的编写方法。 文档使用 CUE 描述插件应用 详细介绍了 CUE 格式的应用描述文件的编写方法。

你可以通过本地安装的方式调试你的 addon，命令如下：

  1. $ vela addon enable ./your-addon-dir/
  • 如果插件中包含了一些 CRD, 尚不支持仅在子集群中安装插件。因为 KubeVela 需要在管控平面中渲染出所有类型的资源再将其下发到子集群当中，如果插件不在管控平面安装的话 KubeVela 的控制器会遇到无法找到 CRD 错误。

如果你根据本文档制作了新的插件，除了将插件资源文件上传到自己的插件仓库中，你也可以通过提交 pull request 向 KubeVela 官方插件仓库 和 试验阶段插件仓库 添加新的插件，pr 合并之后你的插件就可以被其他 KubeVela 用户发现并使用了。

在为社区贡献插件时请留意以下规则：

  • 新插件应首先被接受为实验性插件，需要以下必要信息。

    • 在插件的 metadata.yaml 中定义的可访问图标 URL 和 source URL。

    • README.md 中详细介绍了插件的使用方法和作用。

    • 如果在示例目录中如果包含该插件的 KubeVela 应用的使用例子，则更容易被接受。

  • 一个试验阶段的插件具备以下条件可以提升为正式插件：

    • 该插件被添加到了仓库的 e2e-test 中，从而保证插件能够被正常启用。

    • KubeVela 的插件文档站 中有关于该插件的详细介绍文档。

  • 如果在使用插件的过程中，发现了插件的任何问题，欢迎在仓库中提交 issue 或者直接提交 pull request 修复此问题。在更新插件时，请注意务必修改对应插件的 metadata.yaml 文件中的 version 字段以升级插件版本。

Last updated on 2023年8月4日 by Daniel Higuero