Skip to content

Commit

Permalink
Merge pull request #74 from FogDong/fix-readme
Browse files Browse the repository at this point in the history
Feat: add example of multiple apps and fix read me
  • Loading branch information
FogDong authored Nov 1, 2022
2 parents 2c130ce + 6a5c9d7 commit fe82815
Show file tree
Hide file tree
Showing 9 changed files with 266 additions and 179 deletions.
110 changes: 18 additions & 92 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# KubeVela Workflow
<h1 align="center">KubeVela Workflow</h1>

[![Go Report Card](https://goreportcard.com/badge/github.com/kubevela/workflow)](https://goreportcard.com/report/github.com/kubevela/workflow)
[![codecov](https://codecov.io/gh/kubevela/workflow/branch/main/graph/badge.svg)](https://codecov.io/gh/kubevela/workflow)
[![LICENSE](https://img.shields.io/github/license/kubevela/workflow.svg?style=flat-square)](/LICENSE)
Expand Down Expand Up @@ -35,10 +36,12 @@ During the evolution of the [OAM](https://oam.dev/) and [KubeVela project](https

### As a standalone workflow engine

- Glue and orchestrate operations, such as restart application, scale up/down, read-notify processes.
- Orchestrate delivery process without day-2 management, just deploy. The workflow will not keep reconciliation, no garbage collection when workflow object deleted or updated. The most common use case is to initialize your infrastructure for some environment.
Unlike the workflow in the KubeVela Application, this workflow will only be executed once, and will **not keep reconciliation**, **no garbage collection** when the workflow object deleted or updated. You can use it for **one-time** operations like:

- Glue and orchestrate operations, such as control the deploy process of multiple resources(e.g. your Applications), scale up/down, read-notify processes, or the sequence between http requests.
- Orchestrate delivery process without day-2 management, just deploy. The most common use case is to initialize your infrastructure for some environment.

Please refer to the [installation](#installation) and [quick start](#quick-start) sections.
Please refer to the [installation](#installation) and [quick start](#quick-start) sections for more.

### As an SDK

Expand All @@ -50,14 +53,16 @@ You just need to initialize a workflow instance and generate all the task runner

### Install Workflow

You can install workflow with Helm:
#### Helm

```shell
helm repo add kubevela https://kubevela.github.io/charts
helm repo update
helm install --create-namespace -n vela-system vela-workflow kubevela/vela-workflow
```

#### KubeVela Addon

If you have installed KubeVela, you can install Workflow with the KubeVela Addon:

```shell
Expand All @@ -70,107 +75,28 @@ Please checkout: [Install Vela CLI](https://kubevela.io/docs/installation/kubern

### Install built-in steps in KubeVela(Optional)

Use `vela def apply <directory>` to install built-in steps in [KubeVela](https://github.com/kubevela/kubevela/tree/master/vela-templates/definitions/internal/workflowstep).
Use `vela def apply <directory>` to install built-in step definitions in [KubeVela](https://github.com/kubevela/kubevela/tree/master/vela-templates/definitions/internal/workflowstep) and [Workflow Addon](https://github.com/kubevela/catalog/tree/master/addons/vela-workflow/definitions).

> Note that if you installed Workflow using KubeVela Addon, then the definitions in the addon will be installed automatically.
Checkout this [doc](https://kubevela.io/docs/end-user/workflow/built-in-workflow-defs) for more details.

<h2 align="center">Quick Start</h2>

You can either run a WorkflowRun directly or from a Workflow Template.

> Note: You need to install the [notification step definition](https://github.com/kubevela/kubevela/blob/master/vela-templates/definitions/internal/workflowstep/notification.cue) and definitions in the [example directory](https://github.com/kubevela/workflow/tree/main/examples/definitions) first to run the example.
### Run a WorkflowRun directly

```yaml
apiVersion: core.oam.dev/v1alpha1
kind: WorkflowRun
metadata:
name: request-http
namespace: default
spec:
workflowSpec:
steps:
- name: request
type: request
properties:
url: https://api.github.com/repos/kubevela/workflow
outputs:
- name: stars
valueFrom: |
import "strconv"
"Current star count: " + strconv.FormatInt(response["stargazers_count"], 10)
- name: notification
type: notification
inputs:
- from: stars
parameterKey: slack.message.text
properties:
slack:
url:
value: <your slack url>
- name: failed-notification
type: notification
if: status.request.failed
properties:
slack:
url:
value: <your slack url>
message:
text: "Failed to request github"

```
Above workflow will send a request to the GitHub API and get the star count of the workflow repository as an output, then use the output as a message to send a notification to your Slack channel.
Please refer to the following examples:

Apply the WorkflowRun, you can get a message from Slack like:
![slack-success](./static/slack-success.png)
If you change the `url` to an invalid one, you will get a failed notification:

![slack-failed](./static/slack-fail.png)
- [Control the delivery process of multiple resources(e.g. your Applications)](./examples/multiple-apps)
- [Request a specified URL and then use the response as a message to notify](./examples/request-and-notify)

### Run a WorkflowRun from a Workflow Template

You can also create a Workflow Template and run it with a WorkflowRun with different context.

Workflow Template:

```yaml
apiVersion: core.oam.dev/v1alpha1
kind: Workflow
metadata:
name: deploy-template
namespace: default
steps:
- name: apply
type: apply-deployment
if: context.env == "dev"
properties:
image: nginx
- name: apply-test
type: apply-deployment
if: context.env == "test"
properties:
image: crccheck/hello-world
```

WorkflowRun:

```yaml
apiVersion: core.oam.dev/v1alpha1
kind: WorkflowRun
metadata:
name: deploy-run
namespace: default
spec:
context:
env: dev
workflowRef: deploy-template
```
Please refer to the following examples:

If you apply the WorkflowRun with `dev` in `context.env`, then you'll get a deployment with `nginx` image. If you change the `env` to `test`, you'll get a deployment with `crccheck/hello-world` image.
- [Run the Workflow Template with different context to control the process](./examples/run-with-template)

<h2 align="center">Features</h2>

Expand Down
45 changes: 0 additions & 45 deletions examples/definitions/apply-deployment.cue

This file was deleted.

42 changes: 0 additions & 42 deletions examples/definitions/request.cue

This file was deleted.

87 changes: 87 additions & 0 deletions examples/multiple-apps.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Control the delivery process of multiple applications

> Note: The example uses following definitions, please use `vela def apply -f <filename>` to install them first.
> - [Definition `read-app`](https://github.com/kubevela/catalog/blob/master/addons/vela-workflow/definitions/read-app.cue)
> - [Definition `apply-app`](https://github.com/kubevela/catalog/blob/master/addons/vela-workflow/definitions/apply-app.cue)
Apply the following workflow to control the delivery process of multiple applications:

```yaml
apiVersion: core.oam.dev/v1alpha1
kind: WorkflowRun
metadata:
name: apply-applications
namespace: default
annotations:
workflowrun.oam.dev/debug: "true"
spec:
workflowSpec:
steps:
- name: check-app-exist
type: read-app
properties:
name: webservice-app
- name: apply-app1
type: apply-app
if: status["check-app-exist"].message == "Application not found"
properties:
data:
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: webservice-app
spec:
components:
- name: express-server
type: webservice
properties:
image: crccheck/hello-world
ports:
- port: 8000
- name: suspend
type: suspend
timeout: 24h
- name: apply-app2
type: apply-app
properties:
ref:
name: my-app
key: application
type: configMap
---
apiVersion: v1
kind: ConfigMap
metadata:
name: my-app
namespace: default
data:
application: |
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: webservice-app2
spec:
components:
- name: express-server2
type: webservice
properties:
image: crccheck/hello-world
ports:
- port: 8000
```
Above workflow will first try to read the Application called `webservice-app` from the cluster, if the Application is not found, this step's status message will be `Application not found`. The second step will deploy the `webservice-app` Application if `webservice-app` is not exist in the cluster. After that, the `suspend` step will suspend the delivery process for manual approve.

```
$ kubectl get wr
NAME PHASE AGE
apply-applications suspending 2s
```
You can use `vela workflow resume` to resume this workflow, note that if the workflow has not been resumed in 24 hours, the workflow will failed of timeout:
```
vela workflow resume apply-applications
```
After the workflow is resumed, it will deploy an another Application from the data in ConfigMap with key `application`.
56 changes: 56 additions & 0 deletions examples/request-and-notify.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Use Workflow for request and notify

> Note: The example uses following definitions, please use `vela def apply -f <filename>` to install them first.
> - [Definition `request`](https://github.com/kubevela/catalog/blob/master/addons/vela-workflow/definitions/request.cue)
> - [Definition `notification`](https://github.com/kubevela/kubevela/blob/master/vela-templates/definitions/internal/workflowstep/notification.cue)
Apply the following workflow for request a specified URL first and then use the response as a message to your slack channel.

```yaml
apiVersion: core.oam.dev/v1alpha1
kind: WorkflowRun
metadata:
name: request-http
namespace: default
spec:
workflowSpec:
steps:
- name: request
type: request
properties:
url: https://api.github.com/repos/kubevela/workflow
outputs:
- name: stars
valueFrom: |
import "strconv"
"Current star count: " + strconv.FormatInt(response["stargazers_count"], 10)
- name: notification
type: notification
inputs:
- from: stars
parameterKey: slack.message.text
properties:
slack:
url:
value: <your slack url>
- name: failed-notification
type: notification
if: status.request.failed
properties:
slack:
url:
value: <your slack url>
message:
text: "Failed to request github"

```
Above workflow will send a request to the GitHub API and get the star count of the workflow repository as an output, then use the output as a message to send a notification to your Slack channel.
Apply the WorkflowRun, you can get a message from Slack like:
![slack-success](./static/slack-success.png)
If you change the `url` to an invalid one, you will get a failed notification:

![slack-failed](./static/slack-fail.png)
Loading

0 comments on commit fe82815

Please sign in to comment.