Version: Next

VelaCtx — Runtime Context

defkit.VelaCtx() returns a KubeVela context accessor that compiles to CUE context.* references, evaluated by the controller at deploy time.

`defkit.VelaCtx() *VelaContext`

Call at the top of your template function or definition constructor. Each method returns a Value that produces the corresponding context.* CUE path.

Go — defkit
vela := defkit.VelaCtx()

vela.Name()                    // component name
vela.AppName()                 // application name
vela.Namespace()               // namespace
vela.Revision()                // revision name
vela.ClusterVersion().Minor()  // cluster minor version (int)

CUE — generated
vela.Name()                   → context.name
vela.AppName()                → context.appName
vela.Namespace()              → context.namespace
vela.Revision()               → context.revision
vela.ClusterVersion().Minor() → context.clusterVersion.minor

Context Fields Reference

Go method	CUE path	Description
`vela.Name()`	`context.name`	Component or trait instance name as declared in the Application YAML.
`vela.Namespace()`	`context.namespace`	Namespace where the Application is deployed.
`vela.AppName()`	`context.appName`	The Application CR's name. Different from `Name()` which is the component name.
`vela.AppRevision()`	`context.appRevision`	The Application's current revision string (e.g. `"myapp-v3"`).
`vela.AppRevisionNum()`	`context.appRevisionNum`	The numeric revision counter.
`vela.Revision()`	`context.revision`	The component's own revision string. Tracks individual component changes.
`vela.ClusterVersion()`	`context.clusterVersion`	Returns a `*ClusterVersionRef` for the target cluster's K8s version.
`vela.Output()`	`context.output`	References the primary output resource. Use in traits to read the component's output or in status expressions.
`vela.Outputs(name)`	`context.outputs.<name>`	References a named auxiliary output. Use to read status of secondary resources.

ClusterVersionRef Methods

Method	CUE path	Description
`.Major()`	`context.clusterVersion.major`	K8s major version.
`.Minor()`	`context.clusterVersion.minor`	K8s minor version — most commonly used for feature gating.
`.Patch()`	`context.clusterVersion.patch`	K8s patch version.
`.GitVersion()`	`context.clusterVersion.gitVersion`	Full git version string.

Usage in Resource Fields

The most common use of VelaCtx is setting metadata on generated resources:

Go — defkit
vela := defkit.VelaCtx()

resource := defkit.NewResource("apps/v1", "Deployment").
    Set("metadata.name", vela.Name()).
    Set("metadata.namespace", vela.Namespace()).
    Set("metadata.labels[app.oam.dev/name]", vela.AppName()).
    Set("metadata.labels[app.oam.dev/component]", vela.Name())

CUE — generated
metadata: {
    name:      context.name
    namespace: context.namespace
    labels: {
        "app.oam.dev/name":      context.appName
        "app.oam.dev/component": context.name
    }
}

Usage in Conditions and Comparisons

Context values can be used in comparison expressions for runtime-conditional behaviour:

Go — defkit
vela := defkit.VelaCtx()

hpa := defkit.NewResourceWithConditionalVersion("HorizontalPodAutoscaler").
    VersionIf(defkit.Lt(vela.ClusterVersion().Minor(), defkit.Lit(23)), "autoscaling/v2beta2").
    VersionIf(defkit.Ge(vela.ClusterVersion().Minor(), defkit.Lit(23)), "autoscaling/v2").
    Set("metadata.name", vela.Name())

CUE — generated
apiVersion: {
    if context.clusterVersion.minor < 23 { "autoscaling/v2beta2" }
    if context.clusterVersion.minor >= 23 { "autoscaling/v2" }
}
kind: "HorizontalPodAutoscaler"
metadata: name: context.name

Usage in String Interpolation

Context values integrate naturally with defkit.Interpolation():

Go — defkit
vela := defkit.VelaCtx()
name := defkit.String("name")

clusterScopedName := defkit.Interpolation(
    vela.Namespace(),
    defkit.Lit("/"),
    name,
)

CUE — generated
"\(context.namespace)/\(parameter.name)"

Reading Component Output in Traits

Traits can inspect the component's output resource using defkit.ContextOutput():

Go — defkit
ref := defkit.ContextOutput()

templateRef := defkit.ContextOutput().Field("spec.template")

hasTemplate := defkit.ContextOutput().HasPath("spec.template")

patch := defkit.NewPatchResource()
patch.If(hasTemplate).
    Set("spec.template.metadata.labels.app", defkit.Lit("test")).
    EndIf()

CUE — generated
// .HasPath("spec.template")
context.output.spec.template != _|_

// .Field("spec.template")
context.output.spec.template

info

All VelaCtx methods return Value objects — they are not evaluated in Go. The actual values are substituted by the KubeVela controller at deploy time when the CUE template is executed against the Application spec.

defkit.VelaCtx() *VelaContext​

Context Fields Reference​

ClusterVersionRef Methods​

Usage in Resource Fields​

Usage in Conditions and Comparisons​

Usage in String Interpolation​

Reading Component Output in Traits​