ComponentDefinition

defkit.NewComponent(name string) *ComponentDefinition creates a ComponentDefinition builder. Returns a fluent chain to configure the workload type, parameters, and CUE template function.

Chain Methods

Method	Description
.Description(text)	Human-readable description shown in vela show.
.Workload(apiVersion, kind)	Sets the fixed Kubernetes workload GVK. Use when the workload type is always the same (e.g., apps/v1, Deployment).
.AutodetectWorkload()	Omits workload GVK — KubeVela detects it from the template output. Use for k8s-objects, ref-objects.
.Params(params...)	Registers one or more parameter definitions built with the parameter builder functions.
.Template(func(tpl))	Assigns the CUE template function that builds runtime Kubernetes resources.
.Helper(name, param)	Registers a helper variable available inside the template function.
.CustomStatus(status)	Attaches a custom status DSL expression to the definition.
.HealthPolicy(health)	Attaches a health evaluation DSL expression. Use preset builders like DeploymentHealth().
.WithImports(imports...)	Adds CUE package import paths required by the template body.
.RawCUE(cue string)	Bypasses the builder entirely — the raw CUE string is used as-is for the definition. Use sparingly for patterns the fluent API cannot express.
.ToCue() string	Generate the CUE definition as a string.
.ToCueWithImports(imports...) string	Generate CUE with explicit import declarations appended.
.ToYAML() ([]byte, error)	Generate the Kubernetes YAML manifest for the definition CRD.
.ToParameterSchema() string	Generate only the parameter CUE block (without the full definition).

Example

Go — defkit

func Webservice() *defkit.ComponentDefinition {
    image := defkit.String("image").
        Description("Container image to run")
    replicas := defkit.Int("replicas").Default(1).
        Description("Number of replicas")

    return defkit.NewComponent("webservice").
        Description("HTTP microservice backed by a Deployment").
        Workload("apps/v1", "Deployment").
        Params(image, replicas).
        Template(webserviceTemplate)
}

func init() { defkit.Register(Webservice()) }

CUE — generated

// Generated by defkit — ComponentDefinition CUE template
parameter: {
  // +usage=Container image to run
  image:    string
  // +usage=Number of replicas
  replicas: *1 | int
}
output: {
  apiVersion: "apps/v1"
  kind: "Deployment"
  metadata: name: context.name
  spec: {
    selector: matchLabels: "app.oam.dev/component": context.name
    replicas: parameter.replicas
    template: {
      metadata: labels: "app.oam.dev/component": context.name
      spec: containers: [{
        image: parameter.image
      }]
    }
  }
}

AutodetectWorkload

Use .AutodetectWorkload() instead of .Workload() when the component template can produce different resource kinds depending on parameters (e.g., k8s-objects accepts arbitrary manifests, ref-objects references existing resources).

Go — defkit

// Use AutodetectWorkload when the output kind varies
return defkit.NewComponent("k8s-objects").
    Description("Deploy arbitrary Kubernetes resources").
    AutodetectWorkload().   // no fixed GVK — KubeVela detects
    Params(objects).
    Template(k8sObjectsTemplate)

When to use vs .Workload()

// .Workload("apps/v1", "Deployment")
// → use when the component always produces
//   exactly one fixed resource kind

// .AutodetectWorkload()
// → use when template may output multiple
//   different resource kinds, or zero
//   (k8s-objects, ref-objects patterns)

RawCUE

Use .RawCUE() to inject a raw CUE string as the template body, bypassing the fluent resource builder. Use when the CUE logic cannot be expressed with the builder DSL (e.g., highly dynamic object iteration). Mutually exclusive with .Template().

Go — defkit

rawBody := `
    outputs: {
        for i, obj in parameter.objects {
            "object-\(i)": obj
        }
    }
`

return defkit.NewComponent("k8s-objects").
    AutodetectWorkload().
    Params(objects).
    RawCUE(rawBody)   // bypasses .Template()

WithImports

Use .WithImports() when your template body references CUE standard library packages (e.g., strings, math) or custom KubeVela packages.

Go — defkit

return defkit.NewComponent("my-component").
    Description("Uses CUE strings package").
    Workload("apps/v1", "Deployment").
    WithImports("strings").  // adds: import "strings"
    Params(name).
    Template(myTemplate)

CUE — generated header

import (
    "strings"
)

// template body can now use:
//   strings.ToLower(parameter.name)

Related

• Register & Output — defkit.Register() and output methods
• TraitDefinition — patch workloads with traits
• Quick Start — end-to-end example