Effective KRM functions
This guide covers patterns for writing KRM functions that go beyond the basic tutorial. Read Tutorial and Interfaces first.
The examples use the
KRM function SDK.
The resource types and selector functions live in the
kubeobject package, so
import it alongside the SDK. The examples refer to it as kubeobject.
Prerequisites #
- Install kpt
- Install Docker
- Go 1.24 or later, the minimum version the SDK requires
Read configuration #
The function config arrives as a KubeObject in the functionConfig argument of
Run. Read the fields you need from it instead of defining a struct for them.
func (r *SetImage) Run(ctx *fn.Context, functionConfig *kubeobject.KubeObject, items kubeobject.KubeObjects, results *kubeobject.Results) bool {
oldImage, _, err := functionConfig.NestedString("oldImage")
if err != nil {
results.ErrorE(err)
return false
}
newImage, _, err := functionConfig.NestedString("newImage")
if err != nil {
results.ErrorE(err)
return false
}
// ... use oldImage and newImage
return true
}
In main, wrap your Runner with fn.WithContext before passing it to
fn.AsMain, as shown in
Interfaces.
Passing it directly fails at runtime with unknown input type.
A matching input looks like this:
apiVersion: fn.kpt.dev/v1alpha1
kind: SetImage
metadata:
name: try-out
oldImage: example
newImage: my-registry/example:v2
Select KRM resources #
kubeobject.KubeObjects is a slice of *kubeobject.KubeObject. Use Where and
WhereNot with a predicate to narrow the set. The GroupVersionKind and
GroupKind types come from github.com/kptdev/kpt/api/schema/v1, not from
k8s.io/apimachinery.
import schema "github.com/kptdev/kpt/api/schema/v1"
// Namespace-scoped resources only.
namespaced := items.Where(func(o *kubeobject.KubeObject) bool {
return o.IsNamespaceScoped()
})
// Cluster-scoped resources only.
clusterScoped := items.Where(func(o *kubeobject.KubeObject) bool {
return o.IsClusterScoped()
})
// Deployments in the apps group, at exactly apps/v1.
deployments := items.Where(kubeobject.IsGroupVersionKind(schema.GroupVersionKind{
Group: "apps",
Version: "v1",
Kind: "Deployment",
}))
// Everything except Namespace objects, in the core group.
excluded := items.WhereNot(kubeobject.IsGroupKind(schema.GroupKind{
Group: "",
Kind: "Namespace",
}))
Use kubeobject.IsGroupVersionKind to match an exact apiVersion and kind. Use
kubeobject.IsGroupKind to match a group and kind across all versions. IsGVK is
deprecated, so avoid it in new code.
Changes you make to the objects in items, or to objects returned by Where, are
reflected in the output, because these are the same objects. Reassigning items
or building a filtered slice does not change the output. The SDK emits the list it
passed to Run, so a Runner can’t add or remove resources. To add or remove
resources, implement a ResourceListProcessor instead, as described in
Interfaces.
kubeobject.IsName matches objects by name, for example
items.Where(kubeobject.IsName("nginx")).
IsNamespaceScoped is decided by a table of known kinds. For any other kind it
falls back to whether metadata.namespace is set. A custom resource without a
namespace is treated as cluster-scoped, so check the kind if this matters for
your function.
Read and update fields #
kubeobject.KubeObject embeds kubeobject.SubObject, so both expose the same
field accessors. Each nested getter returns the value, whether the field was
found, and an error.
for _, obj := range items.Where(kubeobject.IsGroupVersionKind(schema.GroupVersionKind{
Group: "apps",
Version: "v1",
Kind: "Deployment",
})) {
replicas, found, err := obj.NestedInt64("spec", "replicas")
if err != nil {
results.ErrorE(err)
continue
}
if found {
fn.Logf("%s has %d replicas\n", obj.GetName(), replicas)
}
strategy, _, err := obj.NestedString("spec", "strategy", "type")
if err != nil {
results.ErrorE(err)
continue
}
if strategy == "Recreate" {
if err := obj.SetNestedString("RollingUpdate", "spec", "strategy", "type"); err != nil {
results.ErrorE(err)
}
}
}
Setters return an error. Check it, as shown above.
Work with sub-objects #
GetMap returns a SubObject for a nested map. If the field is missing, it
returns nil, and calling a method on nil panics. Check each step before you
chain the next one.
spec := deployment.GetMap("spec")
if spec == nil {
return true // no spec, nothing to update
}
template := spec.GetMap("template")
if template == nil {
return true
}
podSpec := template.GetMap("spec")
if podSpec == nil {
return true
}
if err := podSpec.SetNestedString("ssd", "nodeSelector", "disktype"); err != nil {
results.ErrorE(err)
}
Decode into a typed struct #
When a resource has a shape you already model in Go, decode its sub-object into a
struct with As. As returns an error on a nil sub-object, so it is safe to
call without a check, but you still need to handle that error.
type deploymentSpec struct {
Replicas int64 `json:"replicas"`
}
var spec deploymentSpec
if err := deployment.GetMap("spec").As(&spec); err != nil {
results.ErrorE(err)
return false
}
fn.Logf("decoded %d replicas\n", spec.Replicas)
As copies the sub-object. Changes you make to spec don’t change the resource.
To update the resource, set the fields back with the setters, such as
SetNestedString, on the KubeObject.
Next steps #
- Read Testing to cover your selection and update logic with golden tests.
- Read Containerizing to package the function as an image.