Version: v1.3

Built-in Workflow Steps

This documentation will walk through the built-in workflow steps that you can use to design an application deployment process.

deploy

Overview

Deploy components with policies.

Parameter

Name	Type	Description
auto	bool	Optional, default to true. If set to false, the workflow will suspend automatically before this step.
policies	[]string	Optional, the policies that used for this deployment. If not specified, the components will be deployed to the hub cluster.
parallelism	int	Optional, defaults to 5.

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: deploy-workflowstep
  namespace: examples
spec:
  components:
    - name: nginx-deploy-workflowstep
      type: webservice
      properties:
        image: nginx
  policies:
    - name: topology-hangzhou-clusters
      type: topology
      properties:
        clusterLabelSelector:
          region: hangzhou
    - name: topology-local
      type: topology
      properties:
        clusters: ["local"]
        namespace: examples-alternative
  workflow:
    steps:
      - type: deploy
        name: deploy-local
        properties:
          policies: ["topology-local"]
      - type: deploy
        name: deploy-hangzhou
        properties:
          # require manual approval before running this step
          auto: false
          policies: ["topology-hangzhou-clusters"]

suspend

Overview

Suspend the current workflow, we can use vela workflow resume appname to resume the suspended workflow.

For more information of vela workflow, please refer to vela cli。

Parameter

Notice that you need to upgrade to KubeVela v1.4 or higher to use duration parameter.

Name	Type	Description
duration	string	Optional, the wait duration time to resume workflow such as "30s", "1min" or "2m15s"

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: first-vela-workflow
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
  workflow:
    steps:
      - name: slack-message
        type: webhook-notification
        properties:
          slack:
            # the Slack webhook address, please refer to: https://api.slack.com/messaging/webhooks
            message:
              text: Ready to apply the application, ask the administrator to approve and resume the workflow.
      - name: manual-approval
        type: suspend
        # properties:
        #   duration: "30s"
      - name: express-server
        type: apply-application

notification

Overview

Send notifications. You can use the notification to send notifications to Email, DingTalk, Slack, Lark.

Parameters

Name	Type	Description
email	Object	Optional, please fulfill its from, to and content if you want to send email
email.from.address	String	Required, the email address that you want to send from
email.from.alias	String	Optional, the email alias to show after sending the email
email.from.password	ValueOrSecret	Required, the password of the email, you can either specify it in value or use secretRef
email.from.host	String	Required, the host of your email
email.from.port	Int	Optional, the port of the email host, default to 587
email.to	[]String	Required, the email address that you want to send to
email.content.subject	String	Required, the subject of the email
email.content.body	String	Required, the context body of the email
slack	Object	Optional, please fulfill its url and message if you want to send Slack messages
slack.url	ValueOrSecret	Required, the webhook address of Slack, you can choose to fill it directly in value or specify it in secret
slack.message	Object	Required, the Slack messages you want to send, please follow Slack messaging
dingding	Object	Optional, please fulfill its url and message if you want to send DingTalk messages
dingding.url	ValueOrSecret	Required, the webhook address of DingTalk, you can choose to fill it directly in value or specify it in secret
dingding.message	Object	Required, the DingTalk messages you want to send, please follow DingTalk messaging
lark	Object	Optional, please fulfill its url and message if you want to send Lark messages
lark.url	ValueOrSecret	Required, the webhook address of Lark, you can choose to fill it directly in value or specify it in secret
lark.message	Object	Required, the Lark messages you want to send, please follow Lark messaging

The ValueOrSecret format is:

Name	Type	Description
value	String	Optional, directly get the data from value
secretRef.name	String	Optional, get data from secret, the name of the secret
secretRef.key	String	Optional, get data from secret, the key of the secret

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: first-vela-workflow
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
    traits:
    - type: ingress
      properties:
        domain: testsvc.example.com
        http:
          /: 8000
  workflow:
    steps:
      - name: dingtalk-message
        type: notification
        properties:
          dingding:
            # the DingTalk webhook address, please refer to: https://developers.dingtalk.com/document/robots/custom-robot-access
            url: 
              value: <url>
            message:
              msgtype: text
              text:
                context: Workflow starting...
      - name: application
        type: apply-application
      - name: slack-message
        type: notification
        properties:
          slack:
            # the Slack webhook address, please refer to: https://api.slack.com/messaging/webhooks
            url:
              secretRef:
                name: <secret-key>
                key: <secret-value>
            message:
              text: Workflow ended.
          lark:
            url:
              value: <lark-url>
            message:
              msg_type: "text"
              content: "{\"text\":\" Hello KubeVela\"}"
          email:
            from:
              address: <sender-email-address>
              alias: <sender-alias>
              password:
                # secretRef:
                #   name: <secret-name>
                #   key: <secret-key>
                value: <sender-password>
              host: <email host like smtp.gmail.com>
              port: <email port, optional, default to 587>
            to:
              - kubevela1@gmail.com
              - kubevela2@gmail.com
            content:
              subject: test-subject
              body: test-body

Expected outcome

we can see that before and after the deployment of the application, the messages can be seen in the corresponding group chat.

webhook

Overview

Send a request to the specified Webhook URL. If no request body is specified, the current Application body will be sent by default.

Parameter

Name	Type	Description
url	ValueOrSecret	Required, Webhook URL to be sent, you can choose to fill in value directly or get it from secretRef
data	object	Optional, the data that needs to be sent

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: first-vela-workflow
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
  workflow:
    steps:
      - name: express-server
        type: apply-application
      - name: webhook
        type: webhook
        properties:
          url:
            value: <your webhook url>

apply-application

Overview

Apply all components and traits in Application.

Parameter

No arguments, used for custom steps before or after application applied.

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: first-vela-workflow
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
    traits:
    - type: ingress
      properties:
        domain: testsvc.example.com
        http:
          /: 8000
  workflow:
    steps:
      - name: express-server
        type: apply-application

depends-on-app

Overview

Wait for the specified Application to complete.

depends-on-app will check if the cluster has the application with name and namespace defines in properties. If the application exists, the next step will be executed after the application is running. If the application do not exists, KubeVela will check the ConfigMap with the same name, and read the config of the Application and apply to cluster. The ConfigMap is like below: the name and namespace of the ConfigMap is the same in properties. In data, the key is name, and the value is the yaml of the deployed application yaml.
apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp
  namespace: vela-system
data:
  myapp: ...

Parameter

Name	Type	Description
name	string	The name of the Application
namespace	string	The namespace of the Application

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: first-vela-workflow
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
    traits:
    - type: ingress
      properties:
        domain: testsvc.example.com
        http:
          /: 8000
  workflow:
    steps:
      - name: express-server
        type: depends-on-app
        properties:
          name: another-app
          namespace: default

apply-object

Overview

Apply Kubernetes native resources, you need to upgrade to KubeVela v1.1.4 or higher to enable apply-object.

Parameters

Name	Type	Description
value	Object	Required, Kubernetes native resources fields
cluster	String	Optional, The cluster you want to apply the resource to, default is the current cluster. If you want to apply resource in different cluster, use `vela cluster join` to join the cluster first, and then specify the cluster

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: server-with-pvc
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
      volumes:
        - name: "my-pvc"
          type: "pvc"
          mountPath: "/test"
          claimName: "myclaim"

  workflow:
    steps:
      - name: apply-pvc
        type: apply-object
        properties:
          # Kubernetes native resources fields
          value:
            apiVersion: v1
            kind: PersistentVolumeClaim
            metadata:
              name: myclaim
              namespace: default
            spec:
              accessModes:
              - ReadWriteOnce
              resources:
                requests:
                  storage: 8Gi
              storageClassName: standard
            # the cluster you want to apply the resource to, default is the current cluster
            cluster: <your cluster name>  
      - name: apply-server
        type: apply-component
        properties:
          component: express-serve

read-object

Overview

Read Kubernetes native resources, you need to upgrade to KubeVela v1.1.6 or higher to enable read-object.

Parameters

Name	Type	Description
apiVersion	String	Required, The apiVersion of the resource you want to read
kind	String	Required, The kind of the resource you want to read
name	String	Required, The apiVersion of the resource you want to read
namespace	String	Optional, The namespace of the resource you want to read, defaults to `default`
cluster	String	Optional, The cluster you want to read the resource from, default is the current cluster. If you want to read resource in different cluster, use `vela cluster join` to join the cluster first, and then specify the cluster

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: read-object
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
  workflow:
    steps:
    - name: read-object
      type: read-object
      outputs:
        - name: cpu
          valueFrom: output.value.data["cpu"]
        - name: memory
          valueFrom: output.value.data["memory"]
      properties:
        apiVersion: v1
        kind: ConfigMap
        name: my-cm-name
        cluster: <your cluster name
    - name: apply
      type: apply-component
      inputs:
        - from: cpu
          parameterKey: cpu
        - from: memory
          parameterKey: memory
      properties:
        component: express-server

export2config

Overview

Export data to ConfigMap, you need to upgrade to KubeVela v1.1.6 or higher to enable export2config.

Parameters

Name	Type	Description
configName	String	Required, The name of the ConfigMap
namespace	String	Optional, The namespace of the ConfigMap, defaults to `context.namespace`
data	Map	Required, The data that you want to export to ConfigMap

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: export-config
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
  workflow:
    steps:
      - name: apply-server
        type: apply-component
        outputs: 
          - name: status
            valueFrom: output.status.conditions[0].message
        properties:
          component: express-server
      - name: export-config
        type: export-config
        inputs:
          - from: status
            parameterKey: data.serverstatus
        properties:
          configName: my-configmap
          data:
            testkey: testvalue

export2secret

Overview

Export data to Secret, you need to upgrade to KubeVela v1.1.6 or higher to enable export2secret.

Parameters

Name	Type	Description
secretName	String	Required, The name of the Secret
namespace	String	Optional, The namespace of the Secret, defaults to `context.namespace`
data	Map	Required, The data that you want to export to Secret

Example

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: export-secret
  namespace: default
spec:
  components:
  - name: express-server
    type: webservice
    properties:
      image: oamdev/hello-world
      port: 8000
  workflow:
    steps:
      - name: apply-server
        type: apply-component
        outputs: 
          - name: status
            valueFrom: output.status.conditions[0].message
        properties:
          component: express-server
      - name: export-secret
        type: export-secret
        inputs:
          - from: status
            parameterKey: data.serverstatus
        properties:
          secretName: my-secret
          data:
            testkey: testvalue

deploy​

suspend​

notification​

webhook​

apply-application​

depends-on-app​

apply-object​

read-object​

export2config​

export2secret​

deploy

suspend

notification

webhook

apply-application

depends-on-app

apply-object

read-object

export2config

export2secret