Feat(workflow): add workflow introduction doc (#216)
* Feat(workflow): add workflow introduction doc * Fix: delete the useless paragraph
This commit is contained in:
Tianxin Dong
GitHub
parent
304462daf6
commit
5d0cdb0ffb
|
|
@ -0,0 +1,148 @@
|
|||
---
|
||||
title: Workflow
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
`Workflow` allows you to customize steps in `Application`, glue together additional delivery processes and specify arbitrary delivery environments. In short, `Workflow` provides customized control flow and flexibility based on the original delivery model of Kubernetes(Apply). For example, `Workflow` can be used to implement complex operations such as pause, manual approval, waiting status, data flow, multi-environment gray release, A/B testing, etc.
|
||||
|
||||
`Workflow` is a further exploration and best practice based on OAM model in KubeVela, it obeys the modular concept and reusable characteristics of OAM. Each workflow module is a "super glue" that can combine your arbitrary tools and processes. In modern complex cloud native application delivery environment, you can completely describe all delivery processes through a declarative configuration, ensuring the stability and convenience of the delivery process.
|
||||
|
||||
## Using workflow
|
||||
|
||||
`Workflow` consists of steps, you can either use KubeVela's [built-in workflow steps], or write their own `WorkflowStepDefinition` to complete the operation.
|
||||
|
||||
We can use `vela def` to define workflow steps by writing `Cue templates`. Let's write an `Application` that apply a Tomcat using Helm chart and automatically send message to Slack when the Tomcat is running.
|
||||
|
||||
### Workflow Steps
|
||||
|
||||
KubeVela provides several CUE actions for writing workflow steps. These actions are provided by the `vela/op` package.
|
||||
|
||||
| Action | Description | Parameter |
|
||||
| :---: | :--: | :-- |
|
||||
| ApplyApplication | Apply all the resources in Application. | - |
|
||||
| Read | Read resources in Kubernetes cluster. | value: the resource metadata to be get. And after successful execution, `value` will be updated with resource definition in cluster.<br /> err: if an error occurs, the `err` will contain the error message. |
|
||||
| ConditionalWait | The workflow step will be blocked until the condition is met. | continue: The workflow step will be blocked until the value becomes `true`. |
|
||||
| ... | ... | ... |
|
||||
|
||||
> For all the workflow actions, please refer to [Cue Actions](./cue-actions)
|
||||
|
||||
We need two `WorkflowStepDefinitions` to complete the Application：
|
||||
|
||||
1. Apply Tomcat and wait till it's status become running. We need to write a custom workflow step for it.
|
||||
2. Send Slack notifications, we can use the built-in [webhook-notification] step for it.
|
||||
|
||||
#### Step: Apply Tomcat
|
||||
|
||||
First, use `vela def init` to generate a `WorkflowStepDefinition` template：
|
||||
|
||||
```shell
|
||||
vela def init my-helm -t workflow-step --desc "Apply helm charts and wait till it's running." -o my-helm.cue
|
||||
```
|
||||
|
||||
The result is as follows：
|
||||
```shell
|
||||
$ cat my-helm.cue
|
||||
|
||||
"my-helm": {
|
||||
annotations: {}
|
||||
attributes: {}
|
||||
description: "Apply helm charts and wait till it's running."
|
||||
labels: {}
|
||||
type: "workflow-step"
|
||||
}
|
||||
|
||||
template: {
|
||||
}
|
||||
```
|
||||
|
||||
Import `vela/op` and complete the Cue code in `template`:
|
||||
|
||||
```
|
||||
import (
|
||||
"vela/op"
|
||||
)
|
||||
|
||||
"my-helm": {
|
||||
annotations: {}
|
||||
attributes: {}
|
||||
description: "Apply helm charts and wait till it's running."
|
||||
labels: {}
|
||||
type: "workflow-step"
|
||||
}
|
||||
|
||||
template: {
|
||||
// Apply all the resources in Application
|
||||
apply: op.#ApplyApplication & {}
|
||||
|
||||
resource: op.#Read & {
|
||||
value: {
|
||||
kind: "Deployment"
|
||||
apiVersion: "apps/v1"
|
||||
metadata: {
|
||||
name: "tomcat"
|
||||
// we can use context to get any metadata in Application
|
||||
namespace: context.namespace
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
workload: resource.value
|
||||
// wait till it's ready
|
||||
wait: op.#ConditionalWait & {
|
||||
continue: workload.status.readyReplicas == workload.status.replicas && workload.status.observedGeneration == workload.metadata.generation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Apply it to the cluster：
|
||||
|
||||
```shell
|
||||
$ vela def apply my-helm.cue
|
||||
|
||||
WorkflowStepDefinition my-helm in namespace vela-system updated.
|
||||
```
|
||||
|
||||
#### Step: Send Slack notifications
|
||||
|
||||
Use the built-in step, [webhook-notification].
|
||||
|
||||
### Apply the Application
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: first-vela-workflow
|
||||
namespace: default
|
||||
spec:
|
||||
components:
|
||||
- name: tomcat
|
||||
type: helm
|
||||
properties:
|
||||
repoType: helm
|
||||
repoUrl: https://charts.bitnami.com/bitnami
|
||||
chart: tomcat
|
||||
version: "9.2.20"
|
||||
workflow:
|
||||
steps:
|
||||
- name: tomcat
|
||||
# specify the step type
|
||||
type: my-helm
|
||||
outputs:
|
||||
- name: msg
|
||||
# export the deployment status in my-helm
|
||||
exportKey: resource.value.status.conditions[0].message
|
||||
- name: send-message
|
||||
type: webhook-notification
|
||||
inputs:
|
||||
- from: msg
|
||||
# use the output value in the previous step and pass it into the properties slack.message.text
|
||||
parameterKey: slack.message.text
|
||||
properties:
|
||||
slack:
|
||||
# the address of your slack webhook, please refer to: https://api.slack.com/messaging/webhooks
|
||||
url: slack url
|
||||
```
|
||||
|
||||
Apply the Application to the cluster and you can see that all resources have been successfully applied and Slack has received the messages of the Deployment status.
|
||||
|
|
@ -0,0 +1,148 @@
|
|||
---
|
||||
title: 工作流
|
||||
---
|
||||
|
||||
## 总览
|
||||
|
||||
KubeVela 的工作流机制允许你自定义应用部署计划中的步骤，粘合额外的交付流程，指定任意的交付环境。简而言之，工作流提供了定制化的控制逻辑，在原有 Kubernetes 模式交付资源（Apply）的基础上，提供了面向过程的灵活性。比如说，使用工作流实现暂停、人工验证、状态等待、数据流传递、多环境灰度、A/B 测试等复杂操作。
|
||||
|
||||
工作流是 KubeVela 实践过程中基于 OAM 模型的进一步探索和最佳实践，充分遵守 OAM 的模块化理念和可复用特性。每一个工作流模块都是一个“超级粘合剂”，可以将你任意的工具和流程都组合起来。使得你在现代复杂云原生应用交付环境中，可以通过一份申明式的配置，完整的描述所有的交付流程，保证交付过程的稳定性和便利性。
|
||||
|
||||
## 使用工作流
|
||||
|
||||
工作流由步骤组成，你既可以使用 KubeVela 提供的 [内置工作流步骤] 来便利地完成操作，也可以自己来编写 `WorkflowStepDefinition` 来达到想要的效果。
|
||||
|
||||
我们可以使用 `vela def` 通过编写 `Cue template` 来定义工作流步骤。下面我们来完成这个场景：使用 Helm 部署一个 Tomcat，并在部署完成后自动向 Slack 发送消息通知。
|
||||
|
||||
### 编写工作流步骤
|
||||
|
||||
KubeVela 提供了一些 CUE 操作类型用于编写工作流步骤。这些操作均由 `vela/op` 包提供。
|
||||
|
||||
| 操作名 | 说明 | 参数 |
|
||||
| :---: | :--: | :-- |
|
||||
| ApplyApplication | 部署应用中的所有资源 | - |
|
||||
| Read | 读取 Kubernetes 集群中的资源。 | value: 描述需要被读取资源的元数据，比如 kind、name 等，操作完成后，集群中资源的数据会被填充到 `value` 上。<br /> err: 如果读取操作发生错误，这里会以字符串的方式指示错误信息。 |
|
||||
| ConditionalWait | 会让 Workflow Step 处于等待状态，直到条件被满足。 | continue: 当该字段为 true 时，Workflow Step 才会恢复继续执行。 |
|
||||
| ... | ... | ... |
|
||||
|
||||
> 所有的操作类型可参考 [Cue Actions](./cue-actions)
|
||||
|
||||
为了完成这个场景，我们需要两个 `WorkflowStepDefinition`：
|
||||
|
||||
1. 部署 Tomcat，并且等待 Deployment 的状态变为 running，这一步需要自定义工作流步骤来实现。
|
||||
2. 发送 Slack 通知，这一步可以使用 KubeVela 内置的 [webhook-notification] 步骤来实现。
|
||||
|
||||
#### 部署 Tomcat 步骤
|
||||
|
||||
首先，通过 `vela def init` 来生成一个 `WorkflowStepDefinition` 模板：
|
||||
|
||||
```shell
|
||||
vela def init my-helm -t workflow-step --desc "Apply helm charts and wait till it's running." -o my-helm.cue
|
||||
```
|
||||
|
||||
得到如下结果：
|
||||
```shell
|
||||
$ cat my-helm.cue
|
||||
|
||||
"my-helm": {
|
||||
annotations: {}
|
||||
attributes: {}
|
||||
description: "Apply helm charts and wait till it's running."
|
||||
labels: {}
|
||||
type: "workflow-step"
|
||||
}
|
||||
|
||||
template: {
|
||||
}
|
||||
```
|
||||
|
||||
引用 `vela/op` 包，并将 Cue 代码补充到 `template` 中：
|
||||
|
||||
```
|
||||
import (
|
||||
"vela/op"
|
||||
)
|
||||
|
||||
"my-helm": {
|
||||
annotations: {}
|
||||
attributes: {}
|
||||
description: "Apply helm charts and wait till it's running."
|
||||
labels: {}
|
||||
type: "workflow-step"
|
||||
}
|
||||
|
||||
template: {
|
||||
// 部署应用中的所有资源
|
||||
apply: op.#ApplyApplication & {}
|
||||
|
||||
resource: op.#Read & {
|
||||
value: {
|
||||
kind: "Deployment"
|
||||
apiVersion: "apps/v1"
|
||||
metadata: {
|
||||
name: "tomcat"
|
||||
// 可以使用 context 来获取该 Application 的任意元信息
|
||||
namespace: context.namespace
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
workload: resource.value
|
||||
// 等待 helm 的 deployment 可用
|
||||
wait: op.#ConditionalWait & {
|
||||
continue: workload.status.readyReplicas == workload.status.replicas && workload.status.observedGeneration == workload.metadata.generation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
部署到集群中：
|
||||
|
||||
```shell
|
||||
$ vela def apply my-helm.cue
|
||||
|
||||
WorkflowStepDefinition my-helm in namespace vela-system updated.
|
||||
```
|
||||
|
||||
#### 发送 Slack 通知步骤
|
||||
|
||||
直接使用内置的 [webhook-notification] 步骤。
|
||||
|
||||
### 编写应用
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: first-vela-workflow
|
||||
namespace: default
|
||||
spec:
|
||||
components:
|
||||
- name: tomcat
|
||||
type: helm
|
||||
properties:
|
||||
repoType: helm
|
||||
repoUrl: https://charts.bitnami.com/bitnami
|
||||
chart: tomcat
|
||||
version: "9.2.20"
|
||||
workflow:
|
||||
steps:
|
||||
- name: tomcat
|
||||
# 指定步骤类型
|
||||
type: my-helm
|
||||
outputs:
|
||||
- name: msg
|
||||
# 将 my-helm 中读取到的 deployment status 作为信息导出
|
||||
exportKey: resource.value.status.conditions[0].message
|
||||
- name: send-message
|
||||
type: webhook-notification
|
||||
inputs:
|
||||
- from: msg
|
||||
# 引用上一步中 outputs 中的值，并传入到 properties 的 slack.message.text 中作为输入
|
||||
parameterKey: slack.message.text
|
||||
properties:
|
||||
slack:
|
||||
# 你的 slack webhook 地址，请参考：https://api.slack.com/messaging/webhooks
|
||||
url: slack url
|
||||
```
|
||||
|
||||
将该应用部署到集群中，可以看到所有的资源都已被成功部署，且 Slack 中收到了对应的通知，通知内容为该 Deployment 的状态信息。
|
||||
Loading…
Reference in New Issue