关于阿里云:KubeVela-插件指南轻松扩展你的平台专属能力

作者： 姜洪烨

KubeVela 插件（addon）能够不便地扩大 KubeVela 的能力。正如咱们所知，KubeVela 是一个微内核高度可扩大的平台，用户能够通过模块定义（Definition）[ 1] 扩大 KubeVela 的零碎能力，而 KubeVela 插件正是不便将这些 自定义扩大 及其 依赖 打包并散发的外围性能。不仅如此，KubeVela 社区的插件核心也在逐步壮大，现在曾经有超过 50 款插件，涵盖可观测性、微服务、FinOps、云资源、平安等大量场景性能。

本文将会全方位介绍 KubeVela 插件的外围机制，教你如何编写一个自定义插件。在最初，咱们将展现最终用户应用插件的体验，以及插件将如何融入到 KubeVela 平台，为用户提供统一的体验。

为什么要应用 KubeVela 插件

用户应用插件的一个典型办法是通过 KubeVela 团队保护的插件核心（addon catalog）[ 2]，它蕴含了 KubeVela 团队与社区开发者精心编写的零碎扩大性能，并以插件的模式公布于插件核心，这样你能够一键下载并装置这些插件。例如装置 FluxCD 能够疾速给你的 KubeVela Application 提供部署 Helm Chart 的能力。

相较于应用 KubeVela 的插件性能，如果你本人的外部平台想要集成一个云原生的性能，你大略会这么做：

1. 通过 Helm Chart 或者下载 yaml 文件手动装置 FluxCD 或相似的 CRD Operator。
2. 编写系统集成的代码，让用户界面能够通过对立的形式应用 FluxCD 等 CRD 的性能，在 KubeVela 零碎中就是通过编写模块定义（OAM Definition）实现。

实际上，在 KubeVela 1.1 版本之前，咱们也是通过相似的形式实现的。这会带来如下问题：

1. 操作繁琐：用户须要手动查阅文档如何装置 FluxCD 并解决可能产生的谬误
2. 资源扩散：用户须要下载不同的文件，既须要装置 Helm 装置 FluxCD 还须要下载模块定义等零碎扩大的集成配置
3. 难以散发复用：用户须要手动下载模块定义就注定了这些资源难以以一个对立的形式分发给用户，也无奈造成社区生态让不同的用户能够享受社区便当
4. 短少多集群反对：KubeVela 将多集群交付作为一等公民，而这样的手动装置零碎扩大的形式显然难以保护多集群的环境
5. 无版本治理：用户须要手动治理模块定义和 Controller 之间的版本 

而 KubeVela 插件就是为了逐个解决这些问题而诞生的。

KubeVela 插件是如何工作的

KubeVela 的插件次要蕴含两局部：

• 一部分是装置能力的提供者，通常是一个 CRD Operator/Controller。这个 装置过程本质上就是运行一个 OAM 利用，addon 交付中所应用的性能与一般利用能力齐全等价。
• 另一部分就是扩大能力跟 KubeVela 体系的粘合层，也就是模块定义和其余的一些集成配置。OAM 模块定义为用户提供了插件扩大出的组件、运维特色以及工作流步骤等性能，也帮忙 CRD Operator 提供用户敌对的形象，使得最终用户无需了解简单的 CRD 参数，只须要依据最佳实际提供必要的参数。

插件的工作机制如上图所示，KubeVela 的利用具备多集群交付的能力，所以也能帮忙插件中的 CRD Operator 部署到这些集群中。模块定义文件仅须要在管制面被 KubeVela 应用，所以无需部署到被管控的集群中。

提醒

一旦插件被装置，就会创立一个 KubeVela 利用，蕴含所有的相干资源和配置，这些配置都会设置 KubeVela 利用对外作为 OwnerReference（父节点）。当咱们想要卸载一个插件时，只须要删除这个利用，Kubernetes 提供的资源回收机制会主动将标记了 OwnerReference 的资源一并删除。

例如一个 Redis 插件，它能让用户在本人的利用中应用 Redis 集群类型的组件（Component），这样能够疾速创立 Redis 集群。那么这个插件至多会包含一个 Redis Operator 来提供创立 Redis 集群的能力（通过 Application 形容），还有一个组件的模块定义（ComponentDefinition）来提供 Redis 集群的组件类型。

所有整个插件的装置过程会将 Redis Operator 放在一个 KubeVela 利用中下发到多集群，而组件定义和 UI 扩大等配置文件则只部署到管制面集群并设置利用对象为 OwnerReference。

创立本人的插件

提醒

为保障以下内容性能全副可用，请确保你的 KubeVela 版本 为 v1.5+。

咱们将以 Redis 插件为例，解说如何从头创立一个 KubeVela 插件的理论过程。本次残缺的 Redis 插件代码见文末参考 [ 3]。

提醒

在这里咱们会尽可能全面的介绍制作插件中波及的外围常识，然而作为一个介绍性博客，咱们会尽量避免探讨过深的细节免得篇幅过于收缩，理解残缺的性能及细节能够参考自定义插件文档 [ 4]。

首先咱们须要思考咱们要创立的插件有什么作用？ 例如咱们假如 Redis 插件能够提供 redis-failover 类型的 Component，这样用户只需在 Application 中定义一个 redis-failover  Component 即可疾速创立 Redis 集群。

而后思考如何达到这个目标？要提供 redis-failover 类型的 Component 咱们须要定义一个 ComponentDefinition；要提供创立 Redis 集群的能力反对，咱们能够应用 Redis Operator [ 5]。那至此咱们的大指标就明确了：

• 编写插件的利用形容文件（OAM Application），这将会用于装置 Redis Operator（残缺代码能够到插件核心的 template.cue [ 6] 及 resources/ 目录 [ 7] 查看。）
• 编写 redis-failover 类型的 ComponentDefinition [8 ]（残缺代码请查看 definitions/ 目录 [9 ]）

不过在开始编写之前，咱们首先须要理解一个 KubeVela 插件的目录构造。后续咱们会在编写的过程中具体阐明每个文件的作用，在这里只需大抵理解有哪些文件即可。

提醒

命令行工具 vela addon init 能够帮忙你创立目录构造的初始化脚手架。

redis-operator/          
├── definitions           
│   └── redis-failover.cue 
├── resources              
│   ├── crd.yaml           
│   ├── redis-operator.cue
│   └── topology.cue       
├── metadata.yaml         
├── parameter.cue         
├── README.md             
└── template.cue

让咱们逐个来解释它们：

1. redis-operator/ 是目录名，同时也是插件名称，请保持一致。

2. definitions/ 用于寄存模块定义, 例如 TraitDefinition 和 ComponentDefinition。

3. redis-failover.cue 定义咱们编写的 redis-failover 组件类型，蕴含了用户如何应用这个组件的参数以及这个组件与底层资源交互的细节。

4. resources/ 用于寄存资源文件, 之后会在 template.cue 中应用他们独特组成一个 KubeVela 利用来部署插件。

5. crd.yaml 是 Redis Operator 的 Kubernetes 自定义资源定义，在 resources/ 文件夹中的 YAML 文件会被间接部署到集群中。

6. redis-operator.cue 一个 web-service 类型的 Component，用于装置 Redis Operator。

7. topology.cue 是可选的，帮忙 KubeVela 建设利用所纳管资源的拓扑关系。

8. metadata.yaml 是插件的元数据，蕴含插件名称、版本、保护人等，为插件核心提供了概览信息。

9. parameter.cue 插件参数定义，用户能够利用这些参数在插件装置时做轻量级自定义。

10. README.md 提供给最终用户浏览，蕴含插件使用指南等。

11. template.cue 定义插件最终部署时的残缺利用状态，蕴含一个 OAM 利用模板以及对其余资源对象的援用。

提醒

在插件中制作中咱们会宽泛应用 CUE 语言来编排配置，如果对 CUE 不相熟，能够花 10 分钟疾速查阅入门指南有一个根本理解。

parameter.cue

parameter: {
    //+usage=Redis Operator image.
    image: *"quay.io/spotahome/redis-operator:v1.1.0" | string
    // 其余省略
}

在 parameter.cue 中定义的参数都是用户能够自定义的（相似于 Helm Values），后续在 template.cue 或者 resources 中能够通过 parameter.<parameter-name> 拜访参数。在咱们的例子中，用户能够自定义 image，这样后续咱们创立 Redis Operator (redis-operator.cue) 的时候能够通过 parameter.image 应用用户指定的容器镜像。

参数不仅能够给用户预留装置时的自定义输出，还能够作为装置时的条件进行局部装置。比方 fluxcd 插件有一个参数叫 onlyHelmComponents [10 ]，它的作用就是能够帮忙用户只部署用于装置 Helm Chart 的组件能力，而其余控制器就能够不装置。如果你对于实现细节感兴趣，能够参考 fluxcd 插件的局部配置 [11 ]。

在设计提供什么参数供用户自定义插件装置时，咱们也应该遵循一下这些最佳实际来为用户提供更好的应用体验。

最佳实际

• 不要在 parameter.cue 中提供大量的细节参数，将大量细节形象出大量参数供用户调节是一个更好的做法
• 为参数提供默认值（如样例中的 image 参数）或将参数标记为可选（如样例的 clusters 参数），确保用户仅应用默认值能够失去一个可用的配置
• 为参数提供应用阐明（通过正文标记实现，见样例）
• 尽量放弃插件不同版本间的参数统一，避免因为降级导致不兼容

template.cue 和 resources/ 目录

这是寄存咱们利用形容文件的中央，即一个 OAM Application。这形容了理论的插件装置过程。咱们次要会在这里蕴含 Redis Operator，给集群提供治理 Redis 集群的能力。

template.cue 和 resources/ 目录实质上是雷同的，都是形成 KubeVela 利用的组成部分，且都是在同一个 package 下的 CUE 文件。

那为什么须要 resources 目录呢？除去历史起因，这次要是为了可读性的思考，在 Application 中蕴含大量资源的时候 template.cue 可能变得很长，这时咱们能够把资源搁置在 resource 中减少可读性。一般来说，咱们将 Application 的框架放在 template.cue 中，将 Application 外部的 Components、Traits 等信息放在 resource 目录中。

• template.cue

template.cue 定义了利用的框架，绝大多数内容都是固定写法，具体的作用能够参考代码块中的正文。

// template.cue 利用形容文件

// package 名称须要与 resources 目录中 cue 的 package 统一，不便援用 resources 目录中的内容
package main

// Application 模板中多数字段均为固定写法，你须要留神的只有 spec.components

output: {
    // 这是一个经典的 OAM Application
    apiVersion: "core.oam.dev/v1beta1"
    kind:       "Application"
    // 不须要 metadata
    spec: {
        components: [
            // 创立 Redis Operator
            redisOperator // 定义于 resources/redis-operator.cue 中
        ]
        policies: [
        // 这里会指定装置插件的 namespace，是否装置至子集群等
        // 多为固定写法，无需记忆，可查阅本次样例的残缺代码
        // https://github.com/kubevela/catalog/blob/master/experimental/addons/redis-operator/template.cue
        // 文档可参照 https://kubevela.net/zh/docs/end-user/policies/references
        ]
    }
}
// 定义资源关联规定，用于将资源粘合在一起。后续会着重介绍
// Documentation: https://kubevela.net/zh/docs/reference/topology-rule
outputs: topology: resourceTopology // 定义于 resources/topology.cue 中

在插件装置时，零碎次要关注两个关键字：

• 一是 output 字段，定义了插件对应的利用，在利用外部 spec.components 定义了部署的组件，在咱们的例子中援用了寄存在 resources/ 目录中的 redisOperator 组件。output 中的 Application 对象不是严格的 Kubernetes 对象，其中 metadata 里的内容（次要是插件名称）会被插件装置的过程主动注入。
• 另一个是 outputs 字段，定义了除了惯例利用之外的配置，任何你想要跟插件一起部署的额定 Kubernetes 对象都能够定义在这里。请留神 outputs 中的这些对象必须遵循 Kubernetes API。
• resources/ 资源文件

咱们这里应用一个 webservice 类型的 Component 来装置 Redis Operator。当然，如果你能够承受依赖 FluxCD 的话，你也能够应用 helm 类型的 Component 间接装置一个 Helm Chart（因为 helm 类型的 Component 次要由 FluxCD 插件提供）。不过编写 addon 的一个准则是尽量减少内部依赖，所以咱们这里应用 KubeVela 内置的 webservice 类型，而不是 helm。

// resources/redis-operator.cue

// package 名称与 template.cue 统一，不便在 template.cue 中援用以下的 redisOperator
package main

redisOperator: {
    // 这是 OAM Application 中的 Component，它将会创立一个 Redis Operator
    // https://kubevela.net/zh/docs/end-user/components/references
    name: "redis-operator"
    type: "webservice"
    properties: {
        // Redis Operator 镜像名称，parameter.image 即在 parameter.cue 中用户可自定义的参数
        image:           parameter.image
        imagePullPolicy: "IfNotPresent"
    }
    traits: [// 略]
}

你能够浏览代码块中的正文理解字段的具体作用。

• KubeVela 提供的资源粘合能力

值得注意的一个性能是资源关联规定 (Resource Topology) [ 12]。尽管它不是必须的，然而它能帮忙 KubeVela 建设利用所纳管资源的拓扑关系。这就是 KubeVela 如何将各种各样的资源粘合成 Application 的。这在咱们应用 Kubernetes 自定义资源（CR）的时候特地有用。

// resources/topology.cue

package main

import "encoding/json"

resourceTopology: {
    apiVersion: "v1"
    kind:       "ConfigMap"
    metadata: {
        name:      "redis-operator-topology"
        namespace: "vela-system"
        labels: {
            "rules.oam.dev/resources":       "true"
            "rules.oam.dev/resource-format": "json"
        }
    }
    data: rules: json.Marshal([{
        parentResourceType: {
            group: "databases.spotahome.com"
            kind:  "RedisFailover"
        }
        // RedisFailover CR 会创立以下三类资源
        childrenResourceType: [
            {
                apiVersion: "apps/v1"
                kind:  "StatefulSet"
            },
            // KubeVela 内置 Deployment 等资源的拓扑，因而无需持续向下编写
            {
                apiVersion: "apps/v1"
                kind:  "Deployment"
            },
            {
                apiVersion: "v1"
                kind:  "Service"
            },
        ]
    }])
}

在本例中，redis-failover 类型的 Component 会创立一个 CR，名为 RedisFailover。然而在没有资源关联规定的状况下，假如在你的 Application 中应用了 RedisFailover，尽管咱们晓得 RedisFailover 管控了数个 Redis Deployment，然而 KubeVela 并不知道 RedisFailover 之下有 Deployment。这时咱们能够通过 资源关联规定 将咱们对于 RedisFailover 的理解通知 KubeVela，这样 KubeVela 能够帮忙咱们建设起整个利用上面纳管资源的拓扑层级关系。此时你将取得 KubeVela 提供的许多有用性能，成果见运行插件 [ 13]。

提醒

资源的拓扑关联性能给咱们带来了许多有用的性能，最重要的是为 KubeVela 最终用户应用扩大能力提供了对立体验：

• VelaUX 资源拓扑视图，从利用到底层资源 Pod 的关联关系一应俱全，包含多集群
• 对立的 vela exec 命令能够在不同利用组件类型关联的底层容器中执行命令，包含多集群
• 对立的 vela port-forward 转发不同类型利用组件关联的底层容器端口，包含多集群
• 对立的 vela log 查看不同类型利用组件关联的底层容器日志，包含多集群
• 对立的 vela status –pod/–endpoint 查看不同类型利用组件关联的底层容器日志，取得可供拜访的地址等，包含多集群

definitions/ 目录

Definitions 目录寄存 KubeVela 模块定义（Definition）[ 14]，包含组件定义（ComponentDefinition）、策略定义（TraitDefinition）等。这是插件中最重要的局部，因为它蕴含了最终用户装置这个插件当前能够取得哪些性能。 有了这里定义的组件、运维特色、工作流等类型，最终用户就能够在利用中应用他们了。

在插件中编写模块定义跟惯例的编写流程统一，这是一个很大的话题，在这里咱们就不具体开展了。你能够通过浏览模块定义对应的文档理解其中的细节：

• 自定义组件 Component Definition [ 15]
• 自定义运维特色 Trait Definition [ 16]
• 自定义策略 Policy Definition [ 17]
• 自定义工作流步骤 Workflow Step Definition。[ 18]

在本例中，咱们编写 Redis 组件类型次要参照自定义组件 [ 19] 与 Redis Operator 应用文档 [ 20]，咱们将组件类型命名为 redis-failover，它会创立一个 RedisFailover 的 CR，这样刚刚增加的 Redis Operator 就能够帮忙创立 Redis 集群，见文末残缺代码 [ 21]。

metadata.yaml

这里蕴含了插件的元数据，即插件的名称、版本、零碎要求等，能够参考文末文档 [ 22]。须要留神的是，本次介绍的为 KubeVela v1.5 之后的新写法，因而须要防止应用某些不兼容的元数据字段，以下样例中蕴含了所有的可用元数据。

提醒

例如传统的 deployTo.runtimeCluster（装置至子集群）等元数据在新写法中已有代替（应用 topology Policy），该当应用新写法。可见残缺代码中的 template.cue [ 23]

# 插件名称，与目录名统一
name: redis-operator
# 插件形容
description: Redis Operator creates/configures/manages high availability redis with sentinel automatic failover atop Kubernetes.
# 展现用标签
tags:
- redis
# 插件版本
version: 0.0.1
# 展现用图标
icon: https://xxx.com
# 插件所蕴含我的项目的官网地址
url: https://github.com/spotahome/redis-operator
# 可能依赖的其余插件，例如 fluxcd
dependencies: []

# 零碎版本要求
system:
  vela: ">=v1.5.0"
  kubernetes: ">=1.19"

运行插件

至此咱们曾经将插件的次要局部编写实现，下载文末残缺代码 [ 24] 补全局部细节后，即可尝试运行。

下载失去 redis-operator 目录后，咱们能够通过 vela addon enable redis-operator 装置本地的 redis-operator 插件，这种本地装置插件的形式也能够不便你再制作时做一些调试。装置实现后就能够参考插件的 README [ 25] 试用咱们的 Redis 插件了！

提醒

这里也体现出插件的 README 的重要性，其中须要包含插件的作用、具体使用指南等，确保用户能够疾速上手。

在用户应用你编写的插件时，只需如下 4 行 yaml 即可在 Application 中创立蕴含 3 个 Node 的高可用 Redis 集群！相比于手动装置 Redis Operator 并创立 CR，甚至逐个手动配置 Redis 集群，插件的形式极大中央便了用户。

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: redis-operator-sample
spec:
  components:
    # This component is provided by redis-operator addon.
    # In this example, 2 redis instance and 2 sentinel instance
    # will be created.
    - type: redis-failover
      name: ha-redis
      properties:
        # You can increase/decrease this later to add/remove instances.
        replicas: 3

只需 apply 仅仅数行的 yaml 文件，咱们就轻松创立了如下图所示的整个简单的资源。并且因为咱们编写了资源关联规定 (Resource Topology)，用户能够通过 VelaUX 轻松取得刚刚创立的 Redis 集群的资源拓扑状态，理解 Application 底层资源的运行状况，不再受限于 Application Component 级别的可观测性。如图咱们能间接观测到整个 Application 的拓扑，直至每个 Redis Pod，可见图中局部 Pod 仍在筹备中：

在执行 vela exec/log/port-forward 等命令时也能够准确地看到 Application 底层蕴含的资源（即撑持 Redis 集群的 3 个 Redis Pod 和 3 个 Sentinel Pod）。

如果你在应用单集群，乍一看你可能不会感觉 exec 进一个 Pod 是很非凡的性能。然而一旦思考到多集群，可能在横跨多个集群的资源中跟单集群一样以对立的形式进行抉择查看可能极大的节省时间。

应用 vela status 命令能获取这个 Application 的运行状态，有了资源关联规定后能够更进一步，间接通过 vela 寻找出 Redis Sentinel 的 Endpoint 来拜访 Redis 集群：

结语

通过本文，置信你曾经理解插件的作用及制作插件的要点。通过插件体系，咱们将取得如下劣势：

1. 将平台的能力打包成一个易于装置、便于散发复用、且能够造成社区生态的插件市场。
2. 充沛复用 CUE 和 KubeVela 利用通过的弱小能力，将基础设施资源灵便定义并进行多集群散发。
3. 无论扩大的资源类型是什么，均能够接入利用体系，为最终用户提供统一的体验。

最初，如果你胜利制作了属于本人的插件，KubeVela 社区十分欢送开发者奉献插件至插件核心 [ 26]，这样你的插件还可能被其余 KubeVela 社区用户发现并应用！

您能够通过如下资料理解更多对于 KubeVela 以及 OAM 我的项目的细节：

• 我的项目代码库：github.com/oam-dev/kubevela 欢送 Star/Watch/Fork！
• 我的项目官方主页与文档：kubevela.io，从 1.1 版本开始，已提供中文、英文文档，更多语言文档欢送开发者进行翻译。
• 我的项目钉钉群：23310022；Slack：CNCF #kubevela Channel
• 退出微信群：请先增加以下 maintainer 微信号，表明进入 KubeVela 用户群：

戳此处：查看 KubeVela 我的项目官网！！

相干链接

[1] 模块定义（Definition）

https://kubevela.net/zh/docs/…

*[2] 插件核心（addon catalog）*

https://github.com/kubevela/c…

*[3] catalog/redis-operator*

https://github.com/kubevela/c…

*[4] 自定义插件文档 *

https://kubevela.net/zh/docs/…

*[5] Redis Operator*

https://github.com/spotahome/…

*[6] template.cue*

https://github.com/kubevela/c…

*[7] resources/*

https://github.com/kubevela/c…

*[8] ComponentDefinition*

https://kubevela.net/zh/docs/…

**
**

*[9] definitions/ 目录 *

https://github.com/kubevela/c…

*[10] onlyHelmComponents*

https://github.com/kubevela/c…

*[11] fluxcd 插件局部配置 *

https://github.com/kubevela/c…

*[12] 资源关联规定 (Resource Topology)*

https://kubevela.net/zh/docs/…

*[13] 运行插件 *

https://kubevela.io/zh/blog/2022/10/18/building-addon-introduction#%E8%BF%90%E8%A1%8C%E6%8F%92%E4%BB%B6

*[14] 模块定义（Definition）*

https://kubevela.io/docs/gett…

*[15] 自定义组件 Component Definition*

https://kubevela.io/docs/plat…

*[16] 自定义运维特色 Trait Definition*

https://kubevela.io/docs/plat…

*[17] 自定义策略 Policy Definition*

https://kubevela.io/docs/plat…

*[18] 自定义工作流步骤 Workflow Step Definition*

https://kubevela.io/docs/plat…

*[19] 自定义组件 *

https://kubevela.net/zh/docs/…

*[20] Redis Operator 应用文档 *

https://github.com/spotahome/…

*[21] 残缺代码 *

https://github.com/kubevela/c…

*[22] 文档 *

https://kubevela.net/zh/docs/platform-engineers/addon/intro#%E6%8F%92%E4%BB%B6%E7%9A%84%E5%9F%BA%E6%9C%AC%E4%BF%A1%E6%81%AF%E6%96%87%E4%BB%B6

*[23] template.cue*

https://github.com/kubevela/c…

*[24] 残缺代码 *

https://github.com/kubevela/c…

*[25] README*

https://github.com/kubevela/c…

*[26] 插件核心 *

https://github.com/kubevela/c…

11 月 5 日

杭州云栖小镇 - 云原生峰会

阿里云将联手识货、传音、禾连衰弱、新东方、心动网络、小红书等实战企业技术负责人

向你收回邀请

扫码即刻参会！