github.com/kubevela/workflow@v0.6.0/README.md (about)

     1  # KubeVela Workflow
     2  
     3  [![Go Report Card](https://goreportcard.com/badge/github.com/kubevela/workflow)](https://goreportcard.com/report/github.com/kubevela/workflow)
     4  [![codecov](https://codecov.io/gh/kubevela/workflow/branch/main/graph/badge.svg)](https://codecov.io/gh/kubevela/workflow)
     5  [![LICENSE](https://img.shields.io/github/license/kubevela/workflow.svg?style=flat-square)](/LICENSE)
     6  [![Total alerts](https://img.shields.io/lgtm/alerts/g/kubevela/workflow.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/kubevela/workflow/alerts/)
     7  
     8  
     9  ## What is KubeVela Workflow
    10  
    11  KubeVela Workflow is an open-source cloud-native workflow project that can use to orchestrate CI/CD process, terraform resources, multi-kubernetes-clusters management and even your own functional calls.
    12  
    13  You can [install](#installation) KubeVela Workflow and use it, or import the code as an [sdk](#how-can-kubevela-workflow-be-used) of an IaC-based workflow engine in your own repository.
    14  
    15  *The main differences between KubeVela Workflow and other cloud-native workflows are*:
    16  
    17  All the steps in the workflow is based on IaC(Cue): every step has a `type` for abstract and reuse, the `step-type` is programmed in [CUE](https://cuelang.org/) language and easy to customize. 
    18  
    19  That is to say, **you can use atomic capabilities like a function call in every step, instead of just creating a pod.**
    20  
    21  ## Why use KubeVela Workflow
    22  
    23  <h1 align="center"><a href="https://kubevela.io/docs/end-user/pipeline/workflowrun"><img src="https://static.kubevela.net/images/1.6/workflow-arch.png" alt="workflow arch" align="center" width="700px" /></a></h1>
    24  
    25  🌬️ **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.
    26  
    27  ✨ **Flexible, Extensible and Programmable**: Every step has a type, and all the types are based on the [CUE](https://cuelang.org/) language, which means if you want to customize a new step type, you just need to write CUE codes and no need to compile or build anything, KubeVela Workflow will evaluate these codes.
    28  
    29  💪 **Rich built-in capabilities**: You can control the process with conditional judgement, inputs/outputs, timeout, etc. You can also use the built-in step types to do some common tasks, such as `deploy resources`, `suspend`, `notification`, `step-group` and more!
    30  
    31  🔐 **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.
    32  
    33  ## Try KubeVela Workflow
    34  
    35  Run your first WorkflowRun to distribute secrets, build and push your image, and apply the resources in the cluster! Image build can take some time, you can use `vela workflow logs build-push-image --step build-push` to check the logs of building.
    36  
    37  ```
    38  apiVersion: core.oam.dev/v1alpha1
    39  kind: WorkflowRun
    40  metadata:
    41    name: build-push-image
    42    namespace: default
    43  spec:
    44    workflowSpec:
    45     steps:
    46     # or use kubectl create secret generic git-token --from-literal='GIT_TOKEN=<your-token>'
    47      - name: create-git-secret
    48        type: export2secret
    49        properties:
    50          secretName: git-secret
    51          data:
    52            token: <git token>
    53      # or use kubectl create secret docker-registry docker-regcred \
    54      # --docker-server=https://index.docker.io/v1/ \
    55      # --docker-username=<your-username> \
    56      # --docker-password=<your-password> 
    57      - name: create-image-secret
    58        type: export2secret
    59        properties:
    60          secretName: image-secret
    61          kind: docker-registry
    62          dockerRegistry:
    63            username: <docker username>
    64            password: <docker password>
    65      - name: build-push
    66        type: build-push-image
    67        properties:
    68          # use your kaniko executor image like below, if not set, it will use default image oamdev/kaniko-executor:v1.9.1
    69          # kanikoExecutor: gcr.io/kaniko-project/executor:latest
    70          # you can use context with git and branch or directly specify the context, please refer to https://github.com/GoogleContainerTools/kaniko#kaniko-build-contexts
    71          context:
    72            git: github.com/FogDong/simple-web-demo
    73            branch: main
    74          image: fogdong/simple-web-demo:v1
    75          # specify your dockerfile, if not set, it will use default dockerfile ./Dockerfile
    76          # dockerfile: ./Dockerfile
    77          credentials:
    78            image:
    79              name: image-secret
    80          # buildArgs:
    81          #   - key="value"
    82          # platform: linux/arm
    83      - name: apply-deploy
    84        type: apply-deployment
    85        properties:
    86          image: fogdong/simple-web-demo:v1
    87  ```
    88  
    89  ## Quick Start
    90  
    91  After installation, you can either run a WorkflowRun directly or from a Workflow Template. Every step in the workflow should have a type and some parameters, in which defines how this step works. You can use the [built-in step type definitions](./examples/built-in-workflow-def.md) or [write your own custom step types](#how-to-write-custom-steps).
    92  
    93  > Please checkout the [WorkflowRun Specification](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#workflowrun) and [WorkflowRun Status](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#status) for more details.
    94  
    95  ### Run a WorkflowRun directly
    96  
    97  For more, please refer to the following examples:
    98  
    99  - [Control the delivery process of multiple resources(e.g. your Applications)](./examples/multiple-apps.md)
   100  - [Request a specified URL and then use the response as a message to notify](./examples/request-and-notify.md)
   101  - [Automatically initialize the environment with terraform](./examples/initialize-env.md)
   102  
   103  ### Run a WorkflowRun from a Workflow Template
   104  
   105  Please refer to the following examples:
   106  
   107  - [Run the Workflow Template with different context to control the process](./examples/run-with-template.md)
   108  
   109  ## Installation
   110  
   111  ### Install Workflow
   112  
   113  #### Helm
   114  
   115  ```shell
   116  helm repo add kubevela https://kubevela.github.io/charts
   117  helm repo update
   118  helm install --create-namespace -n vela-system vela-workflow kubevela/vela-workflow
   119  ```
   120  
   121  #### KubeVela Addon
   122  
   123  If you have installed KubeVela, you can install Workflow with the KubeVela Addon:
   124  
   125  ```shell
   126  vela addon enable vela-workflow
   127  ```
   128  
   129  ### Install Vela CLI(Optional)
   130  
   131  Please checkout: [Install Vela CLI](https://kubevela.io/docs/installation/kubernetes#install-vela-cli)
   132  
   133  ## Features
   134  
   135  - [Operate WorkflowRun](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#operate-workflowrun)
   136  - [Suspend and Resume](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#suspend-and-resume)
   137  - [Sub Steps](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#sub-steps)
   138  - [Dependency](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#dependency)
   139  - [Data Passing](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#data-passing)
   140  - [Timeout](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#timeout)
   141  - [If Conditions](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#if-conditions)
   142  - [Custom Context Data](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#custom-context-data)
   143  - [Built-in Context Data](https://kubevela.io/docs/next/end-user/pipeline/workflowrun#built-in-context-data)
   144  
   145  ## Step Types
   146  
   147  ### Built-in Step Types
   148  
   149  Please checkout the [built-in step definitions](https://kubevela.io/docs/next/end-user/workflow/built-in-workflow-defs) with scope that valid in `WorkflowRun`.
   150  ### Write Your Custom Step Types
   151  
   152  If you're not familiar with CUE, please checkout the [CUE documentation](https://kubevela.io/docs/platform-engineers/cue/basic) first.
   153  
   154  You can customize your steps with CUE and some [built-in operations](https://kubevela.io/docs/platform-engineers/workflow/cue-actions). Please checkout the [tutorial](https://kubevela.io/docs/platform-engineers/workflow/workflow) for more details.
   155  
   156  > Note that you cannot use the [application operations](https://kubevela.io/docs/next/platform-engineers/workflow/cue-actions#application-operations) since there're no application data like components/traits/policy in the WorkflowRun.
   157  
   158  ## How can KubeVela Workflow be used
   159  
   160  During the evolution of the [OAM](https://oam.dev/) and [KubeVela project](https://github.com/kubevela/kubevela), **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.
   161  
   162  ### As a standalone workflow engine
   163  
   164  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:
   165  
   166  - 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.
   167  - Orchestrate delivery process without day-2 management, just deploy. The most common use case is to initialize your infrastructure for some environment.
   168  
   169  ### As an SDK
   170  
   171  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.
   172  
   173  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](https://github.com/kubevela/workflow/blob/main/controllers/workflowrun_controller.go#L101) or [KubeVela](https://github.com/kubevela/kubevela/blob/master/pkg/controller/core.oam.dev/v1alpha2/application/application_controller.go#L197).
   174  
   175  ## Contributing
   176  
   177  Check out [CONTRIBUTING](https://kubevela.io/docs/contributor/overview) to see how to develop with KubeVela Workflow.