Introduction: From Kubernetes Complexity to Application Simplicity

When managing applications on Kubernetes, platform teams often face a dilemma: how do you give developers the power of Kubernetes without overwhelming them with its inherent complexity? Raw Kubernetes manifests can be verbose, Helm charts offer packaging but often require deep Kubernetes knowledge to customize, and building a custom internal platform is a massive undertaking. This is where KubeVela steps in, offering an application delivery control plane that abstracts away the underlying infrastructure details.

In this chapter, we’ll shift from the “why” of KubeVela to the “how.” You’ll get your hands dirty by setting up KubeVela in your Kubernetes cluster. More importantly, we’ll dive deep into the heart of KubeVela: the Open Application Model (OAM). Understanding OAM is crucial because it’s the language KubeVela uses to describe and deliver applications, providing a clean separation of concerns between platform engineers and application developers.

By the end of this chapter, you’ll have KubeVela running and a solid grasp of OAM’s core concepts. This foundational knowledge will empower you to define and manage applications in an application-centric way, paving the path for truly scalable and maintainable delivery pipelines.

Prerequisites

Before we begin, please ensure you have:

  • A running Kubernetes cluster (any version compatible with KubeVela, typically v1.23+).
  • kubectl configured to access your cluster. We’ll assume kubectl version v1.32.x for this guide, compatible with recent Kubernetes releases.

Setting Up KubeVela: Your Application Control Plane

KubeVela transforms your Kubernetes cluster into an application delivery hub. It provides an extensible framework that allows platform engineers to define the capabilities and guardrails for application deployment, which developers then consume through a simplified, application-centric API.

Installation

Installing KubeVela is straightforward. We’ll use the vela command-line tool, which provides a convenient way to interact with KubeVela. As of 2026-06-22, the latest stable release of KubeVela is v1.11.0.

First, let’s install the vela CLI:

# Download the vela CLI for your OS (example for Linux AMD64)
curl -fsSL https://kubevela.io/script/install.sh | bash

# Verify installation
vela version

You should see output similar to this (versions might vary slightly):

# Example output for 'vela version'
CLI Version: 1.11.0
Core Version: N/A

The Core Version is N/A because we haven’t installed the KubeVela controller into your cluster yet. Let’s do that now.

# Install KubeVela into your Kubernetes cluster
vela install --version v1.11.0

# Check the installation status
vela status -n vela-system

The vela install command deploys the KubeVela control plane components into the vela-system namespace. This includes the KubeVela controller, which is responsible for reconciling Application resources and other OAM definitions.

vela status will show you the progress. It might take a few minutes for all components to become ready. Once ready, you should see something like:

# Example output for 'vela status'
NAMESPACE      NAME                         STATUS   HEALTHY  REASON
vela-system    kubevela-cluster-gateway     Running  True     
vela-system    kubevela-core                Running  True     
vela-system    kubevela-workflow            Running  True     
...

Congratulations! Your Kubernetes cluster is now powered by KubeVela.

Unpacking the Open Application Model (OAM)

At the heart of KubeVela is the Open Application Model (OAM). OAM is a specification that aims to make application development and operations easier by separating concerns. Think of it as a blueprint for building and running applications on cloud-native platforms.

What is OAM and Why Does It Exist?

📌 Key Idea: OAM separates the “what” (application definition by developers) from the “how” (operational capabilities provided by platform engineers).

Before OAM, developers often had to deal with low-level Kubernetes details like Deployment replicas, Service ports, Ingress rules, and HorizontalPodAutoscaler configurations. This created a steep learning curve and made it hard to enforce consistent operational practices.

OAM solves this by introducing a clear contract:

  • For Developers: Focus on defining their application’s components and their desired operational characteristics (e.g., “I need 3 replicas,” “I need an ingress,” “I need to scale based on CPU”). They don’t need to know the intricate Kubernetes YAML.
  • For Platform Engineers: Focus on defining the capabilities and policies that fulfill those operational characteristics. They create reusable building blocks that developers can consume.

This separation promotes consistency, reduces developer toil, and allows platform teams to evolve the underlying infrastructure without impacting developers’ application definitions.

The Pillars of OAM: Building Blocks for Applications

OAM defines several core concepts that work together to describe a complete application. Let’s explore them:

1. Application

The Application is the top-level OAM resource in KubeVela. It represents a complete, deployable application. An Application aggregates all other OAM building blocks (Components, Traits, Policies, Workflows) to define how your software runs.

It’s the single source of truth for your application’s deployment, lifecycle, and operational behaviors.

2. Components

A Component defines a core building block of your application. This could be a microservice, a database, a message queue, or even a static website. A Component typically describes the workload type and its basic configuration.

For instance, a component might specify a Docker image to run, environment variables, and resource requests. It’s the “what” of your application’s pieces.

3. Traits

Traits are operational capabilities that you attach to Components. They define how a component should behave or be operated. Think of them as modifiers that add functionality without changing the component’s core definition.

Examples of traits include:

  • scaler: To define the number of replicas for a workload.
  • ingress: To expose a service via HTTP/HTTPS.
  • autoscaler: To enable automatic scaling based on metrics.
  • rollout: To define deployment strategies like canary or blue/green.

Platform engineers define these traits, and developers simply declare which traits they need for their components.

4. Policies

Policies define guardrails and governance rules for your applications. They ensure compliance, security, and resource management across your deployments. Policies can apply to the entire application or specific components.

Examples of policies:

  • health-check: To define application health probes.
  • topology: To specify where components should be deployed (e.g., specific clusters, regions).
  • security: To enforce network policies or image scanning.

Policies are often defined by platform engineers to enforce organizational standards.

5. Workflows

Workflows define the steps involved in delivering and managing an application. They orchestrate the entire deployment process, from building and testing to deploying and releasing. Workflows are highly customizable and can include manual approvals, data transformations, or complex multi-stage rollouts.

Examples of workflow steps:

  • deploy: Deploy components to a cluster.
  • manual-approval: Pause for human intervention.
  • data-patch: Modify resources during deployment.
  • webhook: Trigger external systems.

6. Addons

Addons extend KubeVela’s capabilities by providing pre-packaged sets of components, traits, policies, and workflows. They allow KubeVela to integrate with other tools (like Argo CD, Flux, Prometheus, Grafana) or provide new application delivery features.

Addons are how KubeVela remains flexible and integrates with the broader cloud-native ecosystem.

OAM in Action: A Visual Flow

This diagram illustrates how these core OAM concepts come together within a KubeVela Application.

flowchart TD Developer[Application Developer] --> App[Application] PlatformEngineer[Platform Engineer] --> Defs[Definitions] subgraph KubeVelaAppDelivery["KubeVela Application Delivery"] App --> Components[Components] App --> Traits[Traits] App --> Policy[Policy] App --> Workflow[Workflow] end Defs --> Components Defs --> Traits Defs --> Policy Defs --> Workflow
  • Developer focuses on the Application, defining its Components and attaching desired Traits, Policies, and Workflows.
  • Platform Engineer defines the underlying Definitions (Component, Trait, Policy, Workflow definitions) and enables Addons. These definitions are the “recipes” that KubeVela uses to fulfill the developer’s requests.
  • KubeVela then uses these definitions to deliver the application according to the specified Workflows and Policies.

Step-by-Step Implementation: Your First KubeVela Application

Let’s put OAM into practice by deploying a simple “hello-world” web service using KubeVela. We’ll start with a basic component and then add operational traits incrementally.

1. Define a Simple Component

Create a file named my-first-app.yaml. We’ll start with just the Application and a single Component. This component will be a simple Nginx web server.

# my-first-app.yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-first-webapp
spec:
  components:
    - name: web-server
      type: webservice # This is a KubeVela built-in component type
      properties:
        image: nginx:1.25.3 # Using a specific Nginx version as of 2026-06-22
        port: 80

Let’s break down this small YAML:

  • apiVersion: core.oam.dev/v1beta1 and kind: Application: This identifies our resource as a KubeVela Application using the OAM API.
  • metadata.name: my-first-webapp: This gives our application a name.
  • spec.components: This section lists the building blocks of our application.
  • - name: web-server: This is our first component, named web-server.
  • type: webservice: This tells KubeVela that our component is a webservice. KubeVela comes with several built-in component types, and webservice is a common one that typically abstracts a Kubernetes Deployment and Service.
  • properties: These are the specific configurations for our webservice component.
    • image: nginx:1.25.3: Specifies the Docker image for our web server.
    • port: 80: The port our web server listens on.

Apply this application to your cluster:

kubectl apply -f my-first-app.yaml

Now, check the status of your KubeVela application:

vela status my-first-webapp

You should see output indicating the application is running and healthy:

# Example output for 'vela status my-first-webapp'
About:

  Name:         my-first-webapp
  Namespace:    default
  Created time: 2026-06-22 10:30:00 +0000 UTC
  Status:       running

Components:

  NAME        TYPE        HEALTHY STATUS  ...
  web-server  webservice  healthy         ...

Workflow:

  MODE        STATUS  STEP    MESSAGE
  DAG         succeed deploy  Workflow is finished.

Resources:

  (v1.Deployment)  web-server
  (v1.Service)     web-server

Notice that KubeVela automatically created a Kubernetes Deployment and a Service for our webservice component. We didn’t have to write any raw Kubernetes YAML for them!

2. Add a Trait: Scaling Your Component

Our web server is running, but what if we need more replicas? This is where Traits shine. Let’s add a scaler trait to specify 3 replicas.

Edit my-first-app.yaml and add the traits section under web-server:

# my-first-app.yaml (modified)
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-first-webapp
spec:
  components:
    - name: web-server
      type: webservice
      properties:
        image: nginx:1.25.3
        port: 80
      traits: # <--- New section for traits
        - type: scaler # <--- Using the built-in scaler trait
          properties:
            replicas: 3 # <--- Desired number of replicas

Apply the updated application:

kubectl apply -f my-first-app.yaml

Check the status again:

vela status my-first-webapp

You’ll see the application reconcile, and if you inspect the underlying Kubernetes resources, you’ll find the Deployment now has 3 replicas:

kubectl get deployment web-server
# Example output for 'kubectl get deployment web-server'
NAME         READY   UP-TO-DATE   AVAILABLE   AGE
web-server   3/3     3            3           2m

See how easy that was? We added a single trait line, and KubeVela handled the underlying Kubernetes Deployment changes. The developer just asks for “3 replicas,” and the platform (via KubeVela) knows how to deliver it.

3. Add Another Trait: Exposing Your Service with Ingress

Our web server is running with 3 replicas, but it’s not accessible from outside the cluster yet. Let’s add an ingress trait to expose it.

Edit my-first-app.yaml again and add another trait:

# my-first-app.yaml (modified again)
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-first-webapp
spec:
  components:
    - name: web-server
      type: webservice
      properties:
        image: nginx:1.25.3
        port: 80
      traits:
        - type: scaler
          properties:
            replicas: 3
        - type: ingress # <--- New trait for exposing the service
          properties:
            domain: my-first-app.example.com # <--- Your desired domain
            http:
              "/": 80 # <--- Route all requests to port 80 of the component

⚡ Quick Note: For this ingress trait to fully function, you’ll need an Ingress Controller (like Nginx Ingress Controller or Traefik) installed in your cluster. KubeVela will create the Ingress resource, but the controller is what makes it work. Also, my-first-app.example.com needs to resolve to your Ingress Controller’s external IP. For local testing, you might need to modify your /etc/hosts file.

Apply the updated application:

kubectl apply -f my-first-app.yaml

Check the status one last time:

vela status my-first-webapp

You’ll now see an Ingress resource listed under Resources:

# Example output for 'vela status my-first-webapp'
...
Resources:

  (v1.Deployment)  web-server
  (v1.Service)     web-server
  (v1.Ingress)     web-server-ingress # <--- New Ingress resource

You’ve successfully deployed a scalable, externally accessible web application with just a few lines of KubeVela YAML, leveraging its application-centric OAM model!

Mini-Challenge: Add a Health Check Policy

You’ve seen how to add traits. Now, let’s try adding a Policy to ensure our application is robust.

Challenge: Modify your my-first-app.yaml to include a health-check policy. This policy should define a readiness probe for your web-server component, checking the / path on port 80 every 5 seconds, with an initial delay of 5 seconds.

Hint:

  • You’ll need to add a policies section at the top level of your Application spec, similar to components.
  • Look for the health-check policy type and its properties for defining probes. KubeVela’s built-in health-check policy usually maps to Kubernetes’ readinessProbe and livenessProbe.

What to observe/learn: How policies are defined at the application level and how they influence the operational behavior of components without modifying the component’s core definition. After applying, check vela status my-first-webapp and potentially kubectl describe deployment web-server to see the added probe.

Common Pitfalls & Troubleshooting

Even with KubeVela’s simplicity, you might encounter issues. Here are a few common ones:

  1. KubeVela Controller Not Running: If vela status shows N/A for Core Version or components in vela-system are not healthy, the KubeVela controller might not be running correctly.
    • Solution: Check kubectl get pods -n vela-system for any failing pods. Use kubectl logs <pod-name> -n vela-system to inspect logs for errors. Ensure your cluster has enough resources.
  2. Application Not Reconciling: If vela status my-first-webapp shows errors or hangs in a pending state.
    • Solution: Double-check your YAML syntax. Even a small indentation error can cause issues. KubeVela’s controller logs (from the kubevela-core pod in vela-system) can provide detailed error messages.
  3. Trait/Component Type Not Found: If you get an error like “component type ‘webservice’ not found” or “trait type ‘scaler’ not found.”
    • Solution: Ensure KubeVela is correctly installed and its definitions are loaded. You can list available definitions with vela def ls. If you’re using a custom definition, make sure it’s applied to the cluster.
  4. Ingress Not Working: You’ve applied the ingress trait, but you can’t access your application from your browser.
    • Solution: Verify an Ingress Controller is running in your cluster. Check the Ingress resource created by KubeVela (kubectl get ingress web-server-ingress) for its IP/Hostname. Ensure your DNS or /etc/hosts file correctly points to the Ingress Controller’s external IP.

Summary

In this chapter, you’ve taken a significant step into the world of application delivery with KubeVela.

Here are the key takeaways:

  • KubeVela Installation: You successfully installed the vela CLI and the KubeVela control plane (v1.11.0) into your Kubernetes cluster.
  • Open Application Model (OAM): You learned that OAM is the foundational specification for KubeVela, designed to separate concerns between developers and platform engineers.
  • OAM’s Core Concepts: You explored the roles of Application, Component, Trait, Policy, Workflow, and Addon in defining and delivering applications.
  • Hands-on Application Deployment: You deployed a simple web application using KubeVela, incrementally adding scaler and ingress traits to modify its operational behavior without touching raw Kubernetes manifests.
  • Troubleshooting: You’re now aware of common pitfalls and how to approach debugging KubeVela applications.

You’ve built a solid foundation for understanding KubeVela’s application-centric approach. In the next chapter, we’ll dive deeper into how platform engineers can extend KubeVela by creating custom ComponentDefinitions and TraitDefinitions, unlocking the true power of KubeVela’s extensibility.

References

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