Feat: refine addon extension docs
Signed-off-by: Jianbo Sun <jianbo.sjb@alibaba-inc.com>
This commit is contained in:
Jianbo Sun
parent
cae5c0ac3c
commit
c909c1bf75
|
|
@ -55,7 +55,47 @@ Other than the basic information such as name, version, tag, etc, it includes th
|
|||
|
||||
### template.yaml(Required)
|
||||
|
||||
Next, you need to write an addon application template file (template.yaml). Through the above introduction, we know that all files under the Addon Registry will eventually be rendered as a KubeVela application, then you can describe the basic information of the application through this file. For example, you can add specific tags or annotations to the application. Of course, you can also add components and workflowsteps directly in the application template file.
|
||||
Next, you need to write an addon application template file (template.yaml).
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: velaux
|
||||
namespace: vela-system
|
||||
spec:
|
||||
# component definition of resource dir .
|
||||
```
|
||||
|
||||
The template file is actually a template of KubeVela Application, resources can be automatically rendered to fill the spec.
|
||||
|
||||
All files under the Addon Registry will eventually be rendered as a KubeVela application, the template can be convenient if you want to describe some basic information of the application previously. For example, you can add specific tags or annotations to the application. Of course, you can also add components and workflowsteps directly in the application template file.
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: kruise
|
||||
namespace: vela-system
|
||||
spec:
|
||||
components:
|
||||
- name: kruise
|
||||
type: helm
|
||||
properties:
|
||||
repoType: git
|
||||
url: https://github.com/openkruise/kruise
|
||||
chart: ./charts/kruise/v1.0.0
|
||||
git:
|
||||
branch: master
|
||||
values:
|
||||
featureGates: PreDownloadImageForInPlaceUpdate=true
|
||||
workflow:
|
||||
steps:
|
||||
- name: apply-resources
|
||||
type: apply-application
|
||||
```
|
||||
|
||||
The example above will directly install openkurise addon from the helm chart.
|
||||
|
||||
Note that even if you set the application name through the `metadata.name` field, this setting will not take effect. When enabled, the application will be uniformly named in the format of addon-{addonName}.
|
||||
|
||||
|
|
@ -65,14 +105,17 @@ The addon's self-describing file is used to describe the main functionality of t
|
|||
|
||||
### Resources directory(Optional)
|
||||
|
||||
In addition to adding components directly in the template file, you can also create a `resources` directory in the Addom Registry, and add YAML/CUE type files in it. These files are eventually rendered into components and added to the application.
|
||||
In addition to adding components directly in the template file, you can also create a `resources` directory in the Addon Registry, add YAML/CUE type files in it. These files are eventually rendered into components and added to the application.
|
||||
|
||||
Among them, the YAML type file should contain a K8S resource object, which will be directly added to the application as a K8s-object type component during rendering.
|
||||
|
||||
#### CUE format resource
|
||||
|
||||
If you need to add a component to your application that needs to be rendered dynamically based on parameters when enabled, you can write a CUE format file as shown below:
|
||||
|
||||
```cue
|
||||
output: {
|
||||
type: "k8s-obeject"
|
||||
type: "k8s-object"
|
||||
properties: {
|
||||
apiVersion: "v1"
|
||||
kind: "ConfigMap"
|
||||
|
|
@ -99,17 +142,35 @@ You can see that `output` in the above example describes a component of type `k8
|
|||
|
||||
When the addon is enabled, the parameters need to be written in the `parameter.cue` file in CUE syntax. UX/CLI renders all CUE files and `parameter.cue` in one context when the addon is enabled, resulting in a set of components that are added to the application.
|
||||
|
||||
#### YAML format resource
|
||||
|
||||
The YAML format resources is just a Kubernetes YAML object, you can define any object one by one in a file.
|
||||
|
||||
For example, the [OCM](https://github.com/oam-dev/catalog/tree/master/addons/ocm-cluster-manager/resources) addon defines all it's resources in the addon. All these YAML objects will be rendered as components in an Application.
|
||||
|
||||
|
||||
### X-Definitions directory(Optional)
|
||||
|
||||
You can create a definition's file directory under the Addon Registry to store template definition files such as component definitions, trait definitions, and workflowstep definitions. It should be noted that since the KubeVela controller is usually not installed in the managed cluster, even if the addon is enabled by setting the `deployTo.runtimeCluster` field in the metadata file (metadata.yaml) to install the addon in the subcluster, the template definition file will not be distributed to sub-clusters.
|
||||
|
||||
For example, the [`fluxcd`](https://github.com/oam-dev/catalog/tree/master/addons/fluxcd/definitions) addon defines multiple ComponentDefinition and TraitDefinition.
|
||||
|
||||
### UI-Schema directory(Optional)
|
||||
|
||||
The schemas directory is used to store the UI-schema files corresponding to `X-Definitions`, which is used to enhance the display effect when displaying the parameters required by `X-Definitions` in UX.
|
||||
|
||||
The above is a complete introduction to how to make an addon, you can find the complete description of the above-mentioned addon in this [catalog](https://github.com/oam-dev/catalog/tree/master/experimental/addons/example) example.
|
||||
|
||||
In addition to uploading the addon resource files to your addon repository, you can also submit a pull request to KubeVela [official addon repository](https://github.com/oam-dev/catalog/tree/master/addons) and [experimental addon repository](https://github.com/oam-dev/catalog/tree/master/experimental/addons) to addon new addons. After pr merged your addons can be discovered and used by other KubeVela users.
|
||||
|
||||
## Install Addon Locally
|
||||
|
||||
You can install addon from local to debug your own addon:
|
||||
|
||||
```
|
||||
vela addon enable ./your-addon-dir/
|
||||
```
|
||||
|
||||
## Known Limits
|
||||
|
||||
- Now if you choose to enable the addon in the cluster, KubeVela will be installed in all subclusters by default, and the parameters filled in when enabling the addon will take effect in all clusters. Later, we plan to improve the multi-cluster addon management system, including supporting features such as cluster differential configuration.
|
||||
|
|
|
|||
|
|
@ -57,7 +57,47 @@ invisible: false
|
|||
|
||||
### 应用模版 (template.yaml) 文件 (必须)
|
||||
|
||||
接下来你还需要编写一个插件的应用模版文件 (template.yaml) ，因为通过上面的介绍，我们知道插件目录下面的所有文件最终会被渲染为一个 KubeVela 应用，那么你就可以通过该文件描述这个应用的基本信息，比如你可以为应用打上特定的标签或注解， 当然你也可以直接在该应用模版文件中添加组件和工作流步骤。
|
||||
接下来你还需要编写一个插件的应用模版文件 (template.yaml)，template 文件有一个固定的开头。
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
namespace: vela-system
|
||||
spec:
|
||||
# component definition of resource dir .
|
||||
```
|
||||
|
||||
|
||||
事实上，通过上面的介绍，我们知道插件目录下面的所有文件最终会渲染成为一个 KubeVela 的 Application 应用，所以这里的模板就是用于组成这个应用的框架。你可以通过该文件描述这个应用的特定信息，比如你可以为应用打上特定的标签或注解，当然你也可以直接在该应用模版文件中添加组件和工作流步骤。
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: kruise
|
||||
namespace: vela-system
|
||||
spec:
|
||||
components:
|
||||
- name: kruise
|
||||
type: helm
|
||||
properties:
|
||||
repoType: git
|
||||
url: https://github.com/openkruise/kruise
|
||||
chart: ./charts/kruise/v1.0.0
|
||||
git:
|
||||
branch: master
|
||||
values:
|
||||
featureGates: PreDownloadImageForInPlaceUpdate=true
|
||||
workflow:
|
||||
steps:
|
||||
- name: apply-resources
|
||||
type: apply-application
|
||||
```
|
||||
|
||||
如上例所示，这个 template.yaml 文件中就描述了一个完整的应用，通过 helm chart 部署 openkurise 插件.
|
||||
|
||||
需要注意的是，即使你通过 `metadata.name` 字段设置了应用的名称，该设置也不会生效，在启用时应用会统一以 addon-{addonName} 的格式被命名。
|
||||
|
||||
### 自描述 (README.md) 文件 (必须)
|
||||
|
|
@ -67,8 +107,16 @@ invisible: false
|
|||
### 组件资源 (resources) 目录 (非必须)
|
||||
|
||||
除了直接在模版文件中添加组件，你也可以在插件目录下创建一个 `resources` 目录，并在里面添加 YAML/CUE 类型的文件，这些文件最终会被渲染成组件并添加到应用当中。
|
||||
|
||||
#### YAML 格式的资源
|
||||
|
||||
其中，YAML 类型的文件中应该包含的是一个 K8S 资源对象，在渲染时该对象会被做为 K8s-object 类型的组件直接添加到应用当中。
|
||||
|
||||
|
||||
如 [OCM](https://github.com/oam-dev/catalog/tree/master/addons/ocm-cluster-manager/resources) 中插件的例子所示，所有 yaml 都会通过 KubeVela Application 中的 Component 形式，被部署到系统中。
|
||||
|
||||
#### CUE 格式的资源
|
||||
|
||||
如果你需要为应用添加一个需要在启用时根据参数动态渲染的组件，你就可以编写一个 CUE 格式的文件，如下所示。
|
||||
|
||||
```cue
|
||||
|
|
@ -112,12 +160,18 @@ schemas 目录用于存放`X-Definitions` 所对应的 UI-schema 文件，用于
|
|||
|
||||
除了将插件资源文件上传到自己的插件仓库中，你也可以通过提交 pull request 向 KubeVela [官方插件仓库](https://github.com/oam-dev/catalog/tree/master/addons) 和 [试验阶段插件仓库](https://github.com/oam-dev/catalog/tree/master/experimental/addons) 添加新的插件，pr 合并之后你的插件就可以被其他 KubeVela 用户发现并使用了。
|
||||
|
||||
## 本地安装（离线安装）
|
||||
|
||||
你可以通过本地安装的方式调试你的 addon，命令如下：
|
||||
|
||||
```
|
||||
vela addon enable ./your-addon-dir/
|
||||
```
|
||||
|
||||
## 已知局限 (Known Limits)
|
||||
|
||||
- 现在如果选择在集群中启用插件，KubeVela 会默认在所有子集群中安装，并且启用插件时所填的参数，会在所有集群中生效，之后计划完善多集群插件管理体系，包括支持集群差异化配置等特性。
|
||||
|
||||
- 尚缺少插件的版本管理，升降级等机制，之后计划完善这些特性。
|
||||
|
||||
- 尚缺少方便的本地插件调试手段，后续计划在 CLI 侧提供完善的插件本地调试的功能。
|
||||
|
||||
- 尚不支持仅在子集群中安装插件。 如果不在控制平面安装插件，仅安装在子集群中，会遇到诸多已知问题。
|
||||
|
|
@ -57,7 +57,47 @@ invisible: false
|
|||
|
||||
### 应用模版 (template.yaml) 文件 (必须)
|
||||
|
||||
接下来你还需要编写一个插件的应用模版文件 (template.yaml) ，因为通过上面的介绍，我们知道插件目录下面的所有文件最终会被渲染为一个 KubeVela 应用，那么你就可以通过该文件描述这个应用的基本信息，比如你可以为应用打上特定的标签或注解， 当然你也可以直接在该应用模版文件中添加组件和工作流步骤。
|
||||
接下来你还需要编写一个插件的应用模版文件 (template.yaml)，template 文件有一个固定的开头。
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
namespace: vela-system
|
||||
spec:
|
||||
# component definition of resource dir .
|
||||
```
|
||||
|
||||
|
||||
事实上，通过上面的介绍，我们知道插件目录下面的所有文件最终会渲染成为一个 KubeVela 的 Application 应用，所以这里的模板就是用于组成这个应用的框架。你可以通过该文件描述这个应用的特定信息，比如你可以为应用打上特定的标签或注解，当然你也可以直接在该应用模版文件中添加组件和工作流步骤。
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: kruise
|
||||
namespace: vela-system
|
||||
spec:
|
||||
components:
|
||||
- name: kruise
|
||||
type: helm
|
||||
properties:
|
||||
repoType: git
|
||||
url: https://github.com/openkruise/kruise
|
||||
chart: ./charts/kruise/v1.0.0
|
||||
git:
|
||||
branch: master
|
||||
values:
|
||||
featureGates: PreDownloadImageForInPlaceUpdate=true
|
||||
workflow:
|
||||
steps:
|
||||
- name: apply-resources
|
||||
type: apply-application
|
||||
```
|
||||
|
||||
如上例所示，这个 template.yaml 文件中就描述了一个完整的应用，通过 helm chart 部署 openkurise 插件.
|
||||
|
||||
需要注意的是，即使你通过 `metadata.name` 字段设置了应用的名称，该设置也不会生效，在启用时应用会统一以 addon-{addonName} 的格式被命名。
|
||||
|
||||
### 自描述 (README.md) 文件 (必须)
|
||||
|
|
@ -67,8 +107,16 @@ invisible: false
|
|||
### 组件资源 (resources) 目录 (非必须)
|
||||
|
||||
除了直接在模版文件中添加组件，你也可以在插件目录下创建一个 `resources` 目录，并在里面添加 YAML/CUE 类型的文件，这些文件最终会被渲染成组件并添加到应用当中。
|
||||
|
||||
#### YAML 格式的资源
|
||||
|
||||
其中，YAML 类型的文件中应该包含的是一个 K8S 资源对象，在渲染时该对象会被做为 K8s-object 类型的组件直接添加到应用当中。
|
||||
|
||||
|
||||
如 [OCM](https://github.com/oam-dev/catalog/tree/master/addons/ocm-cluster-manager/resources) 中插件的例子所示，所有 yaml 都会通过 KubeVela Application 中的 Component 形式，被部署到系统中。
|
||||
|
||||
#### CUE 格式的资源
|
||||
|
||||
如果你需要为应用添加一个需要在启用时根据参数动态渲染的组件，你就可以编写一个 CUE 格式的文件，如下所示。
|
||||
|
||||
```cue
|
||||
|
|
@ -112,12 +160,18 @@ schemas 目录用于存放`X-Definitions` 所对应的 UI-schema 文件，用于
|
|||
|
||||
除了将插件资源文件上传到自己的插件仓库中，你也可以通过提交 pull request 向 KubeVela [官方插件仓库](https://github.com/oam-dev/catalog/tree/master/addons) 和 [试验阶段插件仓库](https://github.com/oam-dev/catalog/tree/master/experimental/addons) 添加新的插件，pr 合并之后你的插件就可以被其他 KubeVela 用户发现并使用了。
|
||||
|
||||
## 本地安装（离线安装）
|
||||
|
||||
你可以通过本地安装的方式调试你的 addon，命令如下：
|
||||
|
||||
```
|
||||
vela addon enable ./your-addon-dir/
|
||||
```
|
||||
|
||||
## 已知局限 (Known Limits)
|
||||
|
||||
- 现在如果选择在集群中启用插件，KubeVela 会默认在所有子集群中安装，并且启用插件时所填的参数，会在所有集群中生效，之后计划完善多集群插件管理体系，包括支持集群差异化配置等特性。
|
||||
|
||||
- 尚缺少插件的版本管理，升降级等机制，之后计划完善这些特性。
|
||||
|
||||
- 尚缺少方便的本地插件调试手段，后续计划在 CLI 侧提供完善的插件本地调试的功能。
|
||||
|
||||
- 尚不支持仅在子集群中安装插件。 如果不在控制平面安装插件，仅安装在子集群中，会遇到诸多已知问题。
|
||||
|
|
@ -55,7 +55,47 @@ Other than the basic information such as name, version, tag, etc, it includes th
|
|||
|
||||
### template.yaml(Required)
|
||||
|
||||
Next, you need to write an addon application template file (template.yaml). Through the above introduction, we know that all files under the Addon Registry will eventually be rendered as a KubeVela application, then you can describe the basic information of the application through this file. For example, you can add specific tags or annotations to the application. Of course, you can also add components and workflowsteps directly in the application template file.
|
||||
Next, you need to write an addon application template file (template.yaml).
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: velaux
|
||||
namespace: vela-system
|
||||
spec:
|
||||
# component definition of resource dir .
|
||||
```
|
||||
|
||||
The template file is actually a template of KubeVela Application, resources can be automatically rendered to fill the spec.
|
||||
|
||||
All files under the Addon Registry will eventually be rendered as a KubeVela application, the template can be convenient if you want to describe some basic information of the application previously. For example, you can add specific tags or annotations to the application. Of course, you can also add components and workflowsteps directly in the application template file.
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: kruise
|
||||
namespace: vela-system
|
||||
spec:
|
||||
components:
|
||||
- name: kruise
|
||||
type: helm
|
||||
properties:
|
||||
repoType: git
|
||||
url: https://github.com/openkruise/kruise
|
||||
chart: ./charts/kruise/v1.0.0
|
||||
git:
|
||||
branch: master
|
||||
values:
|
||||
featureGates: PreDownloadImageForInPlaceUpdate=true
|
||||
workflow:
|
||||
steps:
|
||||
- name: apply-resources
|
||||
type: apply-application
|
||||
```
|
||||
|
||||
The example above will directly install openkurise addon from the helm chart.
|
||||
|
||||
Note that even if you set the application name through the `metadata.name` field, this setting will not take effect. When enabled, the application will be uniformly named in the format of addon-{addonName}.
|
||||
|
||||
|
|
@ -65,14 +105,17 @@ The addon's self-describing file is used to describe the main functionality of t
|
|||
|
||||
### Resources directory(Optional)
|
||||
|
||||
In addition to adding components directly in the template file, you can also create a `resources` directory in the Addom Registry, and add YAML/CUE type files in it. These files are eventually rendered into components and added to the application.
|
||||
In addition to adding components directly in the template file, you can also create a `resources` directory in the Addon Registry, add YAML/CUE type files in it. These files are eventually rendered into components and added to the application.
|
||||
|
||||
Among them, the YAML type file should contain a K8S resource object, which will be directly added to the application as a K8s-object type component during rendering.
|
||||
|
||||
#### CUE format resource
|
||||
|
||||
If you need to add a component to your application that needs to be rendered dynamically based on parameters when enabled, you can write a CUE format file as shown below:
|
||||
|
||||
```cue
|
||||
output: {
|
||||
type: "k8s-obeject"
|
||||
type: "k8s-object"
|
||||
properties: {
|
||||
apiVersion: "v1"
|
||||
kind: "ConfigMap"
|
||||
|
|
@ -99,17 +142,35 @@ You can see that `output` in the above example describes a component of type `k8
|
|||
|
||||
When the addon is enabled, the parameters need to be written in the `parameter.cue` file in CUE syntax. UX/CLI renders all CUE files and `parameter.cue` in one context when the addon is enabled, resulting in a set of components that are added to the application.
|
||||
|
||||
#### YAML format resource
|
||||
|
||||
The YAML format resources is just a Kubernetes YAML object, you can define any object one by one in a file.
|
||||
|
||||
For example, the [OCM](https://github.com/oam-dev/catalog/tree/master/addons/ocm-cluster-manager/resources) addon defines all it's resources in the addon. All these YAML objects will be rendered as components in an Application.
|
||||
|
||||
|
||||
### X-Definitions directory(Optional)
|
||||
|
||||
You can create a definition's file directory under the Addon Registry to store template definition files such as component definitions, trait definitions, and workflowstep definitions. It should be noted that since the KubeVela controller is usually not installed in the managed cluster, even if the addon is enabled by setting the `deployTo.runtimeCluster` field in the metadata file (metadata.yaml) to install the addon in the subcluster, the template definition file will not be distributed to sub-clusters.
|
||||
|
||||
For example, the [`fluxcd`](https://github.com/oam-dev/catalog/tree/master/addons/fluxcd/definitions) addon defines multiple ComponentDefinition and TraitDefinition.
|
||||
|
||||
### UI-Schema directory(Optional)
|
||||
|
||||
The schemas directory is used to store the UI-schema files corresponding to `X-Definitions`, which is used to enhance the display effect when displaying the parameters required by `X-Definitions` in UX.
|
||||
|
||||
The above is a complete introduction to how to make an addon, you can find the complete description of the above-mentioned addon in this [catalog](https://github.com/oam-dev/catalog/tree/master/experimental/addons/example) example.
|
||||
|
||||
In addition to uploading the addon resource files to your addon repository, you can also submit a pull request to KubeVela [official addon repository](https://github.com/oam-dev/catalog/tree/master/addons) and [experimental addon repository](https://github.com/oam-dev/catalog/tree/master/experimental/addons) to addon new addons. After pr merged your addons can be discovered and used by other KubeVela users.
|
||||
|
||||
## Install Addon Locally
|
||||
|
||||
You can install addon from local to debug your own addon:
|
||||
|
||||
```
|
||||
vela addon enable ./your-addon-dir/
|
||||
```
|
||||
|
||||
## Known Limits
|
||||
|
||||
- Now if you choose to enable the addon in the cluster, KubeVela will be installed in all subclusters by default, and the parameters filled in when enabling the addon will take effect in all clusters. Later, we plan to improve the multi-cluster addon management system, including supporting features such as cluster differential configuration.
|
||||
|
|
|
|||
Loading…
Reference in New Issue