Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -420,6 +420,8 @@ kpt fn eval ./testdata/hello-world/resources.yaml --image ${FN_CONTAINER_REGISTR
- Read the [KRM Function Developer Guide]({{% relref "/guides/krm-functions" %}})
for choosing an [interface]({{% relref "/guides/krm-functions/interfaces" %}})
(`fn.Runner` vs `fn.ResourceListProcessor`),
[effective patterns]({{% relref "/guides/krm-functions/effective" %}}) for selecting
and updating resources,
[testing]({{% relref "/guides/krm-functions/testing" %}}) with golden files, and
[containerizing]({{% relref "/guides/krm-functions/containerizing" %}}) your function.
- See other [go documentation examples](https://pkg.go.dev/github.com/kptdev/krm-functions-sdk/go/fn/examples) to use KubeObject.
Expand Down
2 changes: 2 additions & 0 deletions documentation/content/en/guides/krm-functions/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ then dig into the topic guides as needed.
- [Interfaces]({{% relref "/guides/krm-functions/interfaces" %}}) — choose between
`fn.Runner` (transformers, validators) and `fn.ResourceListProcessor`
(generators, complex functions).
- [Effective KRM functions]({{% relref "/guides/krm-functions/effective" %}}) — patterns
for selecting, reading, and updating resources.
- [Testing]({{% relref "/guides/krm-functions/testing" %}}) — golden test patterns
and unit testing in depth.
- [Containerizing]({{% relref "/guides/krm-functions/containerizing" %}}) — package
Expand Down
205 changes: 205 additions & 0 deletions documentation/content/en/guides/krm-functions/effective.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
---
title: Effective KRM functions
linkTitle: Effective KRM functions
description: Practical patterns for selecting, reading, and updating resources in a KRM function.
toc_hide: false
menu:
main:
parent: "KRM Function Developer Guide"
weight: 25
---
This guide covers patterns for writing KRM functions that go beyond the basic
tutorial. Read [Tutorial]({{% relref "/guides/krm-functions/tutorial" %}}) and
[Interfaces]({{% relref "/guides/krm-functions/interfaces" %}}) first.

The examples use the [KRM function SDK](https://pkg.go.dev/github.com/kptdev/krm-functions-sdk/go/fn).
The resource types and selector functions live in the
[`kubeobject` package](https://pkg.go.dev/github.com/kptdev/kpt/api/kubeobject), so
import it alongside the SDK. The examples refer to it as `kubeobject`.

## Prerequisites

- [Install kpt]({{% relref "/installation" %}})
- [Install Docker](https://docs.docker.com/get-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.

```golang
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]({{% relref "/guides/krm-functions/interfaces" %}}).
Passing it directly fails at runtime with `unknown input type`.

A matching input looks like this:

```yaml
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`.

```golang
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]({{% relref "/guides/krm-functions/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.

```golang
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.

```golang
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.

```golang
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]({{% relref "/guides/krm-functions/testing" %}}) to cover your
selection and update logic with golden tests.
- Read [Containerizing]({{% relref "/guides/krm-functions/containerizing" %}}) to
package the function as an image.
Loading