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

[SurbhiAgarwal1]

Description

This PR adds CEL-based conditional function execution to kpt, implementing #4388.

A new optional condition 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.

Motivation

In many real-world scenarios, you want a pipeline function to run only when certain resources exist or meet specific criteria. Without this feature, users had to maintain separate Kptfiles or manually manage which functions run. The condition field makes pipelines more dynamic and reduces the need for workarounds.

Changes

• Added condition field to Function type in pkg/api/kptfile/v1/types.go
• Added CELEnvironment in pkg/lib/runneroptions/celenv.go using google/cel-go
• Integrated condition check in FunctionRunner.Filter() in internal/fnruntime/runner.go
• Functions skipped due to condition show [SKIPPED] in CLI output
• 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 all 3 runtimes (builtin, exec, container)
• Updated documentation: kptfile schema reference and book/04-using-functions

Example Usage

pipeline:
  mutators:
    - image: ghcr.io/kptdev/krm-functions-catalog/set-namespace:v0.4
      condition: "resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'env-config')"
      configMap:
        namespace: production

[netlify]

✅ Deploy Preview for kptdocs ready!

Name	Link
🔨 Latest commit	9431239
🔍 Latest deploy log	https://app.netlify.com/projects/kptdocs/deploys/6a85778f8ec0be00086064b1
😎 Deploy Preview	https://deploy-preview-4469--kptdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[liamfallon]

Comment from #4391:

Closing this PR in favor of a clean rebase. The branch had accumulated 61 commits including upstream commits from other contributors, making it messy to review.

All the feedback from this review has been addressed in the new PR which has a single clean commit:

Removed unnecessary type alias file (celeval.go)
Grouped constants in const() block
Replaced interface{} with any
Removed panic from InitDefaults, added InitCELEnvironment() error method
Added e2e tests for condition-met and condition-not-met
Added immutability test
Added documentation (kptfile schema + book/04-using-functions)
Removed all unwanted files (krm-functions-catalog, output.txt, etc.)
Fixed diff.patch for renderStatus field

Thank you all for the thorough review!

[Copilot]

Pull request overview

Copilot reviewed 31 out of 32 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (1)

thirdparty/kyaml/runfn/runfn.go:1

• NewFunctionRunner’s error is discarded and SetCondition is called without validating opts.CELEnvironment. This can both (a) mask construction failures and (b) silently ignore the condition at runtime when CELEnvironment is nil (since Filter() only evaluates conditions when celEnv != nil). Handle the err from NewFunctionRunner, and if r.Condition is set, return an error when opts.CELEnvironment is nil (or make SetCondition return an error and enforce it here).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

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

• Two doc mismatches with the implementation: (1) the CEL resource map normalization in resourceToMap guarantees apiVersion, kind, and metadata keys, but not spec/status—either update the docs or ensure those keys are present; (2) the skipped example says “Successfully executed 1 function(s)” but the new behavior and e2e expectations indicate skipped functions should not count as executed (so this should be 0).

---

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[liamfallon]

@SurbhiAgarwal1

The tests are failing because we have merged the conditions and renederstatus to kpt recently. I thought that by deleting the diff.patch files, the comparison would just check the output and the tests would pass. However we also need to add the difference in the Kprfile after render to the diff.patch files. Now that I deleted the diff.patch files in the PR, I can't see any option to restore them on the Github GUI.

The following `diff.patch files work for me on the tests locally on my machine:

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

diff --git a/Kptfile b/Kptfile
index eb90ac3..d305dc0 100644
--- a/Kptfile
+++ b/Kptfile
@@ -5,4 +5,14 @@ metadata:
 pipeline:
   mutators:
     - image: ghcr.io/kptdev/krm-functions-catalog/no-op
-      condition: "resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'app-config')"
+      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
+        exitCode: 0

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

diff --git a/Kptfile b/Kptfile
index eb90ac3..b055f32 100644
--- a/Kptfile
+++ b/Kptfile
@@ -5,4 +5,14 @@ metadata:
 pipeline:
   mutators:
     - image: ghcr.io/kptdev/krm-functions-catalog/no-op
-      condition: "resources.exists(r, r.kind == 'ConfigMap' && r.metadata.name == 'app-config')"
+      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
+        exitCode: 0
+        skipped: true

Can you try restoring the two diff.patch files with the contents above and see if that fixes the tests?

Sorry for mucking with your PR 😢

[SurbhiAgarwal1]

Thank you @liamfallon! I've restored both diff.patch files with exactly the contents you provided in commit df1189f. The tests should pass now. Sorry for the confusion!

[liamfallon]

Hi @SurbhiAgarwal1 , have you resolved all the comments above?

[sonarqubecloud]

Quality Gate failed

Failed conditions
3.4% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

[aravindtga]

Hi @SurbhiAgarwal1

This feature has been getting more traction from the community recently and we'd like to prioritise getting it merged. Could you pick this up and address the outstanding items?

1. Rebase onto current main and resolve the merge conflict
2. Address any remaining review comments
3. Get CI passing (including the SonarQube duplication issue)

If you're blocked on anything or need any help, feel free to reach out - we're happy to assist.

cc/ @liamfallon @efiacor

[SurbhiAgarwal1]

Hi @aravindtga @efiacor @liamfallon,

I have updated the PR with all fixes and test fixture updates:

1. Skipped Functions Logic Fix: Updated runMutators and runValidators in render_executor.go so that functions skipped due to a CEL condition (when) are not counted toward executedFunctionCnt (e.g. outputs "Successfully executed 0 function(s)" when all functions are skipped).
2. Metadata Propagation: Ensured When and Skipped fields are populated in PipelineStepResult and serialized into Kptfile renderStatus.
3. Configurable Limits: Made CelCheckFrequency and CelCostLimit configurable via RunnerOptions rather than hardcoded constants.
4. E2E Snapshot Updates: Updated the expected stderr and diff.patch test fixtures (condition-met, condition-not-met, subpkg-fn-failure) to match upstream/main's printer output format and renderStatus schema.
5. Test Verification: Verified unit tests (pkg/fn/runtime, pkg/lib/runneroptions, pkg/lib/kptops) and container e2e test suites pass 100% locally.

All commits are signed off and pushed to the branch. Ready for your review!

[efiacor]

We will have to wave this through and pickup the additional pieces afterwards
@aravindtga