Advanced API Methods

Additional methods used in complex definitions — patch container fields, array builders, field transformations, and collection utilities.

Patch Container Fields

defkit.PatchField()

Defines a single patch field for container mutation. Chain: .Strategy(strategy) (retainKeys, merge, replace), .NotEmpty() (reject empty values), .Description(text).

Applies to: Trait

Go — defkit

defkit.PatchField("image").Strategy("retainKeys").Description("Container image")

CUE — generated

// +patchStrategy=retainKeys
image: string

defkit.PatchFields()

Groups multiple PatchField definitions into a config used in PatchContainerConfig.

Applies to: Trait

Go — defkit

defkit.PatchFields(
    defkit.PatchField("image").Strategy("retainKeys"),
    defkit.PatchField("resources"),
)
// Used with:
tpl.UsePatchContainer(defkit.PatchContainerConfig{
    PatchFields: defkit.PatchFields(...),
})

CUE — generated

#PatchParams: {
  image?:     string
  resources?: {...}
}

Resource-Producing Traits

Traits can create new resources (e.g., a Service) instead of patching the workload. Use tpl.Outputs() inside the trait template — the same method used in component templates — to emit auxiliary resources.

Applies to: Trait

Go — defkit

trait := defkit.NewTrait("expose").
    Description("Expose workload via Service").
    AppliesTo("deployments.apps").
    Stage("PostDispatch").
    Params(
        defkit.Int("port").Default(80).Description("Service port"),
        defkit.String("type").Default("ClusterIP").Description("Service type"),
    ).
    Template(func(tpl *defkit.Template) {
        service := defkit.NewResource("v1", "Service").
            Set("metadata.name", defkit.VelaCtx().Name()).
            Set("spec.type", defkit.ParamRef("type")).
            Set("spec.ports[0].port", defkit.ParamRef("port"))
        tpl.Outputs("service", service)
    })

CUE — generated

expose: {
    type: "trait"
    annotations: {}
    description: "Expose workload via Service"
    attributes: {
        podDisruptive: false
        stage:         "PostDispatch"
        appliesToWorkloads: ["deployments.apps"]
    }
}
template: {
    outputs: service: {
        apiVersion: "v1"
        kind:       "Service"
        metadata: name: context.name
        spec: {
            type: parameter.type
            ports: [{
                port: parameter.port
            }]
        }
    }
    parameter: {
        // +usage=Service port
        port: *80 | int
        // +usage=Service type
        type: *"ClusterIP" | string
    }
}

Reading Component Context

Traits can inspect the component's output resource using ContextOutput(). .Field(path) accesses a nested field for use in patches or conditions. .HasPath(path) returns a boolean condition — true if the path exists in the output.

Applies to: Trait

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

Array Builders

defkit.NewArray().Item() / defkit.NewArrayElement()

Builds a CUE array literal with explicit items. Use when you need to construct an array value inline (not iterate over params). NewArrayElement builds a single object element supporting the same .Set(), .SetIf() methods as NewResource.

Go — defkit

defkit.NewArray().Item(
    defkit.NewArrayElement().Set("kind", defkit.Lit("ServiceAccount")),
)

vela := defkit.VelaCtx()
defkit.NewArrayElement().
    Set("name", vela.Name()).
    Set("namespace", vela.Namespace())

CUE — generated

[{kind: "ServiceAccount"}]

{name: context.name, namespace: context.namespace}

defkit.OpenArray()

Parameter type for an array with open schema (no element type constraint).

Go — defkit

defkit.OpenArray("items")

CUE — generated

items: [...{...}]

defkit.DynamicMap()

Replaces the entire parameter block with a dynamic map. When a definition uses DynamicMap, the parameter schema becomes [string]: T rather than a named-field struct.

Go — defkit

defkit.DynamicMap().ValueTypeUnion("string | null")

CUE — generated

parameter: [string]: string | null

Field Reference & Transformation

defkit.ParameterField() / defkit.ParamPath()

ParameterField returns the value at a dot-notation path inside parameter. ParamPath returns a reference that supports .IsSet() as a condition.

Applies to: Template

Go — defkit

defkit.ParameterField("strategy.type")
defkit.ParamPath("podAffinity.required").IsSet()

CUE — generated

parameter.strategy.type
parameter.podAffinity.required != _|_

defkit.FieldRef()

Inside a ForEachIn / From iteration context, references a field of the current element by name.

Applies to: Template

Go — defkit

defkit.ForEachIn(constraints).MapFields(defkit.FieldMap{
    "maxSkew": defkit.FieldRef("maxSkew"),
})

CUE — generated

[for v in parameter.constraints {
    maxSkew: v.maxSkew
}]

defkit.ForEachIn()

Transforms an array parameter by mapping each element's fields. Returns a CUE list comprehension.

Applies to: Template

Go — defkit

defkit.ForEachIn(constraints).MapFields(defkit.FieldMap{
    "maxSkew":           defkit.FieldRef("maxSkew"),
    "topologyKey":       defkit.FieldRef("topologyKey"),
    "whenUnsatisfiable": defkit.FieldRef("whenUnsatisfiable"),
})

CUE — generated

[for v in parameter.constraints {
    maxSkew:           v.maxSkew
    topologyKey:       v.topologyKey
    whenUnsatisfiable: v.whenUnsatisfiable
}]

defkit.From()

Similar to ForEachIn but with filter and guard support. .Filter(cond) filters elements, .Guard(cond) wraps the whole expression in an if-guard.

Applies to: Template

Go — defkit

defkit.From(privileges).
    Filter(defkit.FieldEquals("scope", "cluster")).
    Guard(privileges.IsSet())

CUE — generated

if parameter["privileges"] != _|_ {
    [for v in parameter.privileges
     if v.scope == "cluster" { v }]
}

defkit.LenGt()

Returns a condition that is true when the length of an array expression is greater than n.

Applies to: Template

Go — defkit

defkit.LenGt(clusterPrivsRef, 0)

CUE — generated

len(_clusterPrivileges) > 0