Imagine you’re a developer, eager to get your new microservice running on Kubernetes. You’ve written the code, but now you face the dreaded YAML jungle: Deployments, Services, Ingresses, ConfigMaps, Secrets – the list goes on. What if you could define your application in a much simpler, application-centric way?

Welcome back! In our previous discussions, we explored why KubeVela acts as an essential application delivery control plane for Kubernetes, simplifying complex deployments for platform teams and developers alike. We understood its role in abstracting away Kubernetes complexities and providing an application-centric view.

Now, it’s time to bridge theory with practice. In this chapter, you’ll learn how to define and deploy your very first application using KubeVela, focusing on its fundamental building block: the Component. By the end, you’ll have a running web service in your Kubernetes cluster, managed by KubeVela, and a clear understanding of how it simplifies your deployment workflow.

The KubeVela Component: Your Application’s Building Block

At the heart of the Open Application Model (OAM) and KubeVela lies the concept of a Component. Think of a Component as a modular, self-contained unit that represents a distinct piece of your application. This could be a microservice, a database, a message queue worker, or even a static file server.

📌 Key Idea: A KubeVela Component is an abstraction layer that empowers developers to declare what their application needs (e.g., “I need a web service running this Docker image”) without getting bogged down in the low-level Kubernetes details like Deployments, Services, or Pods. It’s the “what” of your application, not the “how.”

Why Components? The Power of Abstraction

Before KubeVela, deploying even a simple web service on Kubernetes often involved writing several verbose YAML manifests: a Deployment for the pods, a Service for network access, and perhaps an Ingress for external routing. This quickly becomes a burden, especially for application developers whose primary focus is their code, not infrastructure boilerplate.

KubeVela Components solve this challenge by introducing a powerful level of abstraction:

  • Developer Focus: Developers specify their application’s requirements in terms of high-level component types (like webservice or worker), using simple, intuitive properties such as image and port. They don’t need to know the intricacies of Kubernetes API objects.
  • Platform Engineer Control: Platform engineers define ComponentDefinitions (a concept we’ll explore in later chapters), which map these high-level component types to specific Kubernetes resources and operational best practices. This separation of concerns ensures consistency, compliance, and security across all applications.
  • Reduced Boilerplate: Developers write significantly less YAML. Instead of managing multiple Kubernetes manifests, they interact with a single, application-centric definition. This dramatically reduces the cognitive load and potential for errors.

Consider that simple web service. With raw Kubernetes, you’d define a Deployment and a Service. With KubeVela, you define a single webservice component, and KubeVela automatically provisions and manages the necessary Kubernetes resources for you. This is a game-changer for developer productivity.

Built-in Component Types for Immediate Use

KubeVela comes equipped with several useful built-in component types, ready for immediate use. These cover common application patterns:

  • webservice: Ideal for stateless web applications that require HTTP/HTTPS access. When you declare a webservice component, KubeVela typically provisions a Kubernetes Deployment to manage your application pods and a Service to expose it internally.
  • worker: Designed for background services, batch jobs, or long-running processes that don’t need direct HTTP exposure. Depending on its configuration, it might provision a Deployment or a Job.
  • raw: For scenarios where you need to directly specify a raw Kubernetes resource (e.g., a custom CRD, a specific StatefulSet) as a component. This offers maximum flexibility when you need to drop down to the Kubernetes API level.

We’ll start our hands-on journey with the webservice component, as it’s a common pattern and an excellent way to grasp KubeVela’s core abstraction.

Step-by-Step Implementation: Deploying Your First Component

Let’s get our hands dirty and deploy a simple web service using KubeVela. This will solidify your understanding of components in action.

1. Prerequisites Check

Before proceeding, ensure you have the following:

  • A running Kubernetes cluster: This could be a local cluster (like Kind or Minikube) or a cloud-managed Kubernetes service (e.g., GKE, EKS, AKS).
  • kubectl configured: Your kubectl command-line tool must be configured to access your Kubernetes cluster. You can verify this by running:
    kubectl cluster-info
    You should see information about your cluster, indicating a successful connection.

2. Install the KubeVela CLI (Vela CLI)

The vela CLI is your primary interface for interacting with KubeVela. It allows you to install KubeVela, deploy applications, check their status, and manage component definitions.

As of 2026-06-22, we’ll install vela CLI version 1.12.0. Please always check the official KubeVela documentation for the absolute latest stable release if 1.12.0 is outdated.

# For Linux/macOS users:
curl -fsSL https://kubevela.io/script/install.sh | bash

# For Windows users (using PowerShell):
# Invoke-WebRequest -Uri https://kubevela.io/script/install.ps1 -OutFile install.ps1; .\install.ps1; Remove-Item install.ps1

After installation, it’s good practice to verify that the vela CLI is correctly installed and accessible in your path:

vela version

You should see output similar to this, confirming the CLI version:

CLI Version: v1.12.0 # (Or the specific version you installed)
GitCommit:   a1b2c3d
...

3. Install KubeVela into Your Cluster

Now that you have the vela CLI, let’s install the KubeVela control plane into your Kubernetes cluster. This process deploys the core KubeVela components (like the controller and webhook) into a dedicated namespace, typically vela-system.

vela install --version v1.12.0 # Assuming v1.12.0 is the current stable version as of 2026-06-22

The installation might take a few minutes, as KubeVela sets up its custom resource definitions (CRDs) and deploys its controller. Once the command completes, you can verify that KubeVela’s components are running:

kubectl get pods -n vela-system

You should observe several pods in the Running state, including vela-core, vela-cluster-gateway, and potentially others, indicating a healthy KubeVela control plane.

4. Defining Your First Application

In KubeVela, applications are defined using the Application Custom Resource. This is the top-level object that acts as the blueprint for your entire application, orchestrating its components, traits, policies, and workflows.

Let’s create a file named my-first-app.yaml with the following content. This YAML defines a simple web service.

# my-first-app.yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-first-webapp
spec:
  components:
    - name: welcome-service
      type: webservice
      properties:
        image: oamdev/hello-world
        port: 8000

Let’s dissect this YAML manifest line by line to understand what each part means:

  • apiVersion: core.oam.dev/v1beta1: This line specifies the API version for the Application resource. KubeVela leverages the Open Application Model (OAM) specification, which defines these core APIs.
  • kind: Application: This crucial line tells Kubernetes that we are defining an Application resource, which KubeVela’s controller is designed to understand and manage.
  • metadata:: This standard Kubernetes section holds metadata about our resource.
    • name: my-first-webapp: This is the unique name of our KubeVela application within the cluster.
  • spec:: This is where the core definition of our application’s desired state resides.
    • components:: This is a list where we define all the individual components that comprise our application. In this simple example, we have just one.
      • - name: welcome-service: This is the logical name for our specific component within the my-first-webapp application.
      • type: webservice: This is a key declaration! We’re telling KubeVela that this component is of the webservice type. KubeVela, through its pre-defined ComponentDefinitions, knows how to translate a webservice into concrete Kubernetes resources like a Deployment and a Service.
      • properties:: These are the specific configuration parameters that are relevant to our webservice component type.
        • image: oamdev/hello-world: This specifies the Docker image that our web service will run. oamdev/hello-world is a lightweight Go application that serves a simple “Hello KubeVela” message.
        • port: 8000: This defines the port on which our web service inside the container will listen. KubeVela will configure the Kubernetes Service to expose this port.

5. Deploying the Application

With our my-first-app.yaml file prepared, it’s time to deploy it using the vela CLI:

vela up -f my-first-app.yaml

You’ll see output indicating the application is being deployed. The vela up command is KubeVela’s intelligent way to apply or update an application definition. It figures out what underlying Kubernetes resources need to be created, updated, or deleted based on your Application manifest.

6. Verifying the Deployment

Once deployed, KubeVela will spring into action, provisioning the underlying Kubernetes resources. You can check the status of your KubeVela application to observe its progress:

vela status my-first-webapp

You should see output similar to this (it might take a few moments for all resources to become ready):

About this application:

  Name:         my-first-webapp
  Namespace:    default
  Created time: 2026-06-22 10:00:00 +0000 UTC
  Updated time: 2026-06-22 10:00:05 +0000 UTC

Components:

  - Name: welcome-service
    Type: webservice
    Health Status: Healthy
    Traits:
    Resources:
      - Kind: Deployment
        Name: welcome-service
      - Kind: Service
        Name: welcome-service

Notice the power of KubeVela here: it explicitly tells you that it created a Deployment and a Service for our single webservice component! This is the abstraction in action.

You can also use kubectl to directly inspect the underlying Kubernetes resources that KubeVela created:

kubectl get deployment,service -l app.oam.dev/name=my-first-webapp

You should find a Deployment and a Service, both named welcome-service, demonstrating KubeVela’s orchestration.

To access your newly deployed web service, you can use kubectl port-forward:

kubectl port-forward service/welcome-service 8080:8000

Now, open your web browser and navigate to http://localhost:8080. You should proudly see the “Hello KubeVela!” message.

⚡ Real-world insight: This simple webservice component effectively replaces at least two distinct Kubernetes manifests (Deployment and Service), abstracting away the boilerplate. For developers, this means less YAML to write, fewer Kubernetes concepts to master, and a clearer focus on their application’s logic.

Mini-Challenge: Customize Your Web Service

Now that you’ve successfully deployed your first KubeVela application, let’s make a small change to solidify your understanding of updates.

Challenge: Modify the my-first-app.yaml file to use a different Docker image and expose it on a different port.

  • Try using nginxdemos/hello as the image. This is a simple Nginx server that serves “Hello Nginx!”.
  • Change the port to 80.

Hint: You only need to modify the properties section of your welcome-service component.

Here’s how your modified my-first-app.yaml should look:

# my-first-app.yaml (modified)
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-first-webapp
spec:
  components:
    - name: welcome-service
      type: webservice
      properties:
        image: nginxdemos/hello # Changed image
        port: 80              # Changed port

After modifying the file, apply the changes using the vela CLI, just like you did for the initial deployment:

vela up -f my-first-app.yaml

What to observe/learn:

  1. How quickly KubeVela detects the changes and initiates an update.
  2. After the update, check vela status my-first-webapp again. Does it show Healthy?
  3. Port-forward to the new port (kubectl port-forward service/welcome-service 8080:80).
  4. Visit http://localhost:8080 in your browser. Do you see “Hello Nginx!”?

This exercise demonstrates the agility of KubeVela’s application-centric approach. You made a simple change to your high-level application definition, and KubeVela intelligently handled the underlying Kubernetes resource updates (e.g., performing a rolling update of the Deployment) for you.

Common Pitfalls & Troubleshooting

Even with KubeVela’s streamlined approach, you might encounter issues. Here are a few common mistakes and how to debug them:

  • YAML Syntax Errors: KubeVela, like Kubernetes, is very strict about YAML formatting. A small indentation error, a misplaced dash, or a missing colon can cause parsing failures.
    • Solution: Use a YAML linter (many IDEs like VS Code have excellent YAML extensions) or carefully review your file for syntax. The vela up command will usually provide helpful error messages indicating the line number where the issue occurred.
  • Image Pull Failures: If your specified Docker image doesn’t exist, is misspelled, or requires authentication (and credentials aren’t provided), your pods won’t start successfully.
    • Solution: Check kubectl describe pod <pod-name> for events related to ImagePullBackOff or ErrImagePull. Ensure the image name is correct and accessible from your cluster.
  • vela status shows Running but Health Status is Unhealthy: This indicates that while KubeVela has successfully deployed the underlying Kubernetes resources, the application inside your pods isn’t ready or healthy according to its defined health checks.
    • Solution: Use kubectl logs <pod-name> to check your application’s logs for any runtime errors. Additionally, vela status my-first-webapp --debug can provide more verbose insights into the component’s health status and any associated issues.
  • vela up fails with connection errors: This typically means your kubectl context isn’t correctly pointing to a running Kubernetes cluster, or KubeVela itself isn’t fully installed or healthy in the vela-system namespace.
    • Solution: Verify your cluster connection with kubectl cluster-info and check the health of the KubeVela control plane with kubectl get pods -n vela-system.

⚠️ What can go wrong: Always remember that KubeVela builds on top of Kubernetes. If your underlying Kubernetes cluster has networking issues, resource constraints, or misconfigured storage, KubeVela applications will also be affected. KubeVela simplifies the definition and delivery but doesn’t magically fix fundamental cluster problems.

Summary

Congratulations! You’ve successfully deployed your first application using KubeVela and truly experienced its core abstraction. Here are the key takeaways from this chapter:

  • Components are the core: They are the fundamental building blocks of your application in KubeVela, abstracting away low-level Kubernetes details like Deployments and Services.
  • The Application CRD: This is KubeVela’s top-level resource, serving as the single source of truth for defining your entire application, including its components.
  • webservice component type: A powerful built-in component that allows developers to quickly define stateless web applications with minimal configuration.
  • The vela CLI: Your essential command-line companion for installing KubeVela, deploying applications, and efficiently checking their status.
  • Simplified Application Delivery: KubeVela significantly reduces the complexity of deploying and managing applications by providing an application-centric abstraction, empowering developers to focus on their code.

You’ve seen how KubeVela empowers developers to focus on their application code and configuration, while the platform handles the underlying infrastructure intricacies. This separation of concerns is crucial for modern, scalable application delivery.

In the next chapter, we’ll dive deeper into enhancing these components by attaching Traits. Traits allow you to add operational capabilities like scaling, ingress exposure, and more, without modifying the component’s core definition, further extending KubeVela’s flexibility and power.

References

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