Empowering Platform Engineers: Customizing KubeVela with Definitions and Addons

Welcome back, intrepid platform builder! In our journey through KubeVela, we’ve explored its core application model and how it simplifies deployments for developers. But what if the built-in components and traits aren’t enough for your organization’s unique needs? What if you have a proprietary service or a specific operational pattern you want to expose to developers without them needing to touch raw Kubernetes?

This chapter is your deep dive into KubeVela’s extensibility. We’ll uncover how platform engineers wield the power of Definitions (for Components, Traits, Policies, and Workflows) and Addons to tailor KubeVela precisely to their platform’s requirements. By the end, you’ll understand not just how to extend KubeVela, but why it’s a game-changer for building truly self-service, opinionated platforms.

The “Why” of Extensibility: Beyond Off-the-Shelf

Imagine your developers need to deploy an application that automatically integrates with your internal monitoring system and gets a specific type of database provisioned. With raw Kubernetes, they’d write multiple YAML manifests, possibly ConfigMaps, Secrets, and ServiceMonitors, each with intricate configurations. This is tedious, error-prone, and requires deep Kubernetes knowledge.

KubeVela’s built-in components and traits abstract many common patterns, but they can’t cover every unique system or operational requirement of your specific organization. This is where extensibility shines.

Platform engineers need the ability to:

• Encapsulate Operational Best Practices: Define custom components that deploy applications according to organizational standards (e.g., specific sidecars, security policies).
• Integrate with Internal Systems: Connect applications seamlessly with proprietary monitoring, logging, or secret management solutions.
• Simplify Developer Experience: Provide developers with high-level, application-centric abstractions that hide underlying complexity, letting them focus on business logic.
• Standardize Delivery Workflows: Define custom steps in application delivery workflows to enforce specific deployment, testing, or approval gates.

KubeVela’s extensibility mechanisms empower platform teams to be the architects of their application delivery experience, providing a curated catalog of capabilities that developers can consume with ease.

KubeVela’s Extensibility Foundation: Open Application Model (OAM) and CUE

At the heart of KubeVela’s extensibility are the Definitions that enable you to extend the Open Application Model (OAM). These definitions are Kubernetes Custom Resource Definitions (CRDs) that KubeVela understands. They tell KubeVela how to translate a high-level application description into concrete Kubernetes resources.

The magic behind these definitions is often powered by CUE. CUE is an open-source language, a superset of JSON, designed for defining, generating, and validating configurations. KubeVela leverages CUE to:

• Define Schema: Specify the valid parameters and types for your custom components, traits, policies, and workflow steps. This ensures developers provide correct inputs.
• Generate Kubernetes Manifests: Dynamically create the underlying Kubernetes YAML based on the developer’s inputs and your platform’s logic.
• Validate Configuration: Enforce constraints and rules, preventing invalid deployments before they even hit the cluster.

Using CUE within definitions allows platform engineers to embed sophisticated logic and validation directly into their platform capabilities. This shifts the burden of knowing Kubernetes internals from developers to the platform, making the developer experience much smoother and more reliable.

Unpacking Definitions: Component, Trait, Policy, and WorkflowStep

KubeVela provides four primary types of Definitions for extensibility, each targeting a different aspect of the application delivery lifecycle:

1. ComponentDefinition:

   • What it is: Defines a new type of component that developers can use in their Application manifests. A component describes the core workload (e.g., a web service, a batch job).
   • Why it exists: To abstract how a specific type of workload is deployed. For example, you could define a MyWebService component that always deploys a Deployment, Service, and Ingress with specific defaults and sidecars.
   • How it works: It contains a CUE template that takes parameters from the developer’s Application and renders the necessary Kubernetes resources.

2. TraitDefinition:

   • What it is: Defines a new operational capability that can be attached to a component. Traits modify or augment components (e.g., scaling, exposing, monitoring).
   • Why it exists: To separate operational concerns from the core workload definition. This allows platform engineers to provide reusable “add-ons” that developers can mix and match.
   • How it works: It takes parameters from the Application’s trait configuration and the component’s generated resources, then renders additional Kubernetes resources or modifies existing ones.

3. PolicyDefinition:

   • What it is: Defines a new type of policy that can be applied to an Application or parts of it. Policies enforce governance, security, or compliance rules.
   • Why it exists: To allow platform engineers to codify and enforce organizational rules across applications, such as resource quotas, network access, or deployment windows.
   • How it works: It specifies validation logic and/or triggers actions based on the application’s configuration or cluster state.

4. WorkflowStepDefinition:

   • What it is: Defines a new custom step that can be used within an Application’s workflow. Workflows orchestrate the delivery process.
   • Why it exists: To enable platform engineers to build highly customized, multi-stage delivery pipelines directly within KubeVela, integrating with external systems or internal tools.
   • How it works: It specifies the logic for a particular step, which can involve running scripts, calling APIs, or waiting for conditions, often leveraging CUE or even Go templates.

Step-by-Step Implementation: Crafting a Custom Trait for Internal Monitoring

Let’s walk through creating a simple TraitDefinition that automatically injects a ConfigMap into a component to configure an imaginary internal monitoring agent. This trait will be called internal-monitor.

Prerequisites: Before we start, ensure you have KubeVela installed on your Kubernetes cluster. If you followed previous chapters, you should be all set. We’re assuming KubeVela v1.14.0 as of 2026-06-22 for this example.

Step 1: Define the Basic TraitDefinition Structure

First, let’s create a file named trait-internal-monitor.yaml. We’ll start with the standard Kubernetes object definition and KubeVela-specific metadata.

# trait-internal-monitor.yaml
apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
  name: internal-monitor
  annotations:
    definition.oam.dev/description: "Injects an internal monitoring agent configuration ConfigMap."
spec:
  appliesToWorkloads:
    - deployments.apps
    - statefulsets.apps
  schematic:
    cue:
      template: |
        #CUE_DEFINITION_TEMPLATE
        // The CUE template will go here, piece by piece.

Explanation:

• apiVersion and kind: Standard Kubernetes API version and resource type for a TraitDefinition.
• metadata.name: This is the name developers will use to refer to your custom trait in their Application manifests (e.g., type: internal-monitor).
• annotations: Provides a helpful description, which KubeVela UI tools can use.
• spec.appliesToWorkloads: This is critical! It tells KubeVela that this trait can be applied to workloads that result in Kubernetes Deployment or StatefulSet resources. If a developer tries to apply it to an unsupported workload, KubeVela will prevent it.
• spec.schematic.cue.template: This section is where we’ll write our CUE logic. The #CUE_DEFINITION_TEMPLATE comment is a KubeVela convention to mark the start of the CUE template.

Step 2: Define the Trait’s Parameters

Next, let’s add the parameter block inside the cue.template. This defines what inputs a developer can provide when using our internal-monitor trait.

# trait-internal-monitor.yaml (updated)
apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
  name: internal-monitor
  annotations:
    definition.oam.dev/description: "Injects an internal monitoring agent configuration ConfigMap."
spec:
  appliesToWorkloads:
    - deployments.apps
    - statefulsets.apps
  schematic:
    cue:
      template: |
        #CUE_DEFINITION_TEMPLATE
        parameter: {
          // The name of the monitoring agent
          agentName: string @default("vela-monitor")
          // The endpoint for the monitoring agent to send data
          agentEndpoint: string @default("http://monitor-server.internal:8080")
          // Labels to add to the ConfigMap
          labels?: [string]: string
        }
        // ... rest of the CUE template will follow

Explanation:

• parameter: This CUE block defines the schema for the trait’s configuration.
• agentName: string @default("vela-monitor"): Defines a required string parameter named agentName with a default value.
• agentEndpoint: string @default("http://monitor-server.internal:8080"): Similar to agentName, for the monitoring server’s URL.
• labels?: [string]: string: Defines an optional map (? makes it optional) where keys and values are strings. This allows developers to add custom labels to the generated ConfigMap.
• KubeVela automatically generates a Kubernetes CRD schema from this parameter block, ensuring developers get validation for their inputs.

Step 3: Access the Workload and Define Output Resources

Now, let’s add the logic to access the underlying workload’s pod specification and define the ConfigMap we want to create.

# trait-internal-monitor.yaml (updated)
apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
  name: internal-monitor
  annotations:
    definition.oam.dev/description: "Injects an internal monitoring agent configuration ConfigMap."
spec:
  appliesToWorkloads:
    - deployments.apps
    - statefulsets.apps
  schematic:
    cue:
      template: |
        #CUE_DEFINITION_TEMPLATE
        parameter: {
          agentName: string @default("vela-monitor")
          agentEndpoint: string @default("http://monitor-server.internal:8080")
          labels?: [string]: string
        }

        // We process the existing workload (component) here.
        // `context.output` refers to the primary Kubernetes resource generated by the component
        // (e.g., a Deployment). We access its PodSpec.
        workload: context.output.spec.template.spec

        // Define the ConfigMap to be created
        outputs: internalMonitorConfig: {
          apiVersion: "v1"
          kind: "ConfigMap"
          metadata: {
            name: context.name + "-monitor-config" // Dynamically name the ConfigMap
            labels: parameter.labels | {} // Merge with any provided labels or use an empty map
          }
          data: {
            "monitor-agent.conf": """
              agent.name: \(parameter.agentName)
              agent.endpoint: \(parameter.agentEndpoint)
              # Other internal monitoring specific configurations can go here
              """
          }
        }
        // ... injection logic will follow

Explanation:

• workload: context.output.spec.template.spec: This line is crucial for traits. context.output represents the main Kubernetes resource generated by the component (e.g., the Deployment). We navigate to its spec.template.spec to get to the PodSpec, which contains volumes and containers.
• outputs: internalMonitorConfig: This CUE block declares a new Kubernetes resource that KubeVela should create.
  • apiVersion, kind: Standard fields for a ConfigMap.
  • metadata.name: context.name + "-monitor-config": We dynamically generate the ConfigMap’s name using context.name (which is the component’s name) to ensure it’s unique and related to the application.
  • labels: parameter.labels | {}: This uses CUE’s | (union) operator. It means “use the labels provided by parameter.labels if they exist, otherwise use an empty map {}.”
  • data: This holds the actual content of our configuration file. Notice the """ for multi-line strings and \(...) for string interpolation, allowing us to embed parameter.agentName and parameter.agentEndpoint directly.

Step 4: Inject Volumes and Volume Mounts into the Workload

Finally, we’ll modify the workload (the PodSpec) to inject our newly defined ConfigMap as a volume and mount it into the application containers.

# trait-internal-monitor.yaml (updated)
apiVersion: core.oam.dev/v1beta1
kind: TraitDefinition
metadata:
  name: internal-monitor
  annotations:
    definition.oam.dev/description: "Injects an internal monitoring agent configuration ConfigMap."
spec:
  appliesToWorkloads:
    - deployments.apps
    - statefulsets.apps
  schematic:
    cue:
      template: |
        #CUE_DEFINITION_TEMPLATE
        parameter: {
          agentName: string @default("vela-monitor")
          agentEndpoint: string @default("http://monitor-server.internal:8080")
          labels?: [string]: string
        }

        workload: context.output.spec.template.spec

        outputs: internalMonitorConfig: {
          apiVersion: "v1"
          kind: "ConfigMap"
          metadata: {
            name: context.name + "-monitor-config"
            labels: parameter.labels | {}
          }
          data: {
            "monitor-agent.conf": """
              agent.name: \(parameter.agentName)
              agent.endpoint: \(parameter.agentEndpoint)
              # Other internal monitoring specific configurations
              """
          }
        }

        // Now, we need to inject this ConfigMap as a volume and volumeMount
        // into the workload's pod template.

        // Add a new volume to the workload's PodSpec
        workload.volumes: [... (workload.volumes or []), {
          name: "monitor-config-volume"
          configMap: {
            name: outputs.internalMonitorConfig.metadata.name // Reference our generated ConfigMap
          }
        }]

        // Iterate through all containers and add a volumeMount
        workload.containers: [ for container in workload.containers {
          name: container.name
          volumeMounts: [... (container.volumeMounts or []), {
            name: "monitor-config-volume"
            mountPath: "/etc/monitor-agent"
            readOnly: true
          }]
          // Optional: Inject an environment variable to point to the config
          env: [... (container.env or []), {
            name: "MONITOR_AGENT_CONFIG_PATH"
            value: "/etc/monitor-agent/monitor-agent.conf"
          }]
          // This CUE idiom copies all other fields from the original container,
          // ensuring we only add to it, not overwrite.
          _other: container
        }]

Explanation of Injection Logic:

• workload.volumes: [... (workload.volumes or []), { ... }]: This line adds a new volume definition to the PodSpec.
  • ...: This is CUE’s “list comprehension” or “splat” operator, used here to merge lists. It ensures that if workload.volumes already exists, our new volume is appended without overwriting existing ones. If workload.volumes is null or undefined, (workload.volumes or []) provides an empty list to start with.
  • The new volume is named monitor-config-volume and references our dynamically created ConfigMap by name.
• workload.containers: [ for container in workload.containers { ... }]: This is a CUE list comprehension. It iterates over each container already defined in the PodSpec. For each container:
  • name: container.name: We explicitly keep the container’s original name.
  • volumeMounts: [... (container.volumeMounts or []), { ... }]: Similar to volumes, we append a new volumeMount for our monitor-config-volume to the container’s existing volume mounts. It specifies the mountPath inside the container.
  • env: [... (container.env or []), { ... }]: We also add an environment variable MONITOR_AGENT_CONFIG_PATH to tell the agent where its configuration file is located.
  • _other: container: This is a powerful CUE idiom. It tells CUE to include all other fields from the original container object that we haven’t explicitly mentioned or modified. This prevents us from accidentally removing important container properties (like image, ports, args, etc.).

Step 5: Deploy the TraitDefinition

Now that our TraitDefinition is complete, save the trait-internal-monitor.yaml file and apply it to your Kubernetes cluster using kubectl.

kubectl apply -f trait-internal-monitor.yaml

You should see output similar to:

traitdefinition.core.oam.dev/internal-monitor created

This command creates a new CustomResourceDefinition (CRD) in your cluster, making KubeVela aware of your custom internal-monitor trait.

Step 6: Create an Application Using Your Custom Trait

With the TraitDefinition deployed, developers can now use type: internal-monitor in their Application manifests. Create a new file named application-with-custom-trait.yaml:

# application-with-custom-trait.yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-monitored-app
spec:
  components:
    - name: my-backend
      type: webservice # A built-in KubeVela component type
      properties:
        image: crccheck/hello-world:1.0
        port: 8000
      traits:
        - type: internal-monitor # Our custom trait!
          properties:
            agentName: "my-custom-agent"
            labels:
              app: my-backend
              environment: dev
        - type: ingress # Another built-in trait for exposing via Ingress
          properties:
            domain: my-monitored-app.example.com
            http:
              "/": 8000

Explanation:

• We define an Application with a webservice component named my-backend.
• Crucially, under traits, we specify type: internal-monitor.
• Under properties for our custom trait, we provide values for agentName and labels, demonstrating how developers configure the trait.

Deploy this application:

kubectl apply -f application-with-custom-trait.yaml

Step 7: Verify the Deployed Resources

After the application is deployed, let’s inspect the generated Kubernetes resources to see the effect of our custom trait:

# Get the KubeVela application status
kubectl get app my-monitored-app -o yaml

# Get the Deployment created by the webservice component
kubectl get deployment my-monitored-app-my-backend -o yaml

# Get the ConfigMap created by our custom internal-monitor trait
kubectl get configmap my-monitored-app-my-backend-monitor-config -o yaml

You’ll observe that KubeVela has:

1. Created a Deployment for my-backend.
2. Created a ConfigMap named my-monitored-app-my-backend-monitor-config with the agentName and labels you specified in the Application manifest.
3. Injected a volume and volume mount for this ConfigMap into the Deployment’s pod template.
4. Added the MONITOR_AGENT_CONFIG_PATH environment variable to the container.

All of this was achieved by simply adding type: internal-monitor to the application’s traits, abstracting away the underlying Kubernetes details from the developer! This is the power of KubeVela definitions.

The Power of Addons: Packaging KubeVela Extensions

While Definitions allow you to create individual custom capabilities, Addons are KubeVela’s way of bundling and distributing a collection of related capabilities. An Addon can contain:

• Multiple ComponentDefinitions, TraitDefinitions, PolicyDefinitions, WorkflowStepDefinitions.
• Helm charts for deploying controllers or operators that support these definitions.
• Raw Kubernetes manifests for other resources (e.g., Namespace, ServiceAccount).
• Even other custom resources.

Why Addons matter:

• Discoverability: Addons provide a centralized, versioned way to share and consume complex KubeVela extensions.
• Ease of Installation: Platform engineers can install a whole suite of features with a single command.
• Version Management: Addons can be versioned, allowing for controlled updates and rollbacks.
• Ecosystem: They foster an ecosystem where community and vendors can contribute ready-to-use platform capabilities.

For example, a “GitOps” Addon might include WorkflowStepDefinitions for interacting with Git repositories, PolicyDefinitions for enforcing GitOps principles, and even a Helm chart for deploying Argo CD or Flux CD if not already present.

You can browse available KubeVela addons and install them using the vela addon CLI command.

# List available addons
vela addon list

# Enable an addon (e.g., the velaux addon for the UI)
# Using KubeVela v1.14.0 as of 2026-06-22
vela addon enable velaux --version 1.14.0

# Disable an addon
vela addon disable velaux

⚡ Real-world insight: Platform teams often start with custom definitions for their unique needs, then package them into internal Addons for easier distribution and management across different environments or teams. This makes onboarding new projects or teams much more efficient and ensures consistency.

Comparing KubeVela Extensibility

Let’s briefly compare KubeVela’s extensibility model with other common approaches:

KubeVela’s approach offers a sweet spot: powerful extensibility for platform engineers without requiring them to write full-blown Kubernetes controllers in Go, while still providing developers with a clean, application-centric interface.

Mini-Challenge: Create a Custom ComponentDefinition

Now it’s your turn!

Challenge: Create a ComponentDefinition for a simple “Batch Job” that deploys a Kubernetes Job resource. This component should accept the following parameters:

• image: The container image for the job (string).
• command: A list of strings for the command to run (e.g., ["/bin/sh", "-c", "echo Hello && sleep 10"]).
• backoffLimit: The number of retries before considering a job failed (integer, default to 3).
• activeDeadlineSeconds: The maximum time (in seconds) the job may be active before it is terminated (integer, optional).

After defining and applying the ComponentDefinition, create an Application that uses your new batch-job component type to run a simple echo command.

Hint:

• Start with a ComponentDefinition YAML structure, similar to our TraitDefinition.
• Inside spec.schematic.cue.template, define your parameter block with the specified inputs.
• Then, define the outputs block to render a Job resource. Remember to use context.name for the Job’s metadata.name.
• For the Job’s spec.template.spec.containers section, use the image and command from your parameters.
• Don’t forget to include backoffLimit and activeDeadlineSeconds in the Job spec. For activeDeadlineSeconds, remember it’s optional, so you might use a CUE conditional or a default of _ (undefined) if not provided.

What to observe/learn: Pay attention to how the CUE template directly maps your high-level component parameters into the specific fields of the Kubernetes Job resource. This is the core of abstracting Kubernetes complexity for developers.

Common Pitfalls & Troubleshooting

1. CUE Syntax Errors: CUE is strict about syntax and types. Even a misplaced comma or incorrect indentation can lead to validation failures.
   • Troubleshooting: Use a CUE linter or validator (e.g., cue vet or an IDE plugin) to check your CUE template before applying. The KubeVela CLI also provides vela def vet for validating definitions, which is highly recommended.
2. Incorrect appliesToWorkloads: If your TraitDefinition doesn’t list the correct workload types in appliesToWorkloads, KubeVela won’t be able to attach the trait to the component, resulting in validation errors or the trait simply not applying.
   • Troubleshooting: Double-check the apiVersion.kind of the underlying Kubernetes resources your components generate (e.g., deployments.apps, statefulsets.apps). You can find these by inspecting the WorkloadDefinition of built-in components or the actual Kubernetes resources created.
3. Missing context.output Reference (for Traits): When writing CUE for traits, you often need to modify the primary resource generated by the component. Forgetting to reference context.output or referencing it incorrectly can lead to errors.
   • Troubleshooting: Remember context.output holds the primary resource. For a Deployment, its PodSpec is typically at context.output.spec.template.spec. Use vela def render with an example application to see the intermediate output.
4. Addon Installation Issues: Sometimes addons fail to enable due to network issues, missing CRDs, or conflicts with existing resources.
   • Troubleshooting: Use vela addon status <addon-name> to get detailed information about the addon’s state. Check the KubeVela controller logs for more specific errors. You can usually find controller logs by kubectl logs -n vela-system deploy/vela-core.

Summary

Congratulations! You’ve navigated the powerful world of KubeVela extensibility. By now, you should have a solid understanding of:

• Why extensibility is vital for platform engineers to build opinionated, developer-friendly platforms.
• The role of the Open Application Model (OAM) and CUE in defining and rendering custom capabilities.
• The four primary types of Definitions (ComponentDefinition, TraitDefinition, PolicyDefinition, WorkflowStepDefinition) and their distinct purposes.
• How to craft a custom TraitDefinition to inject functionality into application components, abstracting Kubernetes details with CUE.
• The value of Addons for packaging and distributing collections of KubeVela extensions.
• How KubeVela’s extensibility compares to other Kubernetes ecosystem tools.

You’ve moved beyond merely using KubeVela to shaping it, empowering your platform team to deliver a truly tailored application experience.

In the next chapter, we’ll explore advanced deployment strategies and GitOps integration, bringing together the power of KubeVela’s application model with modern continuous delivery practices.

References

• KubeVela Official Documentation (KubeVela v1.14.0)
• KubeVela Addons Overview (KubeVela v1.14.0)
• CUE Language Official Documentation
• KubeVela OAM Model for Platform Engineers (KubeVela v1.14.0)
• KubeVela Policy Definition (KubeVela v1.14.0)

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