workflow

KubeVela Workflow

Table of Contents

• Why use KubeVela Workflow?
• How can KubeVela Workflow be used?
• Installation
• Quick Start
• Features
• How to write custom steps?
• Contributing

Why use KubeVela Workflow

🌬️ Lightweight Workflow Engine: KubeVela Workflow won't create a pod or job for process control. Instead, everything can be done in steps and there will be no redundant resource consumption.

✨ Flexible, Extensible and Programmable: All the steps are based on the CUE language, which means if you want to customize a new step, you just need to write CUE codes and no need to compile or build anything, KubeVela Workflow will evaluate these codes.

💪 Rich built-in capabilities: You can control the process with conditional judgement, inputs/outputs, timeout, etc. You can also use the built-in steps to do some common tasks, such as deploy resources, suspend, notification, step-group and more!

🔐 Safe execution with schema checksum checking: Every step will be checked with the schema, which means you can't run a step with a wrong parameter. This will ensure the safety of the workflow execution.

How can KubeVela Workflow be used

During the evolution of the OAM and KubeVela project, workflow, as an important part to control the delivery process, has gradually matured. Therefore, we separated the workflow code from the KubeVela repository to make it standalone. As a general workflow engine, it can be used directly or as an SDK by other projects.

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.

Please refer to the installation and quick start sections.

As an SDK

You can use KubeVela Workflow as an SDK to integrate it into your project. For example, the KubeVela Project use it to control the process of application delivery.

You just need to initialize a workflow instance and generate all the task runners with the instance, then execute the task runners. Please check out the example in Workflow or KubeVela.

Installation

Install Workflow

You can install workflow with Helm:

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

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

vela addon enable vela-workflow

Install Vela CLI

Please checkout: Install Vela CLI

Install built-in steps in KubeVela(Optional)

Use vela def apply <directory> to install built-in steps in KubeVela.

Checkout this doc for more details.

Quick Start

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

Note: You need to install the notification step definition and definitions in the example directory first to run the example.

Run a WorkflowRun directly

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:

If you change the url to an invalid one, you will get a failed notification:

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:

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:

apiVersion: core.oam.dev/v1alpha1
kind: WorkflowRun
metadata:
  name: deploy-run
  namespace: default
spec:
  context:
    env: dev
  workflowRef: deploy-template

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.

Features

KubeVela uses Workflow as a SDK to control the process of application delivery. Therefor, all the features of Workflow are also available in KubeVela Workflow.

Please checkout the KubeVela Workflow documentation for more details.

How to write custom steps

If you're not familiar with CUE, please checkout the CUE documentation first.

You can customize your steps with CUE and some built-in operations. Please checkout the tutorial for more details.

Contributing

Check out CONTRIBUTING to see how to develop with KubeVela Workflow.