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

Adds support for CEL expressions in Kptfile pipeline functions via
a new 'condition' field. Functions with a condition are only executed
if the CEL expression evaluates to true against the current resource list.

- Add CELEnvironment in pkg/lib/runneroptions/celenv.go
- Integrate condition check in FunctionRunner.Filter (runner.go)
- Append skipped result to fnResults when condition is not met
- Add 'condition' field to kptfile/v1 Function type
- Update all callers of InitDefaults to also call InitCELEnvironment
- Add e2e testdata for condition-met and condition-not-met cases
- Add unit tests for CEL evaluation and condition checking
- Update documentation: kptfile schema and book/04-using-functions
- Fix go.mod: mark k8s.io/apiserver as direct dependency

Resolves #4388

Signed-off-by: SurbhiAgarwal1 <agarwalsurbhi1807@gmail.com>

Author: SurbhiAgarwal1

commands/fn/render/cmdrender.go

@@ -85,6 +85,9 @@ type Runner struct {
 
 func (r *Runner) InitDefaults() {
 	r.RunnerOptions.InitDefaults(runneroptions.GHCRImagePrefix)
+	// Initialize CEL environment for condition evaluation
+	// Ignore error as conditions are optional; if CEL init fails, conditions will error at runtime
+	_ = r.RunnerOptions.InitCELEnvironment()
 }
 
 func (r *Runner) preRunE(_ *cobra.Command, args []string) error {

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

@@ -375,6 +375,68 @@ 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 `condition`
+
+The `condition` 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`, `metadata`, `spec`, `status`.
+
+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
+      condition: 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 1 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 `condition` 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, you want to invoke the function only on a subset of resources based on a

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
+            condition:
+                description: |-
+                    `Condition` 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: Condition
             selectors:
                 description: |-
                     `Selectors` are used to specify resources on which the function should be executed

e2e/testdata/fn-render/condition/condition-met/.expected/config.yaml

@@ -0,0 +1,12 @@
+actualStripLines:
+  - "    stderr: 'WARNING: The requested image''s platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested'"
+
+stdErrStripLines:
+  - "  Stderr:"
+  - "    \"WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested\""
+
+stdErr: |
+  Package: "condition-met"
+  [RUNNING] "ghcr.io/kptdev/krm-functions-catalog/no-op:latest"
+  [PASS] "ghcr.io/kptdev/krm-functions-catalog/no-op:latest" in 0s
+  Successfully executed 1 function(s) in 1 package(s).

e2e/testdata/fn-render/condition/condition-met/.expected/diff.patch

@@ -0,0 +1,61 @@
+diff --git a/Kptfile b/Kptfile
+index 2210a5f..5ccde1c 100755
+--- a/Kptfile
++++ b/Kptfile
+@@ -1,8 +1,17 @@
+-apiVersion: kpt.dev/v1
+-kind: Kptfile
+-metadata:
+-  name: app
+-pipeline:
+-  mutators:
+-    - image: ghcr.io/kptdev/krm-functions-catalog/no-op
+-      condition: "resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'app-config')"
++apiVersion: kpt.dev/v1
++kind: Kptfile
++metadata:
++  name: app
++pipeline:
++  mutators:
++    - image: ghcr.io/kptdev/krm-functions-catalog/no-op
++      condition: resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'app-config')
++status:
++  conditions:
++    - type: Rendered
++      status: "True"
++      reason: RenderSuccess
++  renderStatus:
++    mutationSteps:
++      - image: ghcr.io/kptdev/krm-functions-catalog/no-op:latest
++        exitCode: 0
+diff --git a/resources.yaml b/resources.yaml
+index 2f4405b..47bec8b 100755
+--- a/resources.yaml
++++ b/resources.yaml
+@@ -1,13 +1,13 @@
+-apiVersion: v1
+-kind: ConfigMap
+-metadata:
+-  name: app-config
+-data:
+-  key: value
+----
+-apiVersion: apps/v1
+-kind: Deployment
+-metadata:
+-  name: my-app
+-spec:
+-  replicas: 1
++apiVersion: v1
++kind: ConfigMap
++metadata:
++  name: app-config
++data:
++  key: value
++---
++apiVersion: apps/v1
++kind: Deployment
++metadata:
++  name: my-app
++spec:
++  replicas: 1

e2e/testdata/fn-render/condition/condition-met/.krmignore

@@ -0,0 +1 @@
+.expected

e2e/testdata/fn-render/condition/condition-met/Kptfile

@@ -0,0 +1,8 @@
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: app
+pipeline:
+  mutators:
+    - image: ghcr.io/kptdev/krm-functions-catalog/no-op
+      condition: "resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'app-config')"

e2e/testdata/fn-render/condition/condition-met/resources.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config
+data:
+  key: value
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+spec:
+  replicas: 1

e2e/testdata/fn-render/condition/condition-not-met/.expected/config.yaml

@@ -0,0 +1,11 @@
+actualStripLines:
+  - "    stderr: 'WARNING: The requested image''s platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested'"
+
+stdErrStripLines:
+  - "  Stderr:"
+  - "    \"WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested\""
+
+stdErr: |
+  Package: "condition-not-met"
+  [SKIPPED] "ghcr.io/kptdev/krm-functions-catalog/no-op:latest" (condition not met)
+  Successfully executed 0 function(s) in 1 package(s).