Effective KRM functions

Practical patterns for selecting, reading, and updating resources in a KRM function.

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 #

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.