Imagine needing to deploy an application that requires multiple stages: first, setting up a database, then deploying your microservice, running integration tests, and finally, sending a notification to a Slack channel. How do you automate this complex, ordered sequence of operations consistently across different environments? This often involves a tangle of scripts, manual steps, or brittle CI/CD configurations.

This is precisely where KubeVela Workflows shine. For platform teams, Workflows transform KubeVela into a powerful application delivery control plane, allowing you to define, automate, and orchestrate the entire lifecycle of an application, from provisioning resources to post-deployment verification and promotion. They bring order and consistency to what would otherwise be a chaotic process.

In this chapter, we’ll dive deep into KubeVela Workflows. You’ll learn what they are, why they’re indispensable for creating robust delivery pipelines, and how to build your own multi-stage workflows using KubeVela’s flexible step system and the powerful CUE language. By the end, you’ll be able to design sophisticated, automated application delivery processes that bring consistency and reliability to your deployments.

To get the most out of this chapter, you should be familiar with KubeVela’s core concepts: Applications, Components, and Traits, as covered in previous sections. You’ll also need a running Kubernetes cluster with KubeVela v1.12.x (as of 2026-06-22) installed and kubectl configured to access it.

The Power of KubeVela Workflows

When we talk about deploying applications, it’s rarely a single, atomic operation. Modern applications often involve a series of interconnected steps: resource provisioning, service deployment, configuration, testing, and more. KubeVela Workflows provide the orchestration layer to manage these complexities directly within your application definition.

What is a KubeVela Workflow?

A KubeVela Workflow is an ordered sequence of steps that define the lifecycle of an application. Think of it as a customizable blueprint for how your application gets from code to production. Each step in a workflow performs a specific action, and they execute in a defined order, allowing you to build sophisticated delivery pipelines directly within your Application definition.

Unlike traditional CI/CD pipelines defined externally, KubeVela Workflows are declared as part of your Application resource. This means your application’s delivery process becomes a first-class citizen alongside its components and traits, promoting a truly application-centric approach.

Why Workflows Matter for Platform Teams

For platform engineers, Workflows are a game-changer. They address several critical challenges that often plague application delivery:

  • Standardization: Workflows enable you to encapsulate best practices for application delivery into reusable templates. Developers then consume these standardized pipelines, ensuring consistent deployments across the organization without needing to understand the underlying infrastructure complexities.
  • Automation: Manual deployment steps are error-prone and slow. Workflows automate everything from resource provisioning to post-deployment checks, reducing human error, accelerating delivery, and freeing up developer time.
  • Extensibility: KubeVela’s workflow engine is incredibly flexible. You’re not limited to built-in steps; you can define custom steps using CUE, allowing you to integrate with virtually any external system or internal tool, from cloud providers to custom CI/CD systems, security scanners, or notification services.
  • Observability: KubeVela provides clear visibility into the execution status of each workflow step. This makes it easy to monitor progress, identify bottlenecks, and troubleshoot failures directly from the vela CLI or KubeVela UI.

Without Workflows, platform teams often resort to complex CI/CD scripts, custom Kubernetes operators, or manual interventions to manage application lifecycles. Workflows offer a declarative, application-centric, and Kubernetes-native approach to solve this.

Workflow Steps: The Building Blocks of Delivery

Each workflow is composed of individual steps. A step is an atomic unit of work that performs a specific action. KubeVela comes with several built-in step types, and you can extend these with custom definitions using WorkflowStepDefinition resources.

Common built-in step types you’ll encounter include:

  • deploy: This is the most common step, responsible for deploying components and their associated traits onto the Kubernetes cluster.
  • suspend: Pauses the workflow until manually resumed or a specified condition is met. This is incredibly useful for implementing manual approvals, waiting for external systems, or staging rollouts.
  • apply-component: Applies a specific component definition, allowing for fine-grained control over which components are deployed at which stage.
  • read-component: Reads the output of a component, enabling subsequent steps to use information generated by a deployed component.
  • custom: Allows you to define highly custom logic using CUE, making it possible to interact with external APIs, run shell commands, or perform complex data transformations.

Steps can pass information between each other using KubeVela’s context mechanism, allowing you to build sophisticated pipelines where the output of one step becomes the input for the next. This enables complex, data-driven delivery processes.

Customizing Steps with CUE: The Secret Sauce

The real power and flexibility of KubeVela Workflows come from its deep integration with CUE. CUE (Configuration, Unification, and Execution) is a powerful open-source language that allows you to define, generate, and validate configurations. In KubeVela, CUE is used to:

  • Define Custom Workflow Steps: You can write CUE templates that describe the logic and actions of a new, domain-specific workflow step. This allows you to integrate with external APIs (e.g., a cloud provider’s database service, a security scanner), run shell commands inside a temporary pod, or perform complex data transformations.
  • Control Step Behavior: CUE can be used within existing steps (like deploy) to dynamically modify resource configurations based on workflow context, application parameters, or even outputs from previous steps. This enables highly adaptive deployments.
  • Validate Inputs/Outputs: Ensure that data flowing between steps and the parameters provided to custom steps meet expected schemas, enhancing reliability and preventing misconfigurations.

📌 Key Idea: CUE provides a robust, declarative way to extend KubeVela’s capabilities without writing Go code or building custom Kubernetes operators. This significantly lowers the barrier for platform engineers to create powerful, tailored delivery experiences.

Visualizing the Workflow Execution Flow

To better understand how KubeVela Workflows operate, let’s visualize a common delivery pipeline pattern.

flowchart TD A[Application Definition] --> B{Start Workflow} B --> C[Deploy Staging Component] C --> D[Run Integration Tests] D --|Tests Pass| E[Request Manual Approval] E --|Approved| F[Deploy Production Component] D --|Tests Fail| G[Send Failure Alert] F --> H[Workflow Complete] G --> H

In this flow:

  • The Application Definition triggers the Workflow.
  • A Deploy Staging Component step creates resources in a staging environment.
  • Run Integration Tests then verifies the staging deployment.
  • Based on the test results, the workflow conditionally proceeds:
    • If Tests Pass, it might Request Manual Approval (using a suspend step).
    • If Tests Fail, it could Send Failure Alert (a custom CUE step).
  • Upon approval, Deploy Production Component executes.
  • Finally, the workflow concludes, whether through success or failure paths.

This diagram illustrates sequential execution with conditional branching, a core capability of KubeVela Workflows. Each box represents a step, and the arrows show the flow of control.

Building Your First Delivery Pipeline

Let’s put theory into practice by creating a multi-stage application delivery workflow. Our goal is to:

  1. Define a simple Nginx web server component.
  2. Implement a “pre-deployment” gate, simulating a manual approval before any deployment occurs.
  3. Deploy the Nginx component.
  4. Perform a “post-deployment” verification using a custom CUE step to simulate a health check.

Setting the Stage: Our Sample Application

First, let’s define a basic KubeVela Application with an Nginx component. We’ll add the workflow directly to this application.

Create a file named nginx-app-workflow.yaml:

# nginx-app-workflow.yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: nginx-workflow-app
spec:
  components:
    - name: my-nginx-component
      type: webservice
      properties:
        image: nginx:1.25.3 # Using a recent stable Nginx version (as of 2026-06-22)
        port: 80
      traits:
        - type: ingress
          properties:
            domain: workflow.example.com
            http:
              /: 80
  # We'll add the workflow definition here!

This is a standard KubeVela application deploying an Nginx webservice component with an ingress trait. Nothing new here, just a foundation for our workflow.

Step 1: Initial Deployment (and a Pre-Deployment Pause)

Now, let’s add a workflow section to our Application. Our first step will be a suspend step, simulating a manual approval or a pre-deployment gate. This step will pause the workflow until we manually resume it.

Add the workflow section to your nginx-app-workflow.yaml file, right after the components section:

# nginx-app-workflow.yaml (continued)
# ... (existing components and traits)
  workflow:
    steps:
      - name: pre-deployment-check
        type: suspend
        properties:
          message: "Manual approval required before deploying Nginx component. Review changes."
      - name: deploy-nginx
        type: deploy
        properties:
          # This step will deploy all components defined in the application.
          # For granular control, you could specify:
          # component: my-nginx-component

Let’s break down what we’ve added:

  • workflow: This is the top-level key for defining our application’s delivery pipeline.
  • steps: A list of individual workflow actions that KubeVela will execute in order.
  • pre-deployment-check: Our first step, of type: suspend. It will simply pause the workflow. The message property provides context to anyone viewing the workflow status, explaining why it’s paused.
  • deploy-nginx: This is a standard deploy step. By default, it will deploy all components defined in the Application. If you had multiple components and only wanted to deploy a specific one at this stage, you could use component: <component-name>.

Now, let’s apply this application to your Kubernetes cluster and observe its state:

kubectl apply -f nginx-app-workflow.yaml

Once applied, check the application status, paying close attention to the workflow section:

vela status nginx-workflow-app --workflow

You should see output similar to this, indicating the workflow is paused:

App Status: running
...
Workflow Steps:
  - Name: pre-deployment-check
    Type: suspend
    Phase: running
    Message: Manual approval required before deploying Nginx component. Review changes.
  - Name: deploy-nginx
    Type: deploy
    Phase: pending

Notice that pre-deployment-check is running and deploy-nginx is pending. The workflow is currently paused, waiting for your instruction!

To proceed and allow the deployment to happen, we need to manually resume the workflow:

vela workflow resume nginx-workflow-app

Now, check vela status nginx-workflow-app --workflow again. You should see the deploy-nginx step now running or completed, and your Nginx component being deployed onto the cluster. You can verify the Nginx deployment by checking kubectl get deploy,svc,ing -l app.oam.dev/name=nginx-workflow-app.

Step 2: Post-Deployment Verification with a Custom CUE Step

Deploying is one thing, but verifying that the deployment is healthy and functioning correctly is another crucial step. What if we want to perform a check after deployment, like verifying an external API endpoint or checking for specific logs? We can define a custom CUE step for this.

First, let’s define a WorkflowStepDefinition that encapsulates our verification logic. We’ll create a simple step that “checks” a condition and, for demonstration, can either succeed or fail based on a parameter.

Create a file named verify-step.yaml:

# verify-step.yaml
apiVersion: core.oam.dev/v1beta1
kind: WorkflowStepDefinition
metadata:
  name: verify-deployment
spec:
  schematic:
    cue: |
      parameter: {
        condition: bool @default(true) // Simulates a condition check: true for success, false for failure
      }
      outputs: {
        result: "Verification " + (if parameter.condition {"succeeded"} else {"failed"})
      }
      // In a real-world scenario, you would replace the simple 'condition' parameter with actual logic:
      // - Making an HTTP request to a service endpoint to check its availability.
      // - Querying Kubernetes resource status (e.g., all pods are 'Ready').
      // - Running a shell command inside a temporary pod to execute a test script.
      // - Interacting with an external monitoring system to check metrics.
      // If the check fails, you could use `fail: "Reason for failure"` to stop the workflow and trigger a rollback.
      // For this example, we'll just output a message based on the 'condition' parameter.

Apply this WorkflowStepDefinition to your cluster. This registers our new custom step type with KubeVela:

kubectl apply -f verify-step.yaml

Now, let’s modify our nginx-app-workflow.yaml to include this new verify-deployment step after our deploy-nginx step.

# nginx-app-workflow.yaml (modified)
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: nginx-workflow-app
spec:
  components:
    - name: my-nginx-component
      type: webservice
      properties:
        image: nginx:1.25.3
        port: 80
      traits:
        - type: ingress
          properties:
            domain: workflow.example.com
            http:
              /: 80
  workflow:
    steps:
      - name: pre-deployment-check
        type: suspend
        properties:
          message: "Manual approval required before deploying Nginx component. Review changes."
      - name: deploy-nginx
        type: deploy
      - name: post-deployment-verify
        type: verify-deployment # Using our custom step!
        properties:
          condition: true # Set to 'false' here to simulate a verification failure

Apply the updated application. Since the workflow for nginx-workflow-app might still be running or terminated from the previous execution, KubeVela will re-evaluate it. If it was terminated, it will run again. If it was running and already past the suspend step, it will continue with the new steps.

To ensure you see the new workflow in action from the beginning, it’s often best to delete and re-create the application, and then resume it after the suspend step:

# Delete the existing application to clear its workflow state
kubectl delete application nginx-workflow-app

# Re-apply the updated application with the new verification step
kubectl apply -f nginx-app-workflow.yaml

# Resume the workflow after the initial suspend step
vela workflow resume nginx-workflow-app

Now, check the status again:

vela status nginx-workflow-app --workflow

You should see post-deployment-verify running or completed. This is where the power of custom steps becomes evident. You can inspect its logs to see the output from our CUE logic:

vela workflow logs nginx-workflow-app --step post-deployment-verify

The logs might show the output from our CUE step, like “Verification succeeded”. If you had set condition: false in the properties for the post-deployment-verify step in nginx-app-workflow.yaml and reapplied, the output would reflect “Verification failed”. In a real scenario, a failing CUE step could use fail: "reason" to stop the workflow or trigger a rollback.

Step 3: Observing Workflow Progress

KubeVela provides excellent tools to observe and manage your workflow’s execution. These commands are invaluable for platform engineers managing complex delivery pipelines:

  • vela status <app-name> --workflow: This is your primary command. It shows the current phase of each step (e.g., running, pending, succeeded, failed, terminated).
  • vela workflow logs <app-name> --step <step-name>: Fetches logs for a specific step. This is crucial for debugging custom CUE steps, as it displays any print statements or errors from your CUE code.
  • vela workflow restart <app-name>: Restarts the workflow from the beginning. Useful for re-running a deployment after fixing an issue.
  • vela workflow terminate <app-name>: Stops a running workflow immediately. This can be used to halt a problematic deployment.
  • vela workflow suspend <app-name>: Pauses a running workflow at its current step.
  • vela workflow resume <app-name>: Resumes a suspended workflow, allowing it to continue from where it left off.

Mini-Challenge: Enhancing Your Workflow

You’ve built a basic multi-stage workflow. Now, let’s make it even more robust by adding a notification step.

Challenge: Modify the nginx-workflow-app to include an additional workflow step:

  1. After the post-deployment-verify step, add a new custom step called send-slack-notification.
  2. This step should take a message parameter (e.g., “Nginx deployment to staging completed successfully!”).
  3. For simplicity, the CUE definition for this send-slack-notification step doesn’t need to actually integrate with Slack. Just make it output a message like “Sending Slack notification: [your message]”.
  4. Apply the new WorkflowStepDefinition and then update your Application’s workflow to include this new step.

Hint:

  • You’ll need to create a new WorkflowStepDefinition YAML file (e.g., slack-step.yaml) similar to verify-step.yaml.
  • Remember to define parameter and outputs in the CUE schematic.
  • Then, add a new step to the workflow.steps list in your nginx-app-workflow.yaml, placing it after the post-deployment-verify step.
  • Don’t forget to kubectl apply both the new WorkflowStepDefinition and the updated Application. You might need to delete and re-apply the application to see the full workflow run from the start.

What to observe/learn: You’ll see how easy it is to extend your delivery pipeline with new custom actions, building a comprehensive, automated process for your applications. This exercise reinforces the power of WorkflowStepDefinition for encapsulating reusable logic.

Troubleshooting Common Workflow Issues

Workflows, especially with custom CUE steps, can sometimes be tricky. Here are some common pitfalls and how to troubleshoot them:

  • Workflow Stuck in running or pending:

    • Diagnosis: Use vela status <app-name> --workflow. This will show you which specific step is currently active or waiting.
    • Solution:
      • If it’s a suspend step, you likely need to vela workflow resume <app-name>.
      • If it’s a deploy step, check the underlying Kubernetes resources (Pods, Deployments, Services) for errors using kubectl get events, kubectl describe the relevant resources, or kubectl logs pods. The application’s components might be failing to start.
      • If it’s a custom CUE step, move to the next point.

  • CUE Syntax Errors or Logic Issues in Custom Steps:

    • Diagnosis: When defining WorkflowStepDefinition with CUE, even a small syntax error or logical flaw can prevent the step from working. vela workflow logs <app-name> --step <step-name> is your best friend here. It will often output detailed CUE validation errors, runtime errors, or the results of your print statements.
    • Solution: Carefully review the CUE code in your WorkflowStepDefinition. Use a CUE linter or an IDE extension with CUE support during development to catch errors early. Incrementally build your CUE logic, testing small parts before combining them.

  • Incorrect Step Order or Dependencies:

    • Diagnosis: Workflows execute steps sequentially as defined in the steps list. If a later step depends on an output from an earlier step, or if an action needs to happen before another, the order is critical.
    • Solution: Review your workflow.steps list. KubeVela allows dependsOn in steps for explicit ordering, which can be useful for non-linear flows, but for simple linear pipelines, the list order is generally sufficient. Ensure that any resource provisioning or information gathering steps occur before steps that rely on them.

  • Permissions Issues for Custom Steps:

    • Diagnosis: If your custom CUE step attempts to create, modify, or delete Kubernetes resources (e.g., creating a Secret, updating a ConfigMap), or if it interacts with external services, the KubeVela controller’s ServiceAccount needs the necessary RBAC permissions.
    • Solution: Ensure the ClusterRole and ClusterRoleBinding for KubeVela grant appropriate permissions for the resources your custom steps manage. If a CUE step calls an external API, ensure the KubeVela controller pod has network access and any required credentials (e.g., API keys) are correctly mounted as Secrets and referenced within your CUE logic.

⚡ Real-world insight: For complex CUE steps, it’s often helpful to break down the logic into smaller, testable CUE files. You can even use the cue eval command-line tool to test parts of your CUE definitions independently before embedding them directly into a WorkflowStepDefinition. This significantly speeds up debugging.

Summary: Orchestrating Your Application’s Journey

Congratulations! You’ve successfully navigated the world of KubeVela Workflows, a cornerstone for building robust and automated application delivery pipelines.

Here are the key takeaways from this chapter:

  • Workflows automate application lifecycle management: They define an ordered sequence of steps for deploying, verifying, promoting, and even rolling back applications.
  • Platform teams leverage Workflows for standardization and extensibility: They provide a declarative, application-centric way to build consistent and customizable delivery processes across environments.
  • Steps are the building blocks: KubeVela offers powerful built-in steps like deploy and suspend, and you can create highly specialized custom steps.
  • CUE is crucial for customization: It empowers platform engineers to define complex custom workflow logic, integrate with external systems, and dynamically control step behavior without writing Go code.
  • Observability is built-in: Tools like vela status --workflow and vela workflow logs provide clear, real-time visibility into pipeline execution, making monitoring and debugging straightforward.

By mastering Workflows, you empower your team to move beyond simple deployments to fully automated, intelligent application delivery. This is a significant step towards building a truly self-service, cloud-native platform that reduces operational burden and accelerates development.

In the next chapter, we’ll explore KubeVela Addons, which allow you to extend KubeVela’s capabilities by installing pre-packaged features like advanced metrics, logging, or integration with GitOps tools. This will further enhance your platform engineering toolkit, showing you how to grow your KubeVela platform.

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.