kubevela
/
kubevela.github.io
mirror of https://github.com/kubevela/kubevela.github.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update docs (#215)

This commit is contained in:
Jianbo Sun 2021-08-30 13:08:41 +08:00 committed by GitHub
parent 98a3255744
commit 3eaeb2dd09
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 501 additions and 507 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -5,6 +5,7 @@
/build
.Ulysses-Settings.plist
.Ulysses-Group.plist
# Generated files
.docusaurus

5
docs/end-user/binding-traits.md Normal file
View File

@ -0,0 +1,5 @@
---
title: Binding Traits
---
WIP

0
docs/case-studies/examples/app-stateful.yaml → docs/platform-engineers/cue/examples/app-stateful.yaml
View File

0
docs/case-studies/examples/my-stateful.cue → docs/platform-engineers/cue/examples/my-stateful.cue
View File

0
docs/case-studies/examples/my-stateful.yaml → docs/platform-engineers/cue/examples/my-stateful.yaml
View File

5
docs/platform-engineers/policy/custom-policy.md Normal file
View File

@ -0,0 +1,5 @@
---
title: Custom Policy
---
TBD

5
docs/platform-engineers/workflow/custom-workflow.md Normal file
View File

@ -0,0 +1,5 @@
---
title: Custom Workflow
---
TBD

357
i18n/zh/docusaurus-plugin-content-docs/current/case-studies/paas.md
View File

@ -1,360 +1,3 @@
---
title: 易用可扩展的 PaaS
---
以 Kubernetes 为核心的云原生技术大多是围绕基础设施向上为平台构建者提供服务的，其功能的多样性和灵活性决定了用户学习使用这些技术有很高的门槛。传统 PaaS 的做法是将复杂的 API 进行固定的封装，以达到降低使用复杂度的目的。但是云原生时代用户的需求不再一成不变，会频繁随着复杂的使用场景不断改变。
KubeVela 针对这种使用需求，为平台管理员提供了一个易用可扩展的 PaaS 引擎，可以随着用户需求变化动态扩展 PaaS 层的能力。使得你的 PaaS 平台可以适应各类用户和场景，满足公司业务长期发展的迭代诉求。
> 注意：此用户案例的学习对象为期望构建可扩展 PaaS 的平台管理员。开始之前请确保你已经了解了[OAM 模型][1]和[模块定义（X-Definition ）][2]的概念。
## 将 Kubernetes API 对象转化为自定义组件
KubeVela 使用 [CUE][3] 构建用户抽象，也就是将复杂的 Kubernetes API 遮挡，只暴露简单的参数，同时也围绕 CUE 提供了管理工具来[编辑和生成 KubeVela 的模块定义对象][4]。
下面我们以 Kubernetes 官方的 [StatefulSet 对象][5]为例，来具体看 KubeVela 是如何构建用户抽象的。我们将官方文档中 StatefulSet 的 YAML 例子保存在本地，并命名为 `my-stateful.yaml`
然后执行如下命令，生成一个名为 “my-stateful” 的 Component 模块定义，并输出到 “my-stateful.cue” 文件中：
vela def init my-stateful -t component --desc "My StatefulSet component." --template-yaml ./my-stateful.yaml -o my-stateful.cue
查看生成的 “my-stateful.cue” 文件：
$ cat my-stateful.cue
"my-stateful": {
annotations: {}
attributes: workload: definition: {
apiVersion: "<change me> apps/v1"
kind: "<change me> Deployment"
}
description: "My StatefulSet component."
labels: {}
type: "component"
}
template: {
output: {
apiVersion: "v1"
kind: "Service"
... // 省略一些非重要信息
}
outputs: web: {
apiVersion: "apps/v1"
kind: "StatefulSet"
... // 省略一些非重要信息
}
parameter: {}
}
下面我们来对这个自动生成的自定义组件做一些修改：
1. 根据 KubeVela [自定义组件的规则][6]，StatefulSet 官网的例子是由 `StatefulSet`和 `Service` 两个对象构成的一个复合组件，复合组件中，核心工作负载由 `template.output`字段表示，其他辅助对象用 `template.outputs`表示，所以我们将内容做一些调整，将自动生成的 output 和 outputs 中的全部调换。
2. 然后我们将核心工作负载的 apiVersion 和 kind 数据填写到标注为 `<change me>`的部分
修改后可以用 `vela def vet`做一下格式检查和校验。
$ vela def vet my-stateful.cue
Validation succeed.
经过两步改动后的文件如下：
$ cat my-stateful.cue
"my-stateful": {
annotations: {}
attributes: workload: definition: {
apiVersion: "apps/v1"
kind: "StatefulSet"
}
description: "My StatefulSet component."
labels: {}
type: "component"
}
template: {
output: {
apiVersion: "apps/v1"
kind: "StatefulSet"
metadata: name: "web"
spec: {
selector: matchLabels: app: "nginx"
replicas: 3
serviceName: "nginx"
template: {
metadata: labels: app: "nginx"
spec: {
containers: [{
name: "nginx"
ports: [{
name: "web"
containerPort: 80
}]
image: "k8s.gcr.io/nginx-slim:0.8"
volumeMounts: [{
name: "www"
mountPath: "/usr/share/nginx/html"
}]
}]
terminationGracePeriodSeconds: 10
}
}
volumeClaimTemplates: [{
metadata: name: "www"
spec: {
accessModes: ["ReadWriteOnce"]
resources: requests: storage: "1Gi"
storageClassName: "my-storage-class"
}
}]
}
}
outputs: web: {
apiVersion: "v1"
kind: "Service"
metadata: {
name: "nginx"
labels: app: "nginx"
}
spec: {
clusterIP: "None"
ports: [{
name: "web"
port: 80
}]
selector: app: "nginx"
}
}
parameter: {}
}
将该组件定义安装到 Kubernetes 集群中：
$ vela def apply my-stateful.cue
ComponentDefinition my-stateful created in namespace vela-system.
此时平台的最终用户已经可以通过 `vela components`命令看到有一个 `my-stateful`组件可以使用了。
$ vela components
NAME NAMESPACE WORKLOAD DESCRIPTION
...
my-stateful vela-system statefulsets.apps My StatefulSet component.
...
通过 KubeVela 的应用部署计划发布到集群中，就可以拉起我们刚刚定义的 StatefulSet 和 Service 对象。
cat <<EOF | kubectl apply -f -
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: website
spec:
components:
- name: my-component
type: my-stateful
EOF
## 为组件定义定制化参数
为了满足用户变化的需求，我们需要在最后的 `parameter` 里暴露一些参数，在 [CUE 基础入门文档][7]中你可以了解到参数相关的语法。在本例中，我们为用户暴露一下参数：
* 镜像名称，允许用户自定义镜像
* 实例名，允许用户自定义生成的 StatefulSet 对象和 Service 对象的实例名称
* 副本数，生成对象的副本数
... # 省略其他没有修改的字段
template: {
output: {
apiVersion: "apps/v1"
kind: "StatefulSet"
metadata: name: parameter.name
spec: {
selector: matchLabels: app: "nginx"
replicas: parameter.replicas
serviceName: "nginx"
template: {
metadata: labels: app: "nginx"
spec: {
containers: [{
image: parameter.image
... // 省略其他没有修改的字段
}]
}
}
... // 省略其他没有修改的字段
}
}
outputs: web: {
apiVersion: "v1"
kind: "Service"
metadata: {
name: "nginx"
labels: app: "nginx"
}
spec: {
... // 省略其他没有修改的字段
}
}
parameter: {
image: string
name: string
replicas: int
}
}
修改后同样使用 `vela def apply`安装到集群中：
$ vela def apply my-stateful.cue
ComponentDefinition my-stateful in namespace vela-system updated.
这个修改过程是实时生效的，用户立即可以看到系统中的 my-stateful 组件增加了新的参数。
$ vela show my-stateful
# Properties
+----------+-------------+--------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+----------+-------------+--------+----------+---------+
| name | | string | true | |
| replicas | | int | true | |
| image | | string | true | |
+----------+-------------+--------+----------+---------+
组件定义的修改并不会影响已经在运行的应用，当下次应用修改并重新部署时，新的组件定义就会生效。
最终用户就可以在应用中指定新增的这三个参数：
cat <<EOF | kubectl apply -f -
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: website
spec:
components:
- name: my-component
type: my-stateful
properties:
image: nginx:latest
replicas: 1
name: my-component
EOF
为了保证用户的应用使用参数能够正确运行，作为管理员，你也可以用 `vela dry-run` 等命令对你的模板进行[调试验证][8]。
## 使用上下文信息减少参数
在我们上面的例子中，properties 中的 name 和 Component 的 name 字段是相同的，此时我们可以在模板中使用携带了上下文信息的 `context`关键字，其中 `context.name` 就是运行时组件名称，此时 `parameter` 中的 name 参数就不再需要的。
... # 省略其他没有修改的字段
template: {
output: {
apiVersion: "apps/v1"
kind: "StatefulSet"
metadata: name: context.name
... // 省略其他没有修改的字段
}
parameter: {
image: string
replicas: int
}
}
KubeVela 内置了应用[所需的上下文信息][9]，你可以根据需要配置.
## 使用运维能力按需添加配置
对于用户的新需求，除了修改组件定义增加参数以外，你还可以使用运维能力，按需添加配置。一方面，KubeVela 已经内置了大量的通用运维能力，可以满足诸如：添加 label、annotation，注入环境变量、sidecar，添加 volume 等等的需求。另一方面，你可以像自定义组件一样，自定义[补丁型运维特征][10]，来满足更多的配置灵活组装的需求。
你可以使用 `vela traits` 查看，带 `*` 标记的 trait 均为通用 trait，能够对常见的 Kubernetes 资源对象做操作。
$ vela traits
NAME NAMESPACE APPLIES-TO CONFLICTS-WITH POD-DISRUPTIVE DESCRIPTION
annotations vela-system * true Add annotations on K8s pod for your workload which follows
the pod spec in path 'spec.template'.
configmap vela-system * true Create/Attach configmaps on K8s pod for your workload which
follows the pod spec in path 'spec.template'.
env vela-system * false add env on K8s pod for your workload which follows the pod
spec in path 'spec.template.'
hostalias vela-system * false Add host aliases on K8s pod for your workload which follows
the pod spec in path 'spec.template'.
init-container vela-system deployments.apps true add an init container and use shared volume with pod
labels vela-system * true Add labels on K8s pod for your workload which follows the
pod spec in path 'spec.template'.
lifecycle vela-system * true Add lifecycle hooks for the first container of K8s pod for
your workload which follows the pod spec in path
'spec.template'.
node-affinity vela-system * true affinity specify node affinity and toleration on K8s pod for
your workload which follows the pod spec in path
'spec.template'.
scaler vela-system * false Manually scale K8s pod for your workload which follows the
pod spec in path 'spec.template'.
sidecar vela-system * true Inject a sidecar container to K8s pod for your workload
which follows the pod spec in path 'spec.template'.
以 sidecar 为例，你可以查看 sidecar 的用法：
$ vela show sidecar
# Properties
+---------+-----------------------------------------+-----------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+---------+-----------------------------------------+-----------------------+----------+---------+
| name | Specify the name of sidecar container | string | true | |
| cmd | Specify the commands run in the sidecar | []string | false | |
| image | Specify the image of sidecar container | string | true | |
| volumes | Specify the shared volume path | [[]volumes](#volumes) | false | |
+---------+-----------------------------------------+-----------------------+----------+---------+
## volumes
+------+-------------+--------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+------+-------------+--------+----------+---------+
| path | | string | true | |
| name | | string | true | |
+------+-------------+--------+----------+---------+
直接使用 sidecar 注入一个容器，应用的描述如下：
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: website
spec:
components:
- name: my-component
type: my-stateful
properties:
image: nginx:latest
replicas: 1
name: my-component
traits:
- type: sidecar
properties:
name: my-sidecar
image: saravak/fluentd:elastic
部署运行该应用，就可以看到 StatefulSet 中已经部署运行了一个 fluentd 的 sidecar。
你也可以使用 `vela def` 获取 sidecar 的 CUE 源文件进行修改，增加参数等。
vela def get sidecar
运维能力的自定义与组件自定义类似，不再赘述，你可以阅读[运维能力自定义文档][11]了解更详细的功能。
## 总结
在本案例中，我们介绍了如何通过 KubeVela 强大而全面的抽象能力，来构建一个易用可扩展的 PaaS。 其核心是基于 CUE 随着用户的需求，不断动态增加配置能力，逐步暴露更多的功能和用法，以便降低用户整体的学习门槛，最终提升研发效率。
[1]: ../platform-engineers/oam/oam-model "OAM"
[2]: ../platform-engineers/oam/x-definition
[3]: ../platform-engineers/cue/basic
[4]: ../platform-engineers/cue/definition-edit
[5]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/
[6]: ../platform-engineers/components/custom-component#%E4%BA%A4%E4%BB%98%E4%B8%80%E4%B8%AA%E5%A4%8D%E5%90%88%E7%9A%84%E8%87%AA%E5%AE%9A%E4%B9%89%E7%BB%84%E4%BB%B6
[7]: ../platform-engineers/cue/basic#%E5%AE%9A%E4%B9%89%E4%B8%80%E4%B8%AA-cue-%E6%A8%A1%E6%9D%BF
[8]: ../platform-engineers/debug/dry-run
[9]: ../platform-engineers/oam/x-definition#%E6%A8%A1%E5%9D%97%E5%AE%9A%E4%B9%89%E8%BF%90%E8%A1%8C%E6%97%B6%E4%B8%8A%E4%B8%8B%E6%96%87
[10]: ../platform-engineers/traits/patch-trait
[11]: ../platform-engineers/traits/customize-trait

25
i18n/zh/docusaurus-plugin-content-docs/current/end-user/component-delivery.md
View File

@ -8,7 +8,7 @@ title: 组件交付
## 查看 KubeVela 的组件类型
我们通过 [KubeVela CLI](.,/../../getting-started/quick-install.mdx#3-安装-kubevela-cli) 来查看系统中可用组件类型：
我们通过 [KubeVela CLI][1] 来查看系统中可用组件类型：
```shell
$ vela components
@ -40,7 +40,7 @@ worker vela-system deployments.apps Describes long-run
- `alibaba-rds`：云资源之一，阿里云关系型数据库服务（RDS）
- `raw`：直接引用原生的 Kubernetes 资源对象的组件
下面让我们以几个典型的组件类型为例，介绍 KubeVela 组件交付的用法。如果你希望直接查看云资源的使用方式，请阅读[集成云资源](./cloud-services)。
下面让我们以几个典型的组件类型为例，介绍 KubeVela 组件交付的用法。如果你希望直接查看云资源的使用方式，请阅读[集成云资源][2]。
## 使用服务型组件(webservice)部署应用
@ -151,7 +151,7 @@ app-delivering-chart redis-comp helm running healthy 2021-08
我们也看到 app-delivering-chart APP 的 PHASE 为 running，同时 STATUS 为 healthy。
关于 Git 仓库和 OSS bucket 的使用示例，以及关于它们的详细配置项信息，请前往管理员手册里的[内置组件](../platform-engineers/components/build-in-component)查阅。
关于 Git 仓库和 OSS bucket 的使用示例，以及关于它们的详细配置项信息，请前往管理员手册里的[内置组件][3]查阅。
## 使用 Kustomize 组件部署应用
@ -194,17 +194,26 @@ bucket-app bucket-comp kustomize running healthy 2021-0
bucket-app APP 的 PHASE 为 running，同时 STATUS 为 healthy。应用部署成功！
关于 Git 仓库的使用示例，以及关于它们的详细配置项信息，请前往管理员手册里的[内置组件](../platform-engineers/components/build-in-component)查阅。
关于 Git 仓库的使用示例，以及关于它们的详细配置项信息，请前往管理员手册里的[内置组件][4]查阅。
## 使用云资源组件
云资源组件也是 KubeVela 支持的核心组件，云资源往往不会单独使用，如数据库、缓存等云资源，往往需要在创建之后将相关信息传递到其他组件使用，同时云资源涉及到不同云厂商，以及一些鉴权相关的准备工作，我们将在[集成云资源](./cloud-services)这个章节独立讲解。
云资源组件也是 KubeVela 支持的核心组件，云资源往往不会单独使用，如数据库、缓存等云资源，往往需要在创建之后将相关信息传递到其他组件使用，同时云资源涉及到不同云厂商，以及一些鉴权相关的准备工作，我们将在[集成云资源][5]这个章节独立讲解。
## 自定义组件
当以上 KubeVela 内置的开箱组件都无法满足需求的时候，不要担心，KubeVela 提供了强大了扩展能力，几乎可以对接任意类型的组件形态，你可以查看管理员手册里的[自定义组件](../platform-engineers/components/custom-component)学习使用 CUE 和 Kubernetes 扩展 KubeVela 的组件类型。
当以上 KubeVela 内置的开箱组件都无法满足需求的时候，不要担心，KubeVela 提供了强大了扩展能力，几乎可以对接任意类型的组件形态，你可以查看管理员手册里的[自定义组件][6]学习使用 CUE 和 Kubernetes 扩展 KubeVela 的组件类型。
## 下一步
- 访问[集成云资源](./cloud-services)文档，掌握不同类型不同厂商的云资源集成方式
- 访问[绑定运维特征][./binding-traits]文档，掌握如何给组件绑定你需要的运维动作和策略
- 访问[集成云资源][7]文档，掌握不同类型不同厂商的云资源集成方式
- 访问[绑定运维特征][8]文档，掌握如何给组件绑定你需要的运维动作和策略
[1]: ../../getting-started/quick-install#3-%E5%AE%89%E8%A3%85-kubevela-cli
[2]: ./cloud-services
[3]: ../platform-engineers/components/build-in-component
[4]: ../platform-engineers/components/build-in-component
[5]: ./cloud-services
[6]: ../platform-engineers/components/custom-component
[7]: ./cloud-services
[8]: ./binding-traits

451
i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/cue/advanced.md
View File

@ -1,6 +1,453 @@
---
title: 开发与调试
title: 交付完整模块
---
TBD
现在你已经了解了[OAM 模型][1]和[模块定义（X-Definition ）][2]的概念，本节将介绍如何使用 CUE 交付完整的模块化功能，使得你的平台可以随着用户需求变化动态扩展功能，适应各类用户和场景，满足公司业务长期发展的迭代诉求。
## 将 Kubernetes API 对象转化为自定义组件
KubeVela 使用 [CUE][3] 配置语言作为管理用户模块化交付的核心，同时也围绕 CUE 提供了管理工具来[编辑和生成 KubeVela 的模块定义对象][4]。
下面我们以 Kubernetes 官方的 [StatefulSet 对象][5]为例，来具体看如何使用 KubeVela 构建自定义的模块化功能并提供能力。
我们将官方文档中 StatefulSet 的 YAML 例子保存在本地，并命名为 `my-stateful.yaml`，
然后执行如下命令，生成一个名为 “my-stateful” 的 Component 模块定义，并输出到 “my-stateful.cue” 文件中：
vela def init my-stateful -t component --desc "My StatefulSet component." --template-yaml ./my-stateful.yaml -o my-stateful.cue
查看生成的 “my-stateful.cue” 文件：
$ cat my-stateful.cue
"my-stateful": {
annotations: {}
attributes: workload: definition: {
apiVersion: "<change me> apps/v1"
kind: "<change me> Deployment"
}
description: "My StatefulSet component."
labels: {}
type: "component"
}
template: {
output: {
apiVersion: "v1"
kind: "Service"
... // 省略一些非重要信息
}
outputs: web: {
apiVersion: "apps/v1"
kind: "StatefulSet"
... // 省略一些非重要信息
}
parameter: {}
}
下面我们来对这个自动生成的自定义组件做一些微调：
1. 根据 KubeVela [自定义组件的规则][6]，StatefulSet 官网的例子是由 `StatefulSet`和 `Service` 两个对象构成的一个复合组件，复合组件中，核心工作负载由 `template.output`字段表示，其他辅助对象用 `template.outputs`表示，所以我们将内容做一些调整，将自动生成的 output 和 outputs 中的全部调换。
2. 然后我们将核心工作负载的 apiVersion 和 kind 数据填写到标注为 `<change me>`的部分
修改后可以用 `vela def vet`做一下格式检查和校验。
$ vela def vet my-stateful.cue
Validation succeed.
经过两步改动后的文件如下：
$ cat my-stateful.cue
"my-stateful": {
annotations: {}
attributes: workload: definition: {
apiVersion: "apps/v1"
kind: "StatefulSet"
}
description: "My StatefulSet component."
labels: {}
type: "component"
}
template: {
output: {
apiVersion: "apps/v1"
kind: "StatefulSet"
metadata: name: "web"
spec: {
selector: matchLabels: app: "nginx"
replicas: 3
serviceName: "nginx"
template: {
metadata: labels: app: "nginx"
spec: {
containers: [{
name: "nginx"
ports: [{
name: "web"
containerPort: 80
}]
image: "k8s.gcr.io/nginx-slim:0.8"
volumeMounts: [{
name: "www"
mountPath: "/usr/share/nginx/html"
}]
}]
terminationGracePeriodSeconds: 10
}
}
volumeClaimTemplates: [{
metadata: name: "www"
spec: {
accessModes: ["ReadWriteOnce"]
resources: requests: storage: "1Gi"
storageClassName: "my-storage-class"
}
}]
}
}
outputs: web: {
apiVersion: "v1"
kind: "Service"
metadata: {
name: "nginx"
labels: app: "nginx"
}
spec: {
clusterIP: "None"
ports: [{
name: "web"
port: 80
}]
selector: app: "nginx"
}
}
parameter: {}
}
将该组件定义安装到 Kubernetes 集群中：
$ vela def apply my-stateful.cue
ComponentDefinition my-stateful created in namespace vela-system.
此时平台的最终用户已经可以通过 `vela components`命令看到有一个 `my-stateful`组件可以使用了。
$ vela components
NAME NAMESPACE WORKLOAD DESCRIPTION
...
my-stateful vela-system statefulsets.apps My StatefulSet component.
...
通过 KubeVela 的应用部署计划发布到集群中，就可以拉起我们刚刚定义的 StatefulSet 和 Service 对象。
cat <<EOF | kubectl apply -f -
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: website
spec:
components:
- name: my-component
type: my-stateful
EOF
## 为组件定义定制化参数
为了满足用户变化的需求，我们需要在最后的 `parameter` 里暴露一些参数，在 [CUE 基础入门文档][7]中你可以了解到参数相关的语法。在本例中，我们为用户暴露一下参数：
* 镜像名称，允许用户自定义镜像
* 实例名，允许用户自定义生成的 StatefulSet 对象和 Service 对象的实例名称
* 副本数，生成对象的副本数
... # 省略其他没有修改的字段
template: {
output: {
apiVersion: "apps/v1"
kind: "StatefulSet"
metadata: name: parameter.name
spec: {
selector: matchLabels: app: "nginx"
replicas: parameter.replicas
serviceName: "nginx"
template: {
metadata: labels: app: "nginx"
spec: {
containers: [{
image: parameter.image
... // 省略其他没有修改的字段
}]
}
}
... // 省略其他没有修改的字段
}
}
outputs: web: {
apiVersion: "v1"
kind: "Service"
metadata: {
name: "nginx"
labels: app: "nginx"
}
spec: {
... // 省略其他没有修改的字段
}
}
parameter: {
image: string
name: string
replicas: int
}
}
修改后同样使用 `vela def apply`安装到集群中：
$ vela def apply my-stateful.cue
ComponentDefinition my-stateful in namespace vela-system updated.
这个修改过程是实时生效的，用户立即可以看到系统中的 my-stateful 组件增加了新的参数。
$ vela show my-stateful
# Properties
+----------+-------------+--------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+----------+-------------+--------+----------+---------+
| name | | string | true | |
| replicas | | int | true | |
| image | | string | true | |
+----------+-------------+--------+----------+---------+
组件定义的修改并不会影响已经在运行的应用，当下次应用修改并重新部署时，新的组件定义就会生效。
最终用户就可以在应用中指定新增的这三个参数：
```
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: website
spec:
components:
- name: my-component
type: my-stateful
properties:
image: nginx:latest
replicas: 1
name: my-component
```
将文件保存在本地并命名为 `app-stateful.yaml`，执行 `kubectl apply -f app-stateful.yaml`更新应用，你可以看到 StatefulSet 对象的名称、镜像和实例数均已更新。
## 调试模块化功能的正确性
为了保证用户的应用使用参数能够正确运行，你也可以用 `vela dry-run` 命令对你的模板进行试运行验证。
```shell
vela dry-run -f app-stateful.yaml
```
查看输出，你就可以对比生成的对象和你实际期望的对象是否一致。甚至可以直接把这个 YAML 执行到 Kubernetes 集群中使用看运行的结果做验证。
<details>
```
# Application(website) -- Component(my-component)
---
apiVersion: v1
kind: Service
metadata:
labels:
app: nginx
app.oam.dev/appRevision: ""
app.oam.dev/component: my-component
app.oam.dev/name: website
workload.oam.dev/type: my-stateful
name: nginx
namespace: default
spec:
clusterIP: None
ports:
- name: web
port: 80
selector:
app: nginx
template:
spec:
containers:
- image: saravak/fluentd:elastic
name: my-sidecar
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
labels:
app.oam.dev/appRevision: ""
app.oam.dev/component: my-component
app.oam.dev/name: website
trait.oam.dev/resource: web
trait.oam.dev/type: AuxiliaryWorkload
name: web
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: nginx
serviceName: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- image: k8s.gcr.io/nginx-slim:0.8
name: nginx
ports:
- containerPort: 80
name: web
volumeMounts:
- mountPath: /usr/share/nginx/html
name: www
terminationGracePeriodSeconds: 10
volumeClaimTemplates:
- metadata:
name: www
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
storageClassName: my-storage-class
```
</details>
你还可以通过 `vela dry-run -h` 来查看更多可用的功能参数。
## 使用上下文信息减少参数
在我们上面的 Application 例子中，properties 中的 name 和 Component 的 name 字段是相同的，此时我们可以在模板中使用携带了上下文信息的 `context`关键字，其中 `context.name` 就是运行时组件名称，此时 `parameter` 中的 name 参数就不再需要的。
... # 省略其他没有修改的字段
template: {
output: {
apiVersion: "apps/v1"
kind: "StatefulSet"
metadata: name: context.name
... // 省略其他没有修改的字段
}
parameter: {
image: string
replicas: int
}
}
KubeVela 内置了应用[所需的上下文信息][9]，你可以根据需要配置.
## 使用运维能力按需添加配置
对于用户的新需求，除了修改组件定义增加参数以外，你还可以使用运维能力，按需添加配置。一方面，KubeVela 已经内置了大量的通用运维能力，可以满足诸如：添加 label、annotation，注入环境变量、sidecar，添加 volume 等等的需求。另一方面，你可以像自定义组件一样，自定义[补丁型运维特征][10]，来满足更多的配置灵活组装的需求。
你可以使用 `vela traits` 查看，带 `*` 标记的 trait 均为通用 trait，能够对常见的 Kubernetes 资源对象做操作。
$ vela traits
NAME NAMESPACE APPLIES-TO CONFLICTS-WITH POD-DISRUPTIVE DESCRIPTION
annotations vela-system * true Add annotations on K8s pod for your workload which follows
the pod spec in path 'spec.template'.
configmap vela-system * true Create/Attach configmaps on K8s pod for your workload which
follows the pod spec in path 'spec.template'.
env vela-system * false add env on K8s pod for your workload which follows the pod
spec in path 'spec.template.'
hostalias vela-system * false Add host aliases on K8s pod for your workload which follows
the pod spec in path 'spec.template'.
labels vela-system * true Add labels on K8s pod for your workload which follows the
pod spec in path 'spec.template'.
lifecycle vela-system * true Add lifecycle hooks for the first container of K8s pod for
your workload which follows the pod spec in path
'spec.template'.
node-affinity vela-system * true affinity specify node affinity and toleration on K8s pod for
your workload which follows the pod spec in path
'spec.template'.
scaler vela-system * false Manually scale K8s pod for your workload which follows the
pod spec in path 'spec.template'.
sidecar vela-system * true Inject a sidecar container to K8s pod for your workload
which follows the pod spec in path 'spec.template'.
以 sidecar 为例，你可以查看 sidecar 的用法：
$ vela show sidecar
# Properties
+---------+-----------------------------------------+-----------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+---------+-----------------------------------------+-----------------------+----------+---------+
| name | Specify the name of sidecar container | string | true | |
| cmd | Specify the commands run in the sidecar | []string | false | |
| image | Specify the image of sidecar container | string | true | |
| volumes | Specify the shared volume path | [[]volumes](#volumes) | false | |
+---------+-----------------------------------------+-----------------------+----------+---------+
## volumes
+------+-------------+--------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+------+-------------+--------+----------+---------+
| path | | string | true | |
| name | | string | true | |
+------+-------------+--------+----------+---------+
直接使用 sidecar 注入一个容器，应用的描述如下：
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: website
spec:
components:
- name: my-component
type: my-stateful
properties:
image: nginx:latest
replicas: 1
name: my-component
traits:
- type: sidecar
properties:
name: my-sidecar
image: saravak/fluentd:elastic
部署运行该应用，就可以看到 StatefulSet 中已经部署运行了一个 fluentd 的 sidecar。
你也可以使用 `vela def` 获取 sidecar 的 CUE 源文件进行修改，增加参数等。
vela def get sidecar
运维能力的自定义与组件自定义类似，不再赘述，你可以阅读[运维能力自定义文档][11]了解更详细的功能。
## 总结
本节介绍了如何通过 CUE 交付完整的模块化能力，其核心是可以随着用户的需求，不断动态增加配置能力，逐步暴露更多的功能和用法，以便降低用户整体的学习门槛，最终提升研发效率。
KubeVela 背后提供的开箱即用的能力，包括组件、运维功能、策略以及工作流，均是通过同样的方式提供了可插拔、可修改的能力。
## 下一步
* 了解更多[自定义组件](../components/custom-component)的功能。
* 了解更多[自定义运维能力](../traits/customize-trait)的功能。
* 了解[自定义策略](../policy/custom-policy)背后的功能。
* 了解[自定义工作流](../workflow/custom-workflow)背后的功能。
[1]: ../oam/oam-model
[2]: ../oam/x-definition
[3]: ../cue/basic
[4]: ../cue/definition-edit
[5]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/
[6]: ../components/custom-component#%E4%BA%A4%E4%BB%98%E4%B8%80%E4%B8%AA%E5%A4%8D%E5%90%88%E7%9A%84%E8%87%AA%E5%AE%9A%E4%B9%89%E7%BB%84%E4%BB%B6
[7]: ../cue/basic#%E5%AE%9A%E4%B9%89%E4%B8%80%E4%B8%AA-cue-%E6%A8%A1%E6%9D%BF
[9]: ../oam/x-definition#%E6%A8%A1%E5%9D%97%E5%AE%9A%E4%B9%89%E8%BF%90%E8%A1%8C%E6%97%B6%E4%B8%8A%E4%B8%8B%E6%96%87
[10]: ../traits/patch-trait
[11]: ../traits/customize-trait

2
i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/cue/basic.md
View File

@ -561,4 +561,4 @@ parameter: {
## 下一步
统一使用 CUE 来[管理自定义 OAM 模块](./definition-edit)。
* 了解如何统一使用 CUE 来[管理自定义 OAM 模块](./definition-edit)。

6
i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/cue/definition-edit.md
View File

@ -1,5 +1,5 @@
---
title: 管理 X-Definition
title: 编辑管理模块定义
---
在 KubeVela CLI (>= v1.1.0) 工具中，`vela def` 命令组为开发者提供了一系列便捷的 X-Definition 编写工具，使得 Definition 的编写将全部在 CUE 文件中进行，避免将 Template CUE 与 Kubernetes 的 YAML 格式进行混合，方便进行格式化与校验。
@ -240,3 +240,7 @@ ComponentDefinition my-comp: My component.
[yes|no] > yes
ComponentDefinition my-comp in namespace my-namespace deleted.
```
## 下一步
* 了解如何使用 CUE 和 KubeVela 工具[交付完整的模块能力](./advanced)。

135
i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/debug/dry-run.md
View File

@ -1,135 +0,0 @@
---
title: 本地试运行
---
如果你是一个 DevOps 用户或者运维管理员，并且对 Kubernetes 有所了解，为了保证一个应用部署计划在 Kubernetes 运行时集群的表现符合期望，在开发调试阶段，你也可以通过下面的试运行功能提前确认这个部署计划背后的逻辑是否正确。
KubeVela 提供了本地试运行（Dry-run）的功能，来满足你的这个需求。
### 如何使用
我们将以一个应用部署计划的示例，来进行讲解。
首先编写如下的 YAML 文件：
```yaml
# app.yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: vela-app
spec:
components:
- name: express-server
type: webservice
properties:
image: crccheck/hello-world
port: 8000
traits:
- type: ingress
properties:
domain: testsvc.example.com
http:
"/": 8000
```
可以看到，我们的期望是交付一个 Web Service 的组件，使用来自 `crccheck/hello-world` 的镜像，并最终提供一个可供对外访问的网关，地址域名为 `testsvc.example.com`，端口号 8000。
然后打开本地试运行模式，使用如下命令：
```shell
kubectl vela dry-run -f app.yaml
```
```console
---
# Application(vela-app) -- Comopnent(express-server)
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.oam.dev/appRevision: ""
app.oam.dev/component: express-server
app.oam.dev/name: vela-app
workload.oam.dev/type: webservice
spec:
selector:
matchLabels:
app.oam.dev/component: express-server
template:
metadata:
labels:
app.oam.dev/component: express-server
spec:
containers:
- image: crccheck/hello-world
name: express-server
ports:
- containerPort: 8000
---
apiVersion: v1
kind: Service
metadata:
labels:
app.oam.dev/appRevision: ""
app.oam.dev/component: express-server
app.oam.dev/name: vela-app
trait.oam.dev/resource: service
trait.oam.dev/type: ingress
name: express-server
spec:
ports:
- port: 8000
targetPort: 8000
selector:
app.oam.dev/component: express-server
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
labels:
app.oam.dev/appRevision: ""
app.oam.dev/component: express-server
app.oam.dev/name: vela-app
trait.oam.dev/resource: ingress
trait.oam.dev/type: ingress
name: express-server
spec:
rules:
- host: testsvc.example.com
http:
paths:
- backend:
serviceName: express-server
servicePort: 8000
path: /
---
```
查看本地试运行模式给出的信息，我们可以进行确认：
1. Kubernetes 集群内部 Service 和我们期望的 `kind: Deployment` 部署，在相关的镜像地址、域名端口上，是否能匹配。
2. 最终对外的 Ingress 网关，与 Kubernetes 集群内部的 `Service`，在相关的镜像地址、域名端口上，是否能匹配。
在完成上述信息确认之后，我们就能进行后续的开发调试步骤了。
最后，你还可以通过 `kubectl vela dry-run -h` 来查看更多可用的本地试运行模式：
```
Usage:
vela dry-run
Examples:
kubectl vela dry-run
Flags:
-d, --definition string specify a definition file or directory, it will only be used in dry-run rather than applied to K8s cluster
-f, --file string application file name (default "./app.yaml")
-h, --help help for dry-run
-n, --namespace string specify namespace of the definition file, by default is default namespace (default "default")
```

5
i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/policy/custom-policy.md Normal file
View File

@ -0,0 +1,5 @@
---
title: 自定义策略
---
TBD

5
i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/workflow/custom-workflow.md Normal file
View File

@ -0,0 +1,5 @@
---
title: 自定义工作流
---
TBD

6
sidebars.js
View File

@ -33,7 +33,7 @@ module.exports = {
// 'end-user/components/helm',
// 'end-user/components/kustomize',
// 'end-user/components/cue',
// 'end-user/components/cloud-services', 先隐藏，需要等用户侧的云服务支持 terraform 原生的 HCL
// 'end-user/components/cloud-services', 先隐藏，需要等用户侧的云服务支持 terraform 原生的 HCL
// {
// 'Cloud Services': [
// {
@ -105,7 +105,7 @@ module.exports = {
'Learning CUE': [
'platform-engineers/cue/basic',
'platform-engineers/cue/definition-edit',
// 'platform-engineers/cue/advanced', 暂时隐藏，来不及随 1.1 发布，随后补充
'platform-engineers/cue/advanced',
]
},
{
@ -159,7 +159,7 @@ module.exports = {
label: 'Case Studies',
collapsed: false,
items: [
'case-studies/paas',
// 'case-studies/paas',
// 'case-studies/workflow-edge-computing', // 待完成
// 'case-studies/li-auto-inc', 暂时下掉，应该改写成一个 10 - 15 分钟体验的产品 lab 例子
// 'case-studies/workflow-with-ocm',