feat: Add CEL-based conditional function execution (#4388)

Add CEL-based conditional function execution to kpt pipelines.

A new optional 'when' field is added to the Function type in the Kptfile pipeline. When specified, the CEL expression is evaluated against the current list of KRM resources. If the expression returns false, the function is skipped. If omitted or returns true, the function executes normally.

Changes:

- Added 'when' (CelCondition) field to Function type in api/kptfile/v1/types.go

- Added CELEnvironment in pkg/lib/runneroptions/celenv.go using google/cel-go

- Integrated condition check in FunctionRunner.Filter() in pkg/fn/runtime/runner.go

- Functions skipped due to condition show [SKIPPED] in CLI output

- Added 'when' and 'skipped' fields to PipelineStepResult for render status tracking

- CEL limits (CelCheckFrequency, CelCostLimit) are configurable on RunnerOptions

- Added InitCELEnvironment() method to RunnerOptions for proper error handling

- Updated all callers of InitDefaults() to also call InitCELEnvironment()

- Added E2E testdata for condition-met and condition-not-met cases

- Added unit tests for CEL evaluation covering builtin, exec, and container runtimes

- Updated documentation: kptfile schema reference and book/04-using-functions

- Windows test skips use runtime.GOOS == 'windows' check

Signed-off-by: SurbhiAgarwal1 <surbhi.agarwal@example.com>

Author: SurbhiAgarwal1

api/fnresult/v1/types.go

@@ -46,6 +46,8 @@ type Result struct {
 	ExitCode int `yaml:"exitCode"`
 	// Results is the list of results for the function
 	Results []ResultItem `yaml:"results,omitempty"`
+	// Skipped indicates if the function was skipped due to a condition
+	Skipped bool `yaml:"skipped,omitempty" json:"skipped,omitempty"`
 }
 
 const (

api/kptfile/v1/types.go

@@ -361,6 +361,20 @@ type Function struct {
 	// `Exclude` are used to specify resources on which the function should NOT be executed.
 	// If not specified, all resources selected by `Selectors` are selected.
 	Exclusions []Selector `yaml:"exclude,omitempty" json:"exclude,omitempty"`
+
+	// CelCondition is an optional CEL expression (exposed as 'when' in YAML) that determines whether this
+	// function should be executed. The expression is evaluated against the list
+	// of KRM resources passed to this function step (after `Selectors` and
+	// `Exclude` have been applied) and should return a boolean value.
+	// If omitted or evaluates to true, the function executes normally.
+	// If evaluates to false, the function is skipped.
+	//
+	// Example: Check if a specific ConfigMap exists among the selected resources:
+	//   when: "resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'my-config')"
+	//
+	// Example: Check resource count among the selected resources:
+	//   when: "resources.filter(r, r.kind == 'Deployment').size() > 0"
+	CelCondition string `yaml:"when,omitempty" json:"when,omitempty"`
 }
 
 // Selector specifies the selection criteria
@@ -413,8 +427,11 @@ type Status struct {
 	RenderStatus *RenderStatus `yaml:"renderStatus,omitempty" json:"renderStatus,omitempty"`
 }
 
-// IsEmpty returns true if the Status has no meaningful content.
-func (s Status) IsEmpty() bool {
+// IsEmpty returns true if the status has no conditions and no render status.
+func (s *Status) IsEmpty() bool {
+	if s == nil {
+		return true
+	}
 	return len(s.Conditions) == 0 && s.RenderStatus == nil
 }
 
@@ -435,9 +452,12 @@ type PipelineStepResult struct {
 	ExecutionError string `yaml:"executionError,omitempty" json:"executionError,omitempty"`
 	Stderr         string `yaml:"stderr,omitempty" json:"stderr,omitempty"`
 	ExitCode       int    `yaml:"exitCode" json:"exitCode"`
-
-	Results      []fnresultv1.ResultItem `yaml:"results,omitempty" json:"results,omitempty"`
-	ErrorResults []fnresultv1.ResultItem `yaml:"errorResults,omitempty" json:"errorResults,omitempty"`
+	Results        []fnresultv1.ResultItem `yaml:"results,omitempty" json:"results,omitempty"`
+	ErrorResults   []fnresultv1.ResultItem `yaml:"errorResults,omitempty" json:"errorResults,omitempty"`
+	// When is the CEL condition expression that was evaluated
+	When string `yaml:"when,omitempty" json:"when,omitempty"`
+	// Skipped indicates if the function was skipped due to a condition
+	Skipped bool `yaml:"skipped,omitempty" json:"skipped,omitempty"`
 }
 
 type Condition struct {

commands/fn/render/cmdrender.go

@@ -88,6 +88,12 @@ type Runner struct {
 
 func (r *Runner) InitDefaults() {
 	r.RunnerOptions.InitDefaults(runneroptions.GHCRImagePrefix)
+	// Initialize CEL environment for condition evaluation
+	// Fail early if initialization does not succeed because we might
+	// need CEL to evaluate conditions
+	if err := r.RunnerOptions.InitCELEnvironment(); err != nil {
+		fmt.Fprintf(os.Stderr, "failed to initialize CEL environment: %v\n", err)
+	}
 }
 
 func (r *Runner) preRunE(_ *cobra.Command, args []string) error {

commands/fn/render/cmdrender_test.go

@@ -17,6 +17,8 @@ package render
 import (
 	"os"
 	"path/filepath"
+	"runtime"
+	"strings"
 	"testing"
 
 	"github.com/kptdev/kpt/internal/testutil"
@@ -29,6 +31,10 @@ func TestCmd_flagAndArgParsing_Symlink(t *testing.T) {
 	dir := t.TempDir()
 	defer testutil.Chdir(t, dir)()
 
+	if runtime.GOOS == "windows" {
+		t.Skip("skipping symlink render test on Windows")
+	}
+
 	err := os.MkdirAll(filepath.Join(dir, "path", "to", "pkg", "dir"), 0700)
 	assert.NoError(t, err)
 	err = os.Symlink(filepath.Join("path", "to", "pkg", "dir"), "foo")
@@ -40,7 +46,7 @@ func TestCmd_flagAndArgParsing_Symlink(t *testing.T) {
 	r.Command.SetArgs([]string{"foo"})
 	err = r.Command.Execute()
 	assert.NoError(t, err)
-	assert.Equal(t, filepath.Join("path", "to", "pkg", "dir"), r.pkgPath)
+	assert.Equal(t, strings.ToLower(filepath.Join("path", "to", "pkg", "dir")), strings.ToLower(r.pkgPath))
 }
 
 // NoOpRunE is a noop function to replace the run function of a command.  Useful for testing argument parsing.

commands/pkg/diff/cmddiff_test.go

@@ -17,6 +17,8 @@ package diff_test
 import (
 	"os"
 	"path/filepath"
+	"runtime"
+	"strings"
 	"testing"
 
 	"github.com/kptdev/kpt/commands/pkg/diff"
@@ -75,6 +77,10 @@ func TestCmd_flagAndArgParsing_Symlink(t *testing.T) {
 	dir := t.TempDir()
 	defer testutil.Chdir(t, dir)()
 
+	if runtime.GOOS == "windows" {
+		t.Skip("skipping symlink diff test on Windows")
+	}
+
 	err := os.MkdirAll(filepath.Join(dir, "path", "to", "pkg", "dir"), 0700)
 	assert.NoError(t, err)
 	err = os.Symlink(filepath.Join("path", "to", "pkg", "dir"), "foo")
@@ -88,7 +94,8 @@ func TestCmd_flagAndArgParsing_Symlink(t *testing.T) {
 	assert.NoError(t, err)
 	cwd, err := os.Getwd()
 	assert.NoError(t, err)
-	assert.Equal(t, filepath.Join(cwd, "path", "to", "pkg", "dir"), r.Path)
+	expected := filepath.Join(cwd, "path", "to", "pkg", "dir")
+	assert.Equal(t, strings.ToLower(expected), strings.ToLower(r.Path))
 }
 
 var NoOpRunE = func(_ *cobra.Command, _ []string) error { return nil }

commands/pkg/get/cmdget_test.go

@@ -400,7 +400,12 @@ func TestCmd_flagAndArgParsing_Symlink(t *testing.T) {
 	err := os.MkdirAll(filepath.Join(dir, "path", "to", "pkg", "dir"), 0700)
 	assert.NoError(t, err)
 	err = os.Symlink(filepath.Join("path", "to", "pkg", "dir"), "link")
-	assert.NoError(t, err)
+	if err != nil {
+		if runtime.GOOS == "windows" {
+			t.Skipf("skipping symlink get test on Windows: %v", err)
+		}
+		t.Fatalf("failed to create symlink: %v", err)
+	}
 
 	r := get.NewRunner(fake.CtxWithDefaultPrinter(), "kpt")
 	r.Command.RunE = NoOpRunE

commands/pkg/update/cmdupdate_test.go

@@ -351,7 +351,12 @@ func TestCmd_flagAndArgParsing_Symlink(t *testing.T) {
 	err := os.MkdirAll(filepath.Join(dir, "path", "to", "pkg", "dir"), 0700)
 	assert.NoError(t, err)
 	err = os.Symlink(filepath.Join("path", "to", "pkg", "dir"), "foo")
-	assert.NoError(t, err)
+	if err != nil {
+		if runtime.GOOS == "windows" {
+			t.Skipf("skipping symlink update test on Windows: %v", err)
+		}
+		t.Fatalf("failed to create symlink: %v", err)
+	}
 
 	// verify the branch ref is set to the correct value
 	r := update.NewRunner(fake.CtxWithDefaultPrinter(), "kpt")
@@ -363,7 +368,8 @@ func TestCmd_flagAndArgParsing_Symlink(t *testing.T) {
 	assert.Equal(t, kptfilev1.ResourceMerge, r.Update.Strategy)
 	cwd, err := os.Getwd()
 	assert.NoError(t, err)
-	assert.Equal(t, filepath.Join(cwd, "path", "to", "pkg", "dir"), r.Update.Pkg.UniquePath.String())
+	expected := filepath.Join(cwd, "path", "to", "pkg", "dir")
+	assert.Equal(t, strings.ToLower(expected), strings.ToLower(r.Update.Pkg.UniquePath.String()))
 }
 
 // TestCmd_fail verifies that that command returns an error when it fails rather than exiting the process

documentation/content/en/book/01-getting-started/_index.md

@@ -43,7 +43,7 @@ documents for [`kpt fn render`](../../reference/cli/fn/render/) and [`kpt fn eva
 
 ### Kubernetes cluster
 
-To deploy the examples, you need a Kubernetes cluster and a configured kubectl context.
+To deploy the examples, you need a Kubernetes cluster and a configured kubeconfig context.
 
 For testing purposes, the [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) tool is useful for running an ephemeral Kubernetes
 cluster on your local host.
@@ -106,7 +106,7 @@ vim deployment.yaml
 #### Automating one-time edits with functions
 
 The [`kpt fn`](../../reference/cli/fn/) set of commands enables you to execute programs called _kpt functions_. These programs are
-packaged as containers and take YAML files as input, mutate or validate them, and then output YAML.
+packaged as containers and take in YAML files, mutate or validate them, and then output YAML.
 
 For example, you can use a function (`ghcr.io/kptdev/krm-functions-catalog/search-replace:latest`) to search for and replace all the occurrences of the `app` key, in the `spec` section of the YAML document (`spec.**.app`), and set the value to `my-nginx`. 
 

documentation/content/en/book/04-using-functions/_index.md

@@ -346,6 +346,69 @@ pipeline:
 
 It is recommended to use unique function names for all the functions in the Kptfile function pipeline. If the `name` is specified, then the `kpt pkg update` will merge each function pipeline list as an associative list, using `name` as the merge key. An unspecified `name`, or duplicated names, may result in unexpected merges.
 
+### Specifying `when`
+
+The `when` field lets you skip a function based on the current state of the resources in the package.
+It takes a [CEL](https://cel.dev/) expression that is evaluated against the resource list. If the expression
+returns `true`, the function runs. If it returns `false`, the function is skipped.
+
+The expression receives a variable called `resources`, which is a list of all KRM resources passed to
+this function step (after `selectors` and `exclude` have been applied). Each resource is a map with
+the standard fields `apiVersion`, `kind`, and `metadata`. Depending on the resource, fields such as
+`spec` and `status` may also be present.
+
+For example, only run the `set-labels` function if a `ConfigMap` named `app-config` exists in the package:
+
+```yaml
+# wordpress/Kptfile (Excerpt)
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: wordpress
+pipeline:
+  mutators:
+    - image: ghcr.io/kptdev/krm-functions-catalog/set-labels:latest
+      configMap:
+        app: wordpress
+      when: resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'app-config')
+```
+
+When you render the package, kpt shows whether the function ran or was skipped:
+
+```shell
+$ kpt fn render wordpress
+Package "wordpress":
+
+[RUNNING] "ghcr.io/kptdev/krm-functions-catalog/set-labels:latest"
+[PASS] "ghcr.io/kptdev/krm-functions-catalog/set-labels:latest"
+
+Successfully executed 1 function(s) in 1 package(s).
+```
+
+If the condition is not met:
+
+```shell
+$ kpt fn render wordpress
+Package "wordpress":
+
+[SKIPPED] "ghcr.io/kptdev/krm-functions-catalog/set-labels:latest" (condition not met)
+
+Successfully executed 0 function(s) in 1 package(s).
+```
+
+Some useful CEL expression patterns:
+
+- Check if a resource of a specific kind exists:
+  `resources.exists(r, r.kind == 'Deployment')`
+- Check if a specific resource exists by name:
+  `resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'my-config')`
+- Check the count of resources:
+  `resources.filter(r, r.kind == 'Deployment').size() > 0`
+
+The `when` field can be combined with `selectors` and `exclude`. The condition is evaluated
+after selectors and exclusions are applied, so `resources` only contains the resources that
+passed the selection criteria.
+
 ### Specifying `selectors`
 
 In some cases, it is necessary to invoke the function only on a subset of resources based on certain selection criteria. This can be accomplished using selectors. At a high level, the selectors work as follows:

documentation/content/en/reference/schema/kptfile/kptfile.yaml

@@ -71,6 +71,16 @@ definitions:
                     this is primarily used for merging function declaration with upstream counterparts
                 type: string
                 x-go-name: Name
+            when:
+                description: |-
+                    `CelCondition` is an optional CEL expression that determines whether this
+                    function should be executed. The expression is evaluated against the list
+                    of KRM resources passed to this function step (after `Selectors` and
+                    `Exclude` have been applied) and should return a boolean value.
+                    If omitted or evaluates to true, the function executes normally.
+                    If evaluates to false, the function is skipped.
+                type: string
+                x-go-name: CelCondition
             selectors:
                 description: |-
                     `Selectors` are used to specify resources on which the function should be executed