refine docs (#259)

This commit is contained in:
Jianbo Sun 2021-09-10 09:18:12 +08:00 committed by GitHub
parent 474dd1c2bb
commit b080e31b50
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 97 additions and 155 deletions

View File

@ -96,23 +96,19 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/mast
## 2. Install KubeVela
1. Add helm chart repo for KubeVela
1. Add and update helm chart repo for KubeVela
```shell script
helm repo add kubevela https://charts.kubevela.net/core
```
2. Update the chart repo
```shell script
helm repo update
```
3. Install KubeVela
2. Install KubeVela
```shell script
helm install --create-namespace -n vela-system kubevela kubevela/vela-core
```
You can refer to [advanced installation guide](./platform-engineers/advanced-install) for more custom ways.
4. Verify chart installed successfully
3. Verify chart installed successfully
```shell script
helm test kubevela -n vela-system
```
@ -143,7 +139,7 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/mast
</details>
## 3. Get KubeVela CLI
## 3. [Optional] Get KubeVela CLI
KubeVela CLI gives you a simplified workflow to manage applications with optimized output. It is not mandatory though.
@ -203,7 +199,7 @@ sudo mv ./vela /usr/local/bin/vela
</TabItem>
</Tabs>
## 4. Enable Addons
## 4. [Optional] Enable Addons
KubeVela support a dozen of [out-of-box addons](./platform-engineers/advanced-install#Addons),
please at least enable following addons to make sure KubeVela functioning well:
@ -215,6 +211,8 @@ please at least enable following addons to make sure KubeVela functioning well:
## 5. Verify
> You can also using `kubectl get comp -A` and `kubectl get trait -A` instead if you haven't installed CLI.
* Get built-in component types by `vela` CLI:
```shell script
vela components

View File

@ -4,36 +4,36 @@ title: Bootstrap Parameters
The introduction of bootstrap parameters in KubeVela controller are listed as below
| Parameter Name | Type | Default Value | Description |
|:---------------------------:|:------:|:---------------------------------:|------------------------------------------------------------------------------|
| use-webhook | bool | false | Use Admission Webhook |
| webhook-cert-dir | string | /k8s-webhook-server/serving-certs | The directory of Admission Webhook cert/secret |
| webhook-port | int | 9443 | The address of Admission Webhook |
| metrics-addr | string | :8080 | The address of Prometheus metrics |
| enable-leader-election | bool | false | Enable Leader Election for Controller Manager and ensure that only one replica is active |
| leader-election-namespace | string | "" | The namespace of Leader Election ConfigMap |
| log-file-path | string | "" | The log file path |
| log-file-max-size | int | 1024 | The maximum size (MBi) of log files |
| log-debug | bool | false | Set the logging level to DEBUG, used in develop environment |
| application-revision-limit | int | 10 | The maximum number of application revisions to keep. When the number of revisions exceeeds this number, older version will be discarded |
| definition-revision-limit | int | 20 | The maximum number of definition revisions to keep |
| autogen-workload-definition | bool | true | Generate WorkloadDefinition for ComponentDefinition automatically |
| health-addr | string | :9440 | The address of health check |
| apply-once-only | string | false | The Workload and Trait will not change after being applied. Used in specific scenario |
| disable-caps | string | "" | Disable internal capabilities |
| storage-driver | string | Local | The storage driver for applications |
| informer-re-sync-interval | time | 1h | The resync period for for controller informer, also the time for application to be reconciled when no spec changes were made |
| system-definition-namespace | string | vela-system | The namespace for storing system definitions |
| concurrent-reconciles | int | 4 | The number of threads that controller uses to process requests |
| kube-api-qps | int | 50 | The QPS for controller to access apiserver |
| kube-api-burst | int | 100 | The burst for controller to access apiserver |
| oam-spec-var | string | v0.3 | The version of OAM spec to use |
| pprof-addr | string | "" | The address of pprof, default to be emtpy to disable pprof |
| perf-enabled | bool | false | Enable performance logging, working with monitoring tools like Loki and Grafana to discover performance bottleneck |
| Parameter Name | Type | Default Value | Description |
| :-------------------------: | :----: | :-------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------- |
| use-webhook | bool | false | Use Admission Webhook |
| webhook-cert-dir | string | /k8s-webhook-server/serving-certs | The directory of Admission Webhook cert/secret |
| webhook-port | int | 9443 | The address of Admission Webhook |
| metrics-addr | string | :8080 | The address of Prometheus metrics |
| enable-leader-election | bool | false | Enable Leader Election for Controller Manager and ensure that only one replica is active |
| leader-election-namespace | string | "" | The namespace of Leader Election ConfigMap |
| log-file-path | string | "" | The log file path |
| log-file-max-size | int | 1024 | The maximum size (MBi) of log files |
| log-debug | bool | false | Set the logging level to DEBUG, used in develop environment |
| application-revision-limit | int | 10 | The maximum number of application revisions to keep. When the number of revisions exceeeds this number, older version will be discarded |
| definition-revision-limit | int | 20 | The maximum number of definition revisions to keep |
| autogen-workload-definition | bool | true | Generate WorkloadDefinition for ComponentDefinition automatically |
| health-addr | string | :9440 | The address of health check |
| apply-once-only | string | false | The Workload and Trait will not change after being applied. Used in specific scenario |
| disable-caps | string | "" | Disable internal capabilities |
| storage-driver | string | Local | The storage driver for applications |
| informer-re-sync-interval | time | 1h | The resync period for for controller informer, also the time for application to be reconciled when no spec changes were made |
| system-definition-namespace | string | vela-system | The namespace for storing system definitions |
| concurrent-reconciles | int | 4 | The number of threads that controller uses to process requests |
| kube-api-qps | int | 50 | The QPS for controller to access apiserver |
| kube-api-burst | int | 100 | The burst for controller to access apiserver |
| oam-spec-var | string | v0.3 | The version of OAM spec to use |
| pprof-addr | string | "" | The address of pprof, default to be emtpy to disable pprof |
| perf-enabled | bool | false | Enable performance logging, working with monitoring tools like Loki and Grafana to discover performance bottleneck |
> Other parameters not listed in the table are old parameters used in previous versions, the latest version ( v1.1 ) does not use them.
### Key Parameters
## Key Parameters
- **informer-resync-interval**: The resync time of applications when no changes were made. A short time may cause controller to reconcile frequently but uselessly. The regular reconciles of applications can help ensure that application and its components keep up-to-date in case some unexpected differences.
- **concurrent-reconciles**: The number of threads to use for controller to handle requests. When rich CPU resources are available, a small number of working threads may lead to insufficient usage of CPU resources.

View File

@ -1,5 +1,5 @@
---
title: Built-in Workflow Definitions
title: Appendix - Built-in Workflow Definitions
---
KubeVela provides some built-in workflow step definitions for better experience.
@ -12,9 +12,7 @@ Apply all components and traits in Application.
### Parameter
| Name | Type | Description |
| :---: | :--: | :--: |
| - | - | - |
No arguments, used for custom steps before or after application applied.
### Example
@ -51,9 +49,9 @@ Wait for the specified Application to complete.
### Parameter
| Name | Type | Description |
| :---: | :--: | :--: |
| name | string | The name of the Application |
| Name | Type | Description |
| :-------: | :----: | :------------------------------: |
| name | string | The name of the Application |
| namespace | string | The namespace of the Application |
### Example
@ -94,10 +92,10 @@ Apply Application in different policies and envs.
### Parameter
| Name | Type | Description |
| :---: | :--: | :--: |
| Name | Type | Description |
| :----: | :----: | :--------------------: |
| policy | string | The name of the policy |
| env | string | The name of the env |
| env | string | The name of the env |
### Example
@ -166,14 +164,14 @@ Send messages to the webhook address.
### 参数
| Name | Type | Description |
| :---: | :--: | :-- |
| slack | Object | Optional, please fulfill its url and message if you want to send Slack messages |
| slack.url | String | Required, the webhook address of Slack |
| slack.message | Object | Required, the Slack messages you want to send, please follow [Slack messaging](https://api.slack.com/reference/messaging/payload) |
| dingding | Object | Optional, please fulfill its url and message if you want to send DingTalk messages |
| dingding.url | String | Required, the webhook address of DingTalk |
| dingding.message | Object | Required, the DingTalk messages you want to send, please follow [DingTalk messaging](https://developers.dingtalk.com/document/robots/custom-robot-access/title-72m-8ag-pqw) | |
| Name | Type | Description |
| :--------------: | :----: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| slack | Object | Optional, please fulfill its url and message if you want to send Slack messages |
| slack.url | String | Required, the webhook address of Slack |
| slack.message | Object | Required, the Slack messages you want to send, please follow [Slack messaging](https://api.slack.com/reference/messaging/payload) |
| dingding | Object | Optional, please fulfill its url and message if you want to send DingTalk messages |
| dingding.url | String | Required, the webhook address of DingTalk |
| dingding.message | Object | Required, the DingTalk messages you want to send, please follow [DingTalk messaging](https://developers.dingtalk.com/document/robots/custom-robot-access/title-72m-8ag-pqw) | |
### Example
@ -230,9 +228,9 @@ Suspend the current workflow, we can use `vela workflow resume appname` to resum
### Parameter
| Name | Type | Description |
| :---: | :--: | :--: |
| - | - | - |
| Name | Type | Description |
| :---: | :---: | :---------: |
| - | - | - |
### Example

View File

@ -1,5 +1,5 @@
---
title: Appendix - CUE Actions
title: Appendix - CUE Actions
---
This doc will illustrate the CUE actions provided in `vela/op` stdlib package.

View File

@ -7,11 +7,7 @@ KubeVela 的系统在默认安装的模式下,是一个只包含“控制平
![kubevela-arch](../resources/system-arch.png)
## 默认安装的控制器
在控制面集群中,默认就安装的组件为深绿色框,其中最核心的是 Application Controller也就是 KubeVela 的应用控制器。
### 应用Application控制器
## 应用Application控制器
应用控制器是 KubeVela 的核心控制器,也是 KubeVela 唯一一个必须要安装且不可替换的控制器,负责应用的全生命周期管控,主要包含应用版本化、交付模型引擎、工作流引擎等模块,即图中淡红色部分框图。
@ -19,83 +15,38 @@ KubeVela 的系统在默认安装的模式下,是一个只包含“控制平
* 交付模型引擎CUE EngineKubeVela 采用 Open Application ModelOAM作为应用交付模型并通过 [CUE](https://cuelang.org/) 配置语言来实现该模型从而以可编程的方式IaC对待交付组件、运维能力、用户输入和交付工作流进行统一的编排和管理。
* 工作流引擎Workflow Engine工作流是一次应用部署执行过程的描述用户可以通过工作流自己定义部署的完整流程或者灵活的插入各种步骤。举例来说用户可以在工作流的最开始加入一个环境初始化的节点这个工作流节点可以是创建一个运行时 Kubernetes 集群,或者是在一个环境上安装某种系统组件。然后再将应用部署到刚刚初始化完成的部署环境中。简而言之,**KubeVela 的工作流使得应用部署的完整流程可以通过一份声明式配置文件完成描述**。
### 模块定义Definition控制器
## 模块定义Definition控制器
模块定义Definition控制器管理各 OAM 模块对象的生命周期比如组件定义模块ComponentDefinition、运维特征模块TraitDefinition等等。模块定义控制器会为这些模块的修改生成不同的版本自动生成操作文档对接的 OpenAPI Schema 等辅助信息,方便其他系统对接。
### 环境初始化Initializer控制器
## 健康检查控制器
环境初始化Initializer控制器可以帮助用户自定义“什么构成一个环境”将构成环境所需的资源完整的创建起来。举例来说一个环境可能是一个 Kubernetes 集群同时加上一些 Ingress 之类的系统插件,那么环境初始化控制器就可以帮助你快速创建一个 Kubernetes 集群,同时在集群中安装这些系统插件。
健康检查控制器是默认的健康检查组件,将散落的 Kubernetes 资源汇总并提供应用整体的部署健康状态和拓扑结构,甚至能够将不同集群的健康状态汇总,并周期性的进行部署状态健康检查。
健康检查策略方面,不仅支持常见 Kubernetes 资源的自动化健康检查,同时可以基于 CUE 配置语言进行自定义健康检查策略。甚至平台构建者可以完全自己编写一个 Kubernetes 控制器,实现自定义健康检查逻辑。这一切都是基于 OAM 标准概念可插拔的。
环境初始化控制器同样使用 KubeVela 自身来交付所有的系统插件,由于 KubeVela 的天然具备高可扩展以及“交付一切“的能力,所以环境初始化控制器的功能非常灵活,可以满足任何环境的初始化需求。
### 健康检查Health Scope控制器
健康检查Health Scope控制器是默认的健康检查组件提供应用资源的部署拓扑图并周期性的进行部署状态健康检查健康检查规则同样可以基于 CUE 配置语言进行自定义。健康检查Health Scope是 OAM 里的标准概念,其实现也是可插拔的,平台构建者也可以定制实现自己的健康检查控制器,并自定义健康检查逻辑。
### 环境差异化配置EnvBinding控制器
## 环境差异化配置控制器
环境差异化配置EnvBinding控制器提供了针对不同的环境做差异化配置patch的能力同时可以结合多集群组件根据用户声明的策略将应用组件分发调度到不同的目标集群环境
## 云资源供应控制器
如今 Terraform 已经逐渐成为了云资源创建的主流方式,涵盖了几乎所有云厂商的资源模块。而这里的云资源供应控制器,就是将 Terraform 客户端的功能与 Kubernetes 控制器相结合,在服务端面向终态的持续管理云资源,为 KubeVela 创建可以持续维护和管理的云资源。这个模块也是可插拔的,可以替换成 Crossplane 等其他云资源创建方案。
## 灰度发布Rollout控制器
灰度发布Rollout控制器可以结合 KubeVela 不同的组件版本进行灰度发布,包含的功能有分批发布、发布暂停、发布回滚、按百分比发布等。可以对接的工作负载包括 Kubernetes 的 Deployment、StatefulSet 等原生能力,以及 OpenKruise 中的 [Cloneset](https://openkruise.io/zh-cn/docs/cloneset.html)。结合 Istio 等 Service Mesh 组件还可以实现蓝绿发布等高级发布功能。
除了默认安装的控制器外KubeVela 提供了包括多集群在内的一系列开箱即用的插件功能,只需要激活这些插件功能,就可以使用。
## 一键安装的插件化控制器
### 云资源 Terraform 控制器
如今 Terraform 已经逐渐成为了云资源创建的主流方式,涵盖了几乎所有云厂商的资源模块。而这里的 Terraform 控制器则是将 Terraform 客户端的功能与 Kubernetes 控制器相结合,在服务端面向终态的持续管理云资源,为 KubeVela 创建可以持续维护和管理的云资源。这个模块也是可插拔的,可以替换成 Crossplane 等其他云资源创建方案。
### 多集群OCM控制器
OCMOpen Cluster Management是 KubeVela 默认的多集群管理引擎,包含集群注册、集群管理、证书自动更新、多集群资源分发等核心功能。这个模块也是可插拔的,可以换成 Karmada 等多集群控制器。
除了控制面的组件以外KubeVela 还需要与实际运行时 Kubernetes 集群的各种工作负载和运维能力联动。主要方式是通过 OAM 模型是将他们作为 Component 和 Trait 背后的实际执行器。除了 Kubernetes 的默认资源外,也有一些是 KubeVela 通过插件机制一键就能安装的。
### OpenKruise 控制器
[OpenKruise](https://openkruise.io/) 控制器工作在运行时集群,提供了多种面向无状态、有状态应用管理的高级工作负载功能,通过 OpenKruise 中的各种高级工作负载,可以实现原地升级、镜像预热等高级功能。
### 灰度发布Rollout控制器
灰度发布Rollout控制器工作在运行时集群可以结合 KubeVela 不同的组件版本进行灰度发布,包含的功能有分批发布、发布暂停、发布回滚、按百分比发布等。可以对接的工作负载包括 Kubernetes 的 Deployment、StatefulSet 等原生能力,以及 OpenKruise 中的 [Cloneset](https://openkruise.io/zh-cn/docs/cloneset.html)。结合 Istio 等 Service Mesh 组件还可以实现蓝绿发布等高级发布功能。
### FluxCD 控制器
KubeVela 通过 FluxCD 控制器来实现 Helm, Kustomize 等组件的交付,并实现基于 GitOps 模式的组件交付功能。
### OpenKruise 控制器
## 系统数据流
KubeVela 的系统数据流如下图所示,其中黄色的实线和虚线为用户数据流向;紫色实线为控制面的数据流向。
![data-flow](../resources/data-flow.png)
### 控制面
KubeVela 多集群模式下,控制面的数据流动是由运行时集群主动拉取管控集群数据的。所以 Kubernetes 多集群网络连通性方面,只需要保证控制面集群的 Kubernetes 可被运行时集群单向访问即可。
云资源是由管控集群的控制器主动调用云的 API 完成。
### 数据面
KubeVela 的用户数据面数据流动采用 Pull 模式订阅模式KubeVela 会主动监听应用元数据变化来驱动后续的应用交付与管理流程。
对于传统的 CI 驱动应用交付模式,用户也可以选择 Push 模式将应用制品从 CI 流程打包生成后直接通过 CI 脚本推给 KubeVelaKubeVela 负责后续的应用交付与管理流程。
**为什么 KubeVela 数据面采用 Pull 模式?**
应用资源通过 Pull 模式下发逐渐成为了云原生社区的主流方式,主要有如下优点:
* 弱网环境下的自治能力
- Pull 模型在管控数据下发以后,能够形成单个集群(环境)的自治,在与管控集群发生网络联通故障时依然能够正常运行。在边缘场景下是刚需。
- 可以就近拉取数据,具备更好的性能。
* 可以做到环境独立的隔离性和安全性
- 管控集群和运行时集群可以做到数据隔离。比如运行时集群使用独立的镜像仓库、Helm 仓库、秘钥仓库等,实际的秘钥渲染在单集群中执行。在混合云场景下是刚需。
* 更好的scale能力支撑更大的规模
- Pull模式下只有管控数据需要统一下发数据面信息可以分散在不同的repo中减少了大量单点
- 在首次管控数据下发后,后续持续的发布可以由运行时集群自动化的进行持续交付,没有管控集群的限制,可以支撑更大的规模
* 更好的容灾能力
- 管控面的故障不影响运行时集群的持续运行
[OpenKruise](https://openkruise.io/) 控制器工作在运行时集群,提供了多种面向无状态、有状态应用管理的高级工作负载功能,通过 OpenKruise 中的各种高级工作负载,可以实现原地升级、镜像预热等高级功能。
## 下一步

View File

@ -94,24 +94,19 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/mast
## 2. 安装 KubeVela
1. 添加 KubeVela helm chart 仓库
1. 添加并更新 KubeVela helm chart 仓库
```shell script
helm repo add kubevela https://charts.kubevela.net/core
```
2. 更新 chart 仓库
```shell script
helm repo update
```
3. 安装 KubeVela
2. 安装 KubeVela
```shell script
helm install --create-namespace -n vela-system kubevela kubevela/vela-core
```
你可以参考 [`自定义安装`](./platform-engineers/advanced-install) 获取更多安装模式和功能。
你可以参考 [`自定义安装`](./platform-engineers/advanced-install) 获取更多安装模式和功能。
4. 验证 chart 安装是否成功
3. 验证 chart 安装是否成功
```shell script
helm test kubevela -n vela-system
```
@ -142,7 +137,7 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/mast
</details>
## 3. 安装 KubeVela CLI
## 3. 【可选】安装 KubeVela CLI
KubeVela CLI 可以让你更便捷地来管理应用交付。不过,它不是必须使用的。
@ -202,7 +197,7 @@ sudo mv ./vela /usr/local/bin/vela
</TabItem>
</Tabs>
## 4. 安装插件
## 4. 【可选】安装插件
KubeVela 支持一系列[开箱即用的插件](./platform-engineers/advanced-install#插件列表),建议您至少开启以下插件:
@ -214,6 +209,8 @@ KubeVela 支持一系列[开箱即用的插件](./platform-engineers/advanced-in
## 5. 查看已安装能力
> 如果没安装 vela 命令行工具,你也可以通过 `kubectl get comp -A` 和 `kubectl get trait -A` 代替.
* 通过 `vela` CLI 来看看有哪些组件类型:
```shell script
vela components

View File

@ -109,7 +109,7 @@ EOF
```
环境初始化 kruise 能帮你在集群中部署一个 [kruise](https://github.com/openkruise/kruise) 的控制器,给集群提供 kruise 的各种能力。
`dependsOn` 字段表示环境初始化 kruise 依赖环境初始化 fluxcd 提供的能力。 其中,环境初始化 fluxcd 是 KubeVela 内置的环境初始化,
`dependsOn` 字段表示环境初始化 kruise 依赖环境初始化 fluxcd 提供的能力。 其中,环境初始化 fluxcd 是 KubeVela 内置的环境初始化,
当集群中没有 `fluxcd` 这个环境初始化时KubeVela 会自动帮你安装。
```shell

View File

@ -1,5 +1,5 @@
---
title: 内置工作流步骤
title: 附录:内置工作流步骤
---
为了便于用户使用KubeVela 提供了一些内置的工作流步骤。
@ -12,9 +12,7 @@ title: 内置工作流步骤
### 参数
| 参数名 | 类型 | 说明 |
| :---: | :--: | :--: |
| - | - | - |
无需指定参数,主要用于应用部署前后增加自定义步骤。
### 示例
@ -51,9 +49,9 @@ spec:
### 参数
| 参数名 | 类型 | 说明 |
| :---: | :--: | :--: |
| name | string | 需要等待的 Application 名称 |
| 参数名 | 类型 | 说明 |
| :-------: | :----: | :-----------------------------------: |
| name | string | 需要等待的 Application 名称 |
| namespace | string | 需要等待的 Application 所在的命名空间 |
### 示例
@ -94,10 +92,10 @@ spec:
### 参数
| 参数名 | 类型 | 说明 |
| :---: | :--: | :--: |
| 参数名 | 类型 | 说明 |
| :----: | :----: | :--------------: |
| policy | string | 需要关联的策略名 |
| env | string | 需要关联的环境名 |
| env | string | 需要关联的环境名 |
### 示例
@ -166,13 +164,13 @@ spec:
### 参数
| 参数名 | 类型 | 说明 |
| :---: | :--: | :-- |
| slack | Object | 可选值,如果需要发送 Slack 信息,则需填写其 url 及 message |
| slack.url | String | 必填值Slack 的 Webhook 地址 |
| slack.message | Object | 必填值,需要发送的 Slack 信息,请符合 [Slack 信息规范](https://api.slack.com/reference/messaging/payload) |
| dingding | Object | 可选值,如果需要发送钉钉信息,则需填写其 url 及 message |
| dingding.url | String | 必填值,钉钉的 Webhook 地址 |
| 参数名 | 类型 | 说明 |
| :--------------: | :----: | :--------------------------------------------------------------------------------------------------------------------------------------- |
| slack | Object | 可选值,如果需要发送 Slack 信息,则需填写其 url 及 message |
| slack.url | String | 必填值Slack 的 Webhook 地址 |
| slack.message | Object | 必填值,需要发送的 Slack 信息,请符合 [Slack 信息规范](https://api.slack.com/reference/messaging/payload) |
| dingding | Object | 可选值,如果需要发送钉钉信息,则需填写其 url 及 message |
| dingding.url | String | 必填值,钉钉的 Webhook 地址 |
| dingding.message | Object | 必填值,需要发送的钉钉信息,请符合 [钉钉信息规范](https://developers.dingtalk.com/document/robots/custom-robot-access/title-72m-8ag-pqw) |
### 示例
@ -230,9 +228,9 @@ spec:
### 参数
| 参数名 | 类型 | 说明 |
| :---: | :--: | :--: |
| - | - | - |
| 参数名 | 类型 | 说明 |
| :----: | :---: | :---: |
| - | - | - |
### 示例