Skip to main content
Version: Next

Integration

defkit integrates with the KubeVela ecosystem through well-defined extension points. Each definition type maps to a Kubernetes CRD managed by the KubeVela controller.

Definition Types​

Definition TypeAPI GroupPurpose
ComponentDefinitioncore.oam.dev/v1beta1Defines a workload type. Maps Go template to Kubernetes resources (Deployment, StatefulSet, Job, etc.). End users reference by name in Application YAML.
TraitDefinitioncore.oam.dev/v1beta1Patches or augments a workload. Uses CUE patch semantics to modify the primary output (e.g., inject env vars, set replica count, add sidecars).
PolicyDefinitioncore.oam.dev/v1alpha1Controls deployment topology and behavior. Used for multi-cluster override, garbage collection rules, and apply-once semantics.
WorkflowStepDefinitioncore.oam.dev/v1beta1Defines automation steps for the application workflow engine. Steps run sequentially or in parallel as part of Application deployment.

go.mod Setup​

Add defkit as a dependency using the KubeVela module:

go get github.com/oam-dev/kubevela/pkg/definition/defkit

A typical go.mod for a definition module:

module my-platform

go 1.21

require (
    github.com/oam-dev/kubevela v1.9.0
)
info

The repository uses a replace directive in go.mod pointing to a custom KubeVela fork when working from the vela-go-definitions reference implementation. Check the upstream module's go.mod for the exact version pin.

Package Structure​

Organize definitions by type in separate packages. Each package registers its definitions via init():

my-platform/
├── module.yaml
├── go.mod
├── cmd/
│   └── register/
│       └── main.go      # Entry point — blank-imports all packages
├── components/
│   └── webservice.go    # package components
├── traits/
│   └── env.go           # package traits
├── policies/
│   └── apply-once.go    # package policies
└── workflowsteps/
    └── deploy.go        # package workflowsteps

The cmd/register/main.go Pattern​

The entry point binary aggregates all definitions by blank-importing each package. Blank imports trigger the init() function in each package, which calls defkit.Register(). The main() function then calls defkit.ToJSON() to emit all registered definitions as JSON for the vela def apply-module command to consume.

cmd/register/main.go
package main

import (
    "fmt"
    "github.com/oam-dev/kubevela/pkg/definition/defkit"

    // Blank imports trigger init() in each package,
    // registering all definitions automatically
    _ "my-platform/components"
    _ "my-platform/traits"
    _ "my-platform/policies"
    _ "my-platform/workflowsteps"
)

func main() {
    // Exports all registered definitions as JSON
    fmt.Println(defkit.ToJSON())
}

Health Evaluation​

defkit's Health DSL generates status.customStatus and status.healthPolicy CUE blocks. The controller determines component health from these. Use preset builders like DeploymentHealth() or provide a custom health policy expression.

vela CLI Integration​

The vela def subcommands handle compilation, validation, and deployment:

CommandPurpose
vela def validate-module ./my-platformValidate the Go module compiles and generates valid CUE
vela def list-module ./my-platformList all definitions in the module
vela def gen-module ./my-platform -o ./outGenerate raw CUE files for inspection
vela def apply-module ./my-platform --dry-runPreview what would be applied
vela def apply-module ./my-platform --conflict overwriteApply all definitions to the cluster

apply-module compiles Go → CUE → YAML and applies to the cluster in one step.