V1.1 docs (#191)

* last check

* fix broken link

Co-authored-by: 段少 <duanwei.duan@alibaba-inc.com>
This commit is contained in:
Wei (段少) 2021-08-20 20:32:21 +08:00 committed by GitHub
parent 0009b58cab
commit 9938e8c481
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 98 additions and 168 deletions

View File

@ -1,5 +1,5 @@
--- ---
title: 系统插件:fluxcd title: fluxcd 插件
--- ---
## 开始之前 ## 开始之前

View File

@ -1,13 +1,13 @@
--- ---
title: 插件系统 title: 介绍
--- ---
本节会介绍如何使用 KubeVela 的默认系统插件Addon 本节会介绍如何使用 KubeVela 的默认系统插件Addon
## 背景 ## 背景
KubeVela 默认是一个应用管理和交付的控制平面,同时它也支持一系列开箱即用的功能,这些都通过系统插件的方式提供。系统管理员只需要一键即可开启这些默认的系统插件使用包括弹性扩缩容、可观测性、GitOps 在内的多种生态功能。 KubeVela 默认是一个应用管理和交付的控制平面,同时它也支持一系列开箱即用的功能,这些都通过系统插件的方式提供。你只需要有对 KubeVela 控制平面集群的写权限,即可一键即可开启这些默认的系统插件使用包括弹性扩缩容、可观测性、GitOps 在内的多种生态功能。
除此之外,系统管理员也可以将系统插件交由用户使用,同时根据需要添加自定义的系统插件。本质上,系统插件提供了一种统一的方式,可以灵活的安装、拆卸满足应用交付和应用管理不同场景的系统能力。 除此之外,你也可以让你的平台管理员,根据业务需要添加自定义的系统插件。本质上,系统插件提供了一种统一的方式,可以灵活的安装、拆卸满足应用交付和应用管理不同场景的系统能力。
一个系统插件通常可以包含如下两个组成部分: 一个系统插件通常可以包含如下两个组成部分:
- 系统组件,如 Kubernetes 的自定义资源CRD Controller系统所需的数据库、缓存、负载均衡等中间件其他容易需要安装运行的系统组件。 - 系统组件,如 Kubernetes 的自定义资源CRD Controller系统所需的数据库、缓存、负载均衡等中间件其他容易需要安装运行的系统组件。
- OAM 标准化定义X-Definition如组件定义ComponentDefinition可以将系统组件的能力通过 OAM 的标准方式提供给最终的用户使用。 - OAM 标准化定义X-Definition如组件定义ComponentDefinition可以将系统组件的能力通过 OAM 的标准方式提供给最终的用户使用。
@ -18,7 +18,6 @@ KubeVela 默认是一个应用管理和交付的控制平面,同时它也支
## 查看默认的系统插件 ## 查看默认的系统插件
1. 使用 vela CLI 查看可用的插件 1. 使用 vela CLI 查看可用的插件
```shell ```shell
@ -58,7 +57,7 @@ terraform Terraform Controller is a Kubernetes Controller for Terrafor
1. 需求 1. 需求
作为一个平台管理员,假设此时你的用户想以 helm chart 形式作为应用部署计划的组件,你需要满足这个需求。经过一番查阅,你发现 KubeVela 提供的名为 fluxcd 的插件已经满足了你的需求。 假设此时你想以 helm chart 形式作为应用部署计划的组件,你需要满足这个需求。经过一番查阅,你发现 KubeVela 提供的名为 fluxcd 的插件已经满足了你的需求。
这个插件已经将调协集群中的 helm chart 的能力整理好,准备了相关的组件定义,可以一键启用。 这个插件已经将调协集群中的 helm chart 的能力整理好,准备了相关的组件定义,可以一键启用。
@ -67,7 +66,7 @@ terraform Terraform Controller is a Kubernetes Controller for Terrafor
下面将以 fluxcd 为例,演示一个插件的安装和使用过程。 下面将以 fluxcd 为例,演示一个插件的安装和使用过程。
2. 以 fluxcd 这个插件为例,启用 fluxcd 以后, CLI 将会持续检查 fluxcd 插件的状态,直至其成功安装。 1. 以 fluxcd 这个插件为例,启用 fluxcd 以后, CLI 将会持续检查 fluxcd 插件的状态,直至其成功安装。
```shell ```shell
vela addon enable fluxcd vela addon enable fluxcd
@ -115,14 +114,3 @@ redis default 1 2021-08-17 04:12:49.3966701 +000
你可以使用 `vela addon disable fluxcd` 来禁用该插件。 请注意在禁用插件之前清理相关应用。注意如果直接禁用插件,带有 helm 类型的交付组件将无法被正确地删除。 你可以使用 `vela addon disable fluxcd` 来禁用该插件。 请注意在禁用插件之前清理相关应用。注意如果直接禁用插件,带有 helm 类型的交付组件将无法被正确地删除。
另外,要完全清理 fluxcd 插件,最后你还需要执行 `vela addon disable ns-flux-system`,这是 fluxcd 的辅助插件,需要手动禁用。 另外,要完全清理 fluxcd 插件,最后你还需要执行 `vela addon disable ns-flux-system`,这是 fluxcd 的辅助插件,需要手动禁用。
## 插件背后
实际上每个插件在 vela-system 名字空间中创建了一个 Initializer。可以用下面的方式查看
```shell
kubectl get initializer -n vela-system
NAME PHASE AGE
fluxcd success 23m
ns-flux-system success 23m
```

View File

@ -2,102 +2,6 @@
title: 云服务 title: 云服务
--- ---
KubeVela 允许你在一致的 API 中声明你的应用程序所需的云服务。 目前,我们推荐使用 Terraform 来支持 对云资源的集成需求往往是最频繁出现比如你可能希望数据库、中间件等服务使用阿里云、AWS 等云厂商的以获得生产级别的可用性并免去运维的麻烦。Terraform 是目前业内支持云资源最广泛也最受欢迎的组件KubeVela 对 Terraform 进行了额外的支持,使得我们可以通过 Kubernetes CRD 的方式配合 Terraform 使用任意的云资源
> 如果你对 KubeVela 中如何维护这些功能感兴趣,请查看 [云服务平台团队指南](../../platform-engineers/components/component-terraform)。 目前,需要你的平台管理员阅读[Terraform 组件](../../platform-engineers/components/component-terraform)后,进行开发然后部署为内置组件提供给你。
应用部署计划将通过 [Service Binding Trait](../traits/service-binding) 使用云服务。
## Terraform
> ⚠️ 本节假设 [Terraform 相关功能](../../platform-engineers/components/component-terraform) 已安装在你的平台中。
检查云资源 component 和 trait 的参数。
```shell
kubectl vela show alibaba-rds
```
```console
# Properties
+----------------------------+-------------------------------------------------------------------------+-----------------------------------------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+----------------------------+-------------------------------------------------------------------------+-----------------------------------------------------------+----------+---------+
| bucket | OSS bucket name | string | true | |
| acl | OSS bucket ACL, supported 'private', 'public-read', 'public-read-write' | string | true | |
| writeConnectionSecretToRef | The secret which the cloud resource connection will be written to | [writeConnectionSecretToRef](#writeConnectionSecretToRef) | false | |
+----------------------------+-------------------------------------------------------------------------+-----------------------------------------------------------+----------+---------+
## writeConnectionSecretToRef
+-----------+-----------------------------------------------------------------------------+--------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-----------+-----------------------------------------------------------------------------+--------+----------+---------+
| name | The secret name which the cloud resource connection will be written to | string | true | |
| namespace | The secret namespace which the cloud resource connection will be written to | string | false | |
+-----------+-----------------------------------------------------------------------------+--------+----------+---------+
```
```shell
kubectl vela show service-binding
```
```console
# Properties
+-------------+------------------------------------------------+------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-------------+------------------------------------------------+------------------+----------+---------+
| envMappings | The mapping of environment variables to secret | map[string]{...} | true | |
+-------------+------------------------------------------------+------------------+----------+---------+
```
### Alibaba Cloud RDS and OSS
示例 [application](https://github.com/oam-dev/kubevela/tree/master/docs/examples/terraform/cloud-resource-provision-and-consume/application.yaml) 如下。
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: webapp
spec:
components:
- name: express-server
type: webservice
properties:
image: zzxwill/flask-web-application:v0.3.1-crossplane
ports: 80
traits:
- type: service-binding
properties:
envMappings:
# environments refer to db-conn secret
DB_PASSWORD:
secret: db-conn # 1) If the env name is the same as the secret key, secret key can be omitted.
endpoint:
secret: db-conn
key: DB_HOST # 2) If the env name is different from secret key, secret key has to be set.
username:
secret: db-conn
key: DB_USER
# environments refer to oss-conn secret
BUCKET_NAME:
secret: oss-conn
- name: sample-db
type: alibaba-rds
properties:
instance_name: sample-db
account_name: oamtest
password: U34rfwefwefffaked
writeConnectionSecretToRef:
name: db-conn
- name: sample-oss
type: alibaba-oss
properties:
bucket: vela-website
acl: private
writeConnectionSecretToRef:
name: oss-conn
```

View File

@ -2,23 +2,17 @@
title: CUE 组件 title: CUE 组件
--- ---
> ⚠️ 请安装 [KubeVela CLI 命令行工具](../../getting-started/quick-install.mdx##3)
作为用户的你,一定希望随时可以找到开箱即用的组件,同时如果没有找到满足需求的组件,又可以灵活地自定义你想要的组件。 作为用户的你,一定希望随时可以找到开箱即用的组件,同时如果没有找到满足需求的组件,又可以灵活地自定义你想要的组件。
KubeVela 通过强大的 CUE 配置语言去粘合开源社区里的所有相关能力。我们给你提供了一些开箱即用的组件能力,也为你们的平台管理员,开放了灵活的自定义组件开发方式。 KubeVela 通过强大的 CUE 配置语言去粘合开源社区里的所有相关能力。我们给你提供了一些开箱即用的组件能力,也为你们的平台管理员,开放了灵活的自定义组件开发方式。
可以先使用指令看看我们已经通过 CUE 内置的组件能力: 可以先使 vela CLI 看看我们已经通过 CUE 默认内置的组件能力:
``` ```
$ vela components $ vela components
NAME NAMESPACE WORKLOAD DESCRIPTION NAME NAMESPACE WORKLOAD DESCRIPTION
alibaba-rds default configurations.terraform.core.oam.dev Terraform configuration for Alibaba Cloud RDS object
stateless default deployments.apps description not defined
task default jobs.batch Describes jobs that run code or a script to completion.
webserver default deployments.apps webserver is a combo of Deployment + Service
helm vela-system autodetects.core.oam.dev helm release is a group of K8s resources from either git
repository or helm repo
kustomize vela-system autodetects.core.oam.dev kustomize can fetching, building, updating and applying
Kustomize manifests from git repo.
raw vela-system autodetects.core.oam.dev raw allow users to specify raw K8s object in properties raw vela-system autodetects.core.oam.dev raw allow users to specify raw K8s object in properties
task vela-system jobs.batch Describes jobs that run code or a script to completion. task vela-system jobs.batch Describes jobs that run code or a script to completion.
webservice vela-system deployments.apps Describes long-running, scalable, containerized services webservice vela-system deployments.apps Describes long-running, scalable, containerized services
@ -31,4 +25,38 @@ worker vela-system deployments.apps Describes long-run
你所看到,在 vela-system 命令空间下的 webservice、task 和 worker 等组件类型,都是通过 CUE 模版来内置的。 你所看到,在 vela-system 命令空间下的 webservice、task 和 worker 等组件类型,都是通过 CUE 模版来内置的。
在你想要通过自定义组件来满足需求的时候,可以自己查看管理员手册里的[自定义组件](../../platform-engineers/components/custom-component)进行开发,或者请求你们的平台管理员进行开发。 我们以一个简单的 task 类型组件进行讲解,它用来给定一个运行代码或脚本的作业。
先用 vela CLI 查询熟悉一下 task 组件的配置项目:
```
$ vela show task
# Properties
+---------+-------------+----------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+---------+-------------+----------+----------+---------+
| cmd | | []string | false | |
| count | | int | true | 1 |
| restart | | string | true | Never |
| image | | string | true | |
+---------+-------------+----------+----------+---------+
```
然后编写一个如下的 YMAL 并部署到运行时集群:
```yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: app-worker
spec:
components:
- name: mytask
type: task
properties:
image: perl
count: 10
cmd: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
```
最后,在你想要通过自定义组件来满足需求的时候,可以自己查看管理员手册里的[自定义组件](../../platform-engineers/components/custom-component)进行开发,或者请求你们的平台管理员进行开发。

View File

@ -8,7 +8,7 @@ title: Helm 组件
## 开始之前 ## 开始之前
helm 类型组件开启 [fluxcd](../../reference/addon/fluxcd) 插件即可使用。 helm 类型组件开启 [fluxcd](../addons/fluxcd) 插件即可使用。
## 部署来自 Helm 仓库的 Chart ## 部署来自 Helm 仓库的 Chart

View File

@ -2,7 +2,7 @@
title: 版本对比 title: 版本对比
--- ---
另一个更进一步的验证需求是,升级部署版本所带来的表现是否符合期望。但我们同样希望,这个验证在本地试运行时就可以完成。 更进一步的验证需求是,升级部署版本所带来的表现是否符合期望。但我们同样希望,这个验证在本地试运行时就可以完成。
KubeVela 提供版本对比Live-diff这个功能来满足你的需求。它可以让你不用真的对运行时集群进行操作在本地就为你提供应用升级时的预览来进行确认。 KubeVela 提供版本对比Live-diff这个功能来满足你的需求。它可以让你不用真的对运行时集群进行操作在本地就为你提供应用升级时的预览来进行确认。

View File

@ -2,12 +2,27 @@
title: 云资源绑定 title: 云资源绑定
--- ---
// 云资源绑定和数据持久化,都需要通过写 Definition 来引入,要单开一个小节去讲 本节将介绍 `service-binding` 运维特征的用法,它能将数据从 Kubernetes `Secret` 绑定到应用程序所在容器的 `ENV` 上。
## 定义 ### 开始之前
服务绑定 trait 将数据从 Kubernetes `Secret` 绑定到应用程序容器的 ENV。
## 示例 > ⚠️ 请安装 [KubeVela CLI 命令行工具](../../getting-started/quick-install.mdx##3)
### 如何使用
先熟悉 `service-binding` 运维特征的相关信息:
```
$ vela show service-binding
# Properties
+-------------+------------------------------------------------+------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-------------+------------------------------------------------+------------------+----------+---------+
| envMappings | The mapping of environment variables to secret | map[string]{...} | true | |
+-------------+------------------------------------------------+------------------+----------+---------+
```
然后编写一个名为 `webapp` 的应用部署计划来讲解:
```yaml ```yaml
apiVersion: core.oam.dev/v1beta1 apiVersion: core.oam.dev/v1beta1
@ -28,9 +43,9 @@ spec:
# environments refer to db-conn secret # environments refer to db-conn secret
DB_PASSWORD: DB_PASSWORD:
secret: db-conn secret: db-conn
key: password # 1) If the env name is different from secret key, secret key has to be set. key: password # 1) 如果 ENV 和 Secret 不一致,则 Secret 必须被设置
endpoint: endpoint:
secret: db-conn # 2) If the env name is the same as the secret key, secret key can be omitted. secret: db-conn # 2) 如果 ENV 和 Secret 一致,则 Secret 可以缺省不写
username: username:
secret: db-conn secret: db-conn
@ -43,18 +58,12 @@ spec:
instanceClass: rds.mysql.c1.large instanceClass: rds.mysql.c1.large
username: oamtest username: oamtest
secretName: db-conn secretName: db-conn
```
部署这个 YAML
```
$ kubectl apply -f webapp.yaml
application.core.oam.dev/webapp created
``` ```
更详细的示例请参考【云资源】(../components/cloud-services) 我们在 alibaba-rds 获取的 `secretName: db-conn` 将会由 `service-binding` 对象进行转发,并注入 express-server 的这个组件的环境变量 ENV 中。
## 属性说明
```console
# Properties
+-------------+------------------------------------------------+------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+-------------+------------------------------------------------+------------------+----------+---------+
| envMappings | The mapping of environment variables to secret | map[string]{...} | true | |
+-------------+------------------------------------------------+------------------+----------+---------+
```

View File

@ -1,5 +1,5 @@
--- ---
title: 基础 title: 基础入门
--- ---
CUE 是 KubeVela 的核心依赖,也是用户实现自定义扩展的主要方式。本章节将详细介绍 CUE 的基础知识,帮助你更好地使用 KubeVela。 CUE 是 KubeVela 的核心依赖,也是用户实现自定义扩展的主要方式。本章节将详细介绍 CUE 的基础知识,帮助你更好地使用 KubeVela。

View File

@ -1,5 +1,5 @@
--- ---
title: 可观测性 Observability title: 系统可观测性
--- ---
可观测性插件Observability addon基于 metrics、logging、tracing 数据,可以为 KubeVela core 提供系统级别的监控,也可以为应用提供业务级别的监控。 可观测性插件Observability addon基于 metrics、logging、tracing 数据,可以为 KubeVela core 提供系统级别的监控,也可以为应用提供业务级别的监控。
@ -16,29 +16,29 @@ KubeVela 可观测能力是通过 [Grafana](https://grafana.com/) 展示的,
1CPU、内存等使用量和使用率数据 1CPU、内存等使用量和使用率数据
![](../../resources/observability-system-level-summary-of-source-usages.png) ![](../resources/observability-system-level-summary-of-source-usages.png)
2CPU、内存随着时间变化如过去三小时的使用量和使用率、已经每秒网络带宽的图形化展示 2CPU、内存随着时间变化如过去三小时的使用量和使用率、已经每秒网络带宽的图形化展示
![](../../resources/observability-system-level-summary-of-source-usages-chart.png) ![](../resources/observability-system-level-summary-of-source-usages-chart.png)
- 第二种用法KubeVela Core 日志监控 ### 第二种用法KubeVela Core 日志监控
1日志统计 1日志统计
可观测页面会显示KubeVela Core 日志总量,已经默认情况下,`error` 出现的数量、频率、出现的所有日志概览和详情。 可观测页面会显示KubeVela Core 日志总量,已经默认情况下,`error` 出现的数量、频率、出现的所有日志概览和详情。
![](../../resources/observability-system-level-logging-statistics.png) ![](../resources/observability-system-level-logging-statistics.png)
还会展示随着时间变化,`error` 日志出现的总量、频率等。 还会展示随着时间变化,`error` 日志出现的总量、频率等。
![](../../resources/observability-system-level-logging-statistics2.png) ![](../resources/observability-system-level-logging-statistics2.png)
2日志过滤 2日志过滤
在最上方填写关键词,还可以过滤日志。 在最上方填写关键词,还可以过滤日志。
![](../../resources/observability-system-level-logging-search.png) ![](../resources/observability-system-level-logging-search.png)
## 安装插件 ## 安装插件
@ -114,7 +114,7 @@ Forwarding from [::1]:80 -> 3000
通过浏览器访问 [http://127.0.0.1/dashboards](http://127.0.0.1/dashboards),点击相应的 Dashboard ,查看前面介绍的各种监控数据。 通过浏览器访问 [http://127.0.0.1/dashboards](http://127.0.0.1/dashboards),点击相应的 Dashboard ,查看前面介绍的各种监控数据。
![](../../resources/observability-system-level-dashboards.png) ![](../resources/observability-system-level-dashboards.png)
### 云服务商提供的 Kubernetes 集群 ### 云服务商提供的 Kubernetes 集群

View File

@ -17,7 +17,6 @@ module.exports = {
items: [ items: [
'core-concepts/architecture', 'core-concepts/architecture',
'core-concepts/application', 'core-concepts/application',
'core-concepts/workflow',
], ],
}, },
{ {
@ -59,6 +58,7 @@ module.exports = {
// 'end-user/traits/service-binding', // 'end-user/traits/service-binding',
'end-user/traits/annotations-and-labels', 'end-user/traits/annotations-and-labels',
'end-user/traits/sidecar', 'end-user/traits/sidecar',
'end-user/traits/service-binding',
// 'end-user/traits/metrics', // 'end-user/traits/metrics',
// 并入可观测性,不再用一个 trait 来实现,本文档留作参考 // 并入可观测性,不再用一个 trait 来实现,本文档留作参考
'end-user/traits/rollout', 'end-user/traits/rollout',
@ -79,7 +79,7 @@ module.exports = {
{ {
'Addons': [ 'Addons': [
'end-user/addons/introduction', 'end-user/addons/introduction',
'end-user/addons/observability', 'end-user/addons/fluxcd',
] ]
}, },
{ {
@ -91,16 +91,6 @@ module.exports = {
}, },
] ]
}, },
{
type: 'category',
label: 'Case Studies',
collapsed: false,
items: [
// 'case-studies/workflow-edge-computing', // 待完成
'case-studies/li-auto-inc',
'case-studies/workflow-with-ocm',
],
},
{ {
type: 'category', type: 'category',
label: 'Platform Admin Guide', label: 'Platform Admin Guide',
@ -152,6 +142,7 @@ module.exports = {
'platform-engineers/workflow/cue-actions', 'platform-engineers/workflow/cue-actions',
] ]
}, },
'platform-engineers/observability',
{ {
'Debugging': [ 'Debugging': [
'platform-engineers/debug/dry-run', 'platform-engineers/debug/dry-run',
@ -159,6 +150,16 @@ module.exports = {
}, },
] ]
}, },
{
type: 'category',
label: 'Case Studies',
collapsed: false,
items: [
// 'case-studies/workflow-edge-computing', // 待完成
'case-studies/li-auto-inc',
'case-studies/workflow-with-ocm',
],
},
{ {
type: 'category', type: 'category',
label: 'Using KubeVela CLI', label: 'Using KubeVela CLI',