Update Traits in User Guide and add Section of Practical Case (#149)

* Update Traits in User Guide and add Section of Practical Case

* updates based on review

Co-authored-by: 段少 <duanwei.duan@alibaba-inc.com>
This commit is contained in:
Wei (段少) 2021-08-10 15:11:24 +08:00 committed by GitHub
parent 23385eeca9
commit c7e5160b05
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
22 changed files with 279 additions and 63 deletions

View File

@ -0,0 +1,5 @@
---
title: Practical Case
---
TBD

View File

@ -0,0 +1,5 @@
---
title: Practical Case
---
TBD

View File

@ -0,0 +1,5 @@
---
title: Practical Case
---
TBD

View File

@ -0,0 +1,5 @@
---
title: Practical Case
---
TBD

View File

@ -0,0 +1,5 @@
---
title: Practical Case
---
TBD

View File

@ -0,0 +1,5 @@
---
title: Practical Case
---
TBD

View File

@ -11,9 +11,9 @@
"message": "核心概念",
"description": "The label for Core Concepts in sidebar docs"
},
"sidebar.docs.category.CUE": {
"sidebar.docs.category.Learning CUE": {
"message": "CUE 语言",
"description": "The label for category CUE in sidebar docs"
"description": "The label for category Learning CUE in sidebar docs"
},
"sidebar.docs.category.Helm": {
"message": "Helm",
@ -23,9 +23,9 @@
"message": "Raw Template",
"description": "The label for category Raw Template in sidebar docs"
},
"sidebar.docs.category.Defining Traits": {
"sidebar.docs.category.Traits System": {
"message": "运维特征系统",
"description": "The label for category Defining Traits in sidebar docs"
"description": "The label for category Traits System in sidebar docs"
},
"sidebar.docs.category.Defining Cloud Service": {
"message": "定义 Cloud Service",
@ -67,21 +67,21 @@
"message": "参考",
"description": "The label for category References in sidebar docs"
},
"sidebar.docs.category.OAM": {
"sidebar.docs.category.Learning OAM": {
"message": "开放应用模型",
"description": "The label for category OAM in sidebar docs"
"description": "The label for category Learning OAM in sidebar docs"
},
"sidebar.docs.category.Initializer Platform Eng": {
"sidebar.docs.category.Environment System": {
"message": "交付环境系统",
"description": "The label for category Initializer Platform Eng in sidebar docs"
"description": "The label for category Environment System in sidebar docs"
},
"sidebar.docs.category.Workflow End User": {
"sidebar.docs.category.Workflow": {
"message": "定义交付工作流",
"description": "The label for category Workflow End User in sidebar docs"
},
"sidebar.docs.category.Workflow Platform Engineers": {
"sidebar.docs.category.Worfklow System": {
"message": "工作流系统",
"description": "The label for category Workflow Platform Engineers in sidebar docs"
"description": "The label for category Worfklow System in sidebar docs"
},
"sidebar.docs.category.Customize Traits": {
"message": "自定义运维特征",
@ -103,13 +103,13 @@
"message": "附录",
"description": "The label for category Appendix in sidebar docs"
},
"sidebar.docs.category.Defining Components": {
"sidebar.docs.category.Component System": {
"message": "组件系统",
"description": "The label for category Defining Components in sidebar docs"
"description": "The label for category Component System in sidebar docs"
},
"sidebar.docs.category.End User Guide": {
"sidebar.docs.category.User Guide": {
"message": "用户手册",
"description": "The label for category End User Guide in sidebar docs"
"description": "The label for category User Guide in sidebar docs"
},
"sidebar.docs.category.Components": {
"message": "选择待交付组件",
@ -119,11 +119,15 @@
"message": "挂载运维特征",
"description": "The label for category Traits in sidebar docs"
},
"sidebar.docs.category.Practical Case": {
"message": "实践案例",
"description": "The label for category Practical case in sidebar docs"
},
"sidebar.docs.category.Observability": {
"message": "新增可观测性",
"description": "The label for category Observability in sidebar docs"
},
"sidebar.docs.category.Scaler": {
"sidebar.docs.category.Scaling": {
"message": "扩缩容",
"description": "The label for category Scaler in sidebar docs"
},

View File

@ -1,11 +1,11 @@
---
title: 组件标签
title: 标签管理
---
`labels``annotations` 运维特征,允许你将标签和注释附加到组件。通过标签和注释,我们在实现业务逻辑时,能十分灵活的根据它们来对应地调用组件。
### 如何使用
## 列出 trait
`label``annotations` trait 允许你将标签和注释附加到组件。
首先,我们准备一个应用部署计划 YAML 如下:
```shell
# myapp.yaml
@ -29,23 +29,25 @@ spec:
"description": "web application"
```
部署这个 application.
根据业务需要,我们定义这个组件供 `stable` 发布使用,并描述它是一个网页应用程序的业务。
编写完毕后部署:
```shell
kubectl apply -f myapp.yaml
```
在运行时集群上,检查工作负载是否已成功创建。
成功后,在运行时集群上,检查应用是否已成功创建:
```bash
kubectl get deployments
```
```console
NAME READY UP-TO-DATE AVAILABLE AGE
express-server 1/1 1 1 15s
➜ vela ls
APP COMPONENT TYPE TRAITS PHASE HEALTHY STATUS CREATED-TIME
myapp express-server webservice labels,annotations running healthy 2021-08-09 17:13:10 +0800 CST
```
检查 `labels`.
一切正常。
让我们来使用命令检查 `labels`,符合预期的显示出来。
```bash
kubectl get deployments express-server -o jsonpath='{.spec.template.metadata.labels}'
@ -54,7 +56,7 @@ kubectl get deployments express-server -o jsonpath='{.spec.template.metadata.lab
{"app.oam.dev/component":"express-server","release": "stable"}
```
检查 `annotations`.
使用命令检查 `annotations`,符合预期的显示出来。
```bash
kubectl get deployments express-server -o jsonpath='{.spec.template.metadata.annotations}'

View File

@ -2,4 +2,116 @@
title: 自动扩缩容
---
TBD
本小节会介绍,如何为应用部署计划的一个待交付组件,配置自动扩缩容。我们使用运维特征里的 `cpuscaler` 来完成开发。
### 开始之前
> ⚠️ 请已安装 [KubeVela CLI 命令行工具](../../getting-started/quick-install.mdx##3)
### 如何使用
先熟悉 `cpuscaler` 运维特征的相关信息:
```
vela show cpuscaler
# Properties
+---------+---------------------------------------------------------------------------------+------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+---------+---------------------------------------------------------------------------------+------+----------+---------+
| min | Specify the minimal number of replicas to which the autoscaler can scale down | int | true | 1 |
| max | Specify the maximum number of of replicas to which the autoscaler can scale up | int | true | 10 |
| cpuUtil | Specify the average cpu utilization, for example, 50 means the CPU usage is 50% | int | true | 50 |
+---------+---------------------------------------------------------------------------------+------+----------+---------+
```
然后我们准备一个应用部署计划,并将 `cpuscaler` 运维特征,按业务需要设置好:
```yaml
# sample.yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: website
spec:
components:
- name: frontend # This is the component I want to deploy
type: webservice
properties:
image: nginx
traits:
- type: cpuscaler # Automatically scale the component by CPU usage after deployed
properties:
min: 1
max: 10
cpuPercent: 60
```
编写完毕,在 YAML 所在路径,部署该文件:
```shell
$ kubectl apply -f sample.yaml
application.core.oam.dev/website created
```
看看应用是否启动起来:
```shell
$ vela ls
NAME COMPONENT TYPE PHASE HEALTHY STATUS AGE
website frontend webservice running true 4m54s
```
最后查看应用相关信息,`cpuscaler` 在正常工作:
```shell
$ kubectl get app website -o yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
generation: 1
name: website
namespace: default
spec:
components:
- name: frontend
properties:
image: nginx
traits:
- properties:
cpuPercent: 60
max: 10
min: 1
type: cpuscaler
- properties:
image: fluentd
name: sidecar-test
type: sidecar
type: webservice
- name: backend
properties:
cmd:
- sleep
- "1000"
image: busybox
type: worker
status:
...
latestRevision:
name: website-v1
revision: 1
revisionHash: e9e062e2cddfe5fb
services:
- healthy: true
name: frontend
traits:
- healthy: true
type: cpuscaler
workloadDefinition:
apiVersion: apps/v1
kind: Deployment
status: running
```

View File

@ -1,13 +1,20 @@
---
title: 配置网关
---
本小节会介绍,如何为应用部署计划的一个组件,进行网关配置。我们使用运维特征里的 `ingress`,将组件暴露出去,可供公网访问。
> ⚠️ 本节要求你的运行时集群有一个有效的 ingress 控制器。
### 开始之前
`ingress` trait 通过有效域将组件暴露给公共 Internet。
> ⚠️ 需要你的集群已安装 [Ingress 控制器](https://kubernetes.github.io/ingress-nginx/deploy/)。
> ⚠️ 请已安装 [KubeVela CLI 命令行工具](../../getting-started/quick-install.mdx##3)
### 如何使用
先熟悉 `ingress` 运维特征的相关信息:
```shell
kubectl vela show ingress
vela show ingress
```
```console
# Properties
@ -19,7 +26,7 @@ kubectl vela show ingress
+--------+------------------------------------------------------------------------------+----------------+----------+---------+
```
`ingress` trait 附加到要公开和部署的组件。
使用时,我们将 `ingress` 运维特征,添加到待交付的组件中去:
```yaml
# vela-app.yaml
@ -42,14 +49,16 @@ spec:
"/": 8000
```
修改完毕,在 YAML 文件所在路径下,使用命令进行部署:
```bash
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/docs/examples/vela-app.yaml
kubectl apply -f vela-app.yaml
```
```console
application.core.oam.dev/first-vela-app created
```
检查状态,直到我们看到 `status``running` 并且服务为 `healthy`
我们看到 `status``running` 并且服务为 `healthy`,表示应用部署计划完全生效
```bash
kubectl get application first-vela-app -w
@ -60,7 +69,7 @@ first-vela-app express-server webservice healthChecking
first-vela-app express-server webservice running true 42s
```
检查其访问网址的 trait 详细信息
这时候,让我们查看网关提供的公网 IP
```shell
kubectl get application first-vela-app -o yaml
@ -84,7 +93,7 @@ spec:
...
```
然后你将能够通过其域访问该应用程序
然后你的用户就能够通过这个 IP来访问该应用程序了
```
curl -H "Host:testsvc.example.com" http://<your ip address>/

View File

@ -1,11 +1,18 @@
---
title: 手动扩缩容
---
本小节会介绍,如何为应用部署计划的一个待交付组件,配置手动扩缩容。我们使用运维特征里的 `scaler` 来完成开发。
`scaler` trait 允许你手动扩缩容你的组件实例。
### 开始之前
> ⚠️ 请已安装 [KubeVela CLI 命令行工具](../../getting-started/quick-install.mdx##3)
### 如何使用
先熟悉 `scaler` 运维特征的相关信息:
```shell
kubectl vela show scaler
vela show scaler
```
```console
# Properties
@ -16,7 +23,7 @@ kubectl vela show scaler
+----------+--------------------------------+------+----------+---------+
```
声明一个具有缩放 trait 的 application。
使用时,我们将 `salcer` 运维特征,添加到待交付的组件中去:
```yaml
# sample-manual.yaml
@ -47,16 +54,16 @@ spec:
- '1000'
```
应用示例 application
修改完毕,在 YAML 文件所在路径下,使用命令进行部署
```shell
kubectl apply -f https://raw.githubusercontent.com/oam-dev/kubevela/master/docs/examples/enduser/sample-manual.yaml
kubectl apply -f sample-manual.yaml
```
```console
application.core.oam.dev/website configured
```
在运行时集群中,你可以看到 `frontend` 组件的底层部署现在有2个副本。
应用部署计划完全生效后,当我们查看运行时集群,会看到 `frontend` 组件的底层部署现在有 2 个副本。
```shell
kubectl get deploy -l app.oam.dev/name=website
@ -67,4 +74,4 @@ backend 1/1 1 1 19h
frontend 2/2 2 2 19h
```
要扩容或缩容,你只需要修改`scaler` trait 的`replicas` 字段并重新应用YAML
如果要扩容或缩容,你只需要修改 `scaler` 运维特征的 `replicas` 字段,并重新应用 YAML 文件即可

View File

@ -2,11 +2,12 @@
title: 日志监控
---
## 描述
### 开始之前
配置你服务的监控指标。
> ⚠️ 请已安装 [KubeVela CLI 命令行工具](../../getting-started/quick-install.mdx##3)
### 如何使用
## 规范
列出 `Metrics` trait 的所有配置项。

View File

@ -2,6 +2,8 @@
title: 云资源绑定
---
// 云资源绑定和数据持久化,都需要通过写 Definition 来引入,要单开一个小节去讲
## 定义
服务绑定 trait 将数据从 Kubernetes `Secret` 绑定到应用程序容器的 ENV。

View File

@ -1,14 +1,19 @@
---
title: 容器注入
---
本小节会介绍,如何为应用部署计划的一个组件,添加 `sidecar` 运维特征来收集日志。
在本章节中,我们会展示如何使用 `sidecar` trait 来收集日志。
### 开始之前
> ⚠️ 请安装 [KubeVela CLI 命令行工具](../../getting-started/quick-install.mdx##3)
## 查看 Sidecar 的使用手册
### 如何使用
先熟悉 `ingress` 运维特征的相关信息:
```shell
$ kubectl vela show sidecar
$ vela show sidecar
# Properties
+---------+-----------------------------------------+-----------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
@ -29,9 +34,8 @@ $ kubectl vela show sidecar
+-----------+-------------+--------+----------+---------+
```
## 安装应用
应用的组件 `log-gen-worker` 和 sidecar 共享相同的日志数据目录。sidecar 会重新输出日志到标准输出中。
接下来,让我们来编写一个应用部署计划里的组件 `log-gen-worker`
同时,我们将 `sidecar` 所记录的日志数据目录和组件,指向同一个数据源 `varlog`
```yaml
# app.yaml
@ -71,13 +75,13 @@ spec:
path: /var/log
```
安装这个应用
编写完毕,在 YAML 文件所在路径下,部署这个应用:
```shell
kubectl apply -f app.yaml
```
检查应用生成的 workload
成功后,先检查应用生成的工作负载情况:
```shell
$ kubectl get pod
@ -85,7 +89,7 @@ NAME READY STATUS RESTARTS AGE
log-gen-worker-76945f458b-k7n9k 2/2 Running 0 90s
```
查看 sidecar 的输出
然后,查看 `sidecar` 的输出,日志显示正常。
```shell
$ kubectl logs -f log-gen-worker-76945f458b-k7n9k count-log

View File

@ -2,10 +2,14 @@
title: 数据持久化
---
本节介绍如何将 Cloud Volumes 附加到组件。 例如AWS ElasticBlockStore、
Azure Disk、阿里云OSS等。
本节介绍如何将 `Cloud Volumes` 添加到待交付的组件,来实现数据持久化的功能。 例如,我们会用到 AWS ElasticBlockStore、Azure Disk、阿里云 OSS 等。
云卷不是 KubeVela 中的内置功能,因此你需要先启用这些特性。 让我们以 AWS EBS 为例。
### 开始之前
可以用来实现数据持久化的运维特征,并不是 KubeVela 中的内置功能。所以为了实现它,你需要用到 XXX。
### 如何使用
让我们以 AWS EBS 为例。
安装并检查 AWS EBS volume 特征的 `TraitDefinition`

View File

@ -0,0 +1,5 @@
---
title: 实践案例
---
TBD

View File

@ -0,0 +1,5 @@
---
title: 实践案例
---
TBD

View File

@ -0,0 +1,5 @@
---
title: 实践案例
---
TBD

View File

@ -0,0 +1,5 @@
---
title: 实践案例
---
TBD

View File

@ -0,0 +1,5 @@
---
title: 实践案例
---
TBD

View File

@ -0,0 +1,5 @@
---
title: 实践案例
---
TBD

View File

@ -65,11 +65,13 @@ module.exports = {
'end-user/traits/autoscaler',
]
},
'end-user/traits/volumes',
'end-user/traits/service-binding',
// 云资源绑定和数据持久化,都需要通过写 Definition 来引入,要单开一个小节去讲
// 'end-user/traits/volumes',
// 'end-user/traits/service-binding',
'end-user/traits/annotations-and-labels',
'end-user/traits/sidecar',
'end-user/traits/metrics',
// 'end-user/traits/metrics',
// 并入可观测性,不再用一个 trait 来实现
'end-user/traits/rollout',
]
},
@ -83,6 +85,15 @@ module.exports = {
},
]
},
{
type: 'category',
label: 'Practical Case',
collapsed: false,
items: [
'practical-case/pc1',
'practical-case/pc2',
],
},
{
type: 'category',
label: 'Platform Admin Guide',