Conversation
SurbhiAgarwal1
requested review from
efiacor,
kispaljr,
liamfallon and
mozesl-nokia
as code owners
✅ Deploy Preview for kptdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
dosubot
bot
added
size:XL
There was a problem hiding this comment.
Pull request overview
This PR adds end-user documentation for running/developing/publishing WASM functions in kpt, and (in the same change set) introduces a new CEL-based condition field on Kptfile pipeline functions to enable conditional function execution.
Changes:
- Adds a comprehensive “Using WASM Functions” guide (run, eval, push/pull, Go build tags, limitations).
- Extends
kptfile.v1.Functionwith aconditionfield and evaluates it before executing a function. - Adds a CEL evaluator implementation + unit/E2E-style tests, and updates Go module dependencies for CEL.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| pkg/api/kptfile/v1/types.go | Adds Function.Condition (CEL) field to the Kptfile API. |
| internal/fnruntime/runner.go | Initializes and uses a CEL evaluator to skip function execution when condition is false. |
| internal/fnruntime/celeval.go | New CEL evaluator implementation for evaluating conditions against resource inputs. |
| internal/fnruntime/celeval_test.go | Unit tests for CEL evaluator behavior and errors. |
| internal/fnruntime/conditional_e2e_test.go | End-to-end style tests for conditional execution behavior in FunctionRunner. |
| go.mod / go.sum | Adds github.com/google/cel-go and related transitive dependencies. |
| documentation/content/en/book/04-using-functions/wasm-functions.md | New documentation page describing the WASM function workflow in kpt. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
documentation/content/en/book/04-using-functions/wasm-functions.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 8 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Security | ||
|
|
||
| WASM functions run in a sandbox: | ||
| - No network access | ||
| - No filesystem access (except input/output resources) | ||
| - Can't execute system commands |
There was a problem hiding this comment.
The “Security” section states WASM functions have no network/filesystem access and no host access by default. kpt supports both wasmtime (default) and node.js-based runtimes (selectable via KPT_FN_WASM_RUNTIME), and the node.js runtime can expose broader host capabilities to Go WASM via syscall/js. Please qualify these claims (e.g., “with wasmtime runtime…”) to avoid overstating the sandbox guarantees.
SurbhiAgarwal1
force-pushed
the
docs/wasm-function-support
branch
from
e979fbb to
1abf41f
Compare
dosubot
bot
added
size:L
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
|
|
||
| What this does: | ||
| 1. Compresses the WASM file into a tar archive | ||
| 2. Creates an OCI image with `wasm/js` platform |
There was a problem hiding this comment.
The same incorrect wasm/js platform identifier is used here. It should be js/wasm to match the OCI convention of OS/Architecture, consistent with the code in pkg/wasm/client.go:122-124 where OS: "js" and Architecture: "wasm".
documentation/content/en/book/04-using-functions/wasm-functions.md
Outdated
Show resolved
Hide resolved
| Here's how to build a Go KRM function for WASM. You need two files - one for regular builds and one for WASM: | ||
|
|
||
| `main.go` (regular build): | ||
|
|
||
| ```go | ||
| //go:build !(js && wasm) | ||
|
|
||
| package main | ||
|
|
||
| import ( | ||
| "os" | ||
|
|
||
| "github.com/kptdev/krm-functions-sdk/go/fn" | ||
| ) | ||
|
|
||
| func main() { | ||
| if err := fn.AsMain(fn.ResourceListProcessorFunc(process)); err != nil { | ||
| os.Exit(1) | ||
| } | ||
| } | ||
|
|
||
| func process(rl *fn.ResourceList) (bool, error) { | ||
| for i := range rl.Items { | ||
| // Your transformation logic | ||
| rl.Items[i].SetAnnotation("processed-by", "my-fn") | ||
| } | ||
| return true, nil | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The code example has a compilation issue: main.go defines the process function with the build tag //go:build !(js && wasm), meaning it is excluded during WASM builds. However, main_js.go (with build tag //go:build js && wasm) references process on line 184 via fn.ResourceListProcessorFunc(process). Since process is not available during WASM builds, this code will fail to compile with GOOS=js GOARCH=wasm.
The process function should be placed in a third file (e.g., process.go) without any build tags, so it's available for both regular and WASM builds. This is the typical pattern used in the referenced krm-functions-catalog.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 2. Creates an OCI image with `wasm/js` platform | ||
| 3. Pushes to the registry |
There was a problem hiding this comment.
The platform format wasm/js here is inconsistent with OCI conventions. The OCI platform format is OS/Architecture, and looking at pkg/wasm/client.go:122-125, the platform is {OS: "js", Architecture: "wasm"}. This should be written as js/wasm to match the standard OCI platform format.
documentation/content/en/book/04-using-functions/wasm-functions.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // TODO: copy the implementation from main.go so behavior is consistent. | ||
| return false, nil |
There was a problem hiding this comment.
This example process function in the WASM build file has a TODO comment and returns false, nil without implementing any transformation logic. A user copying this documentation example would get a WASM function that does nothing (and returns false indicating no changes). The main.go version adds an annotation, but this version doesn't.
For a documentation example, the implementation should be consistent between the two files. Either duplicate the logic (adding the annotation) here, or refactor the example to show the recommended pattern of extracting shared logic into a separate file (e.g., processor.go) with no build tags, so both builds share the same process function. The latter pattern avoids the exact problem this code demonstrates — divergent implementations in WASM and non-WASM builds.
| // TODO: copy the implementation from main.go so behavior is consistent. | |
| return false, nil | |
| changed := false | |
| const annotationKey = "example.com/wasm" | |
| const annotationValue = "processed" | |
| for _, obj := range rl.Items { | |
| if obj == nil { | |
| continue | |
| } | |
| annotations := obj.GetAnnotations() | |
| if existing, ok := annotations[annotationKey]; ok && existing == annotationValue { | |
| continue | |
| } | |
| obj.SetAnnotation(annotationKey, annotationValue) | |
| changed = true | |
| } | |
| return changed, nil |
SurbhiAgarwal1
force-pushed
the
docs/wasm-function-support
branch
from
5b119ee to
46f7f9a
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
documentation/content/en/book/04-using-functions/wasm-functions.md
Outdated
Show resolved
Hide resolved
| - [kpt alpha wasm push](../../../reference/cli/alpha/wasm/push/) | ||
| - [kpt alpha wasm pull](../../../reference/cli/alpha/wasm/pull/) |
| WASM functions run in a sandbox: | ||
| - No network access | ||
| - No filesystem access (except input/output resources) | ||
| - Can't execute system commands | ||
|
|
||
| This is more secure but also more restrictive. | ||
|
|
| ### Using local WASM files | ||
|
|
||
| You can run local `.wasm` files with the `--exec` flag: | ||
|
|
||
| ```shell | ||
| kpt fn eval my-package --allow-alpha-wasm --exec ./my-function.wasm | ||
| ``` |
SurbhiAgarwal1
force-pushed
the
docs/wasm-function-support
branch
from
318480e to
76ebd1e
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| kpt fn render my-package --allow-alpha-wasm | ||
| ``` | ||
|
|
||
| kpt will detect the function as WASM if the OCI image has a `js/wasm` platform manifest. |
|
|
||
| - A language that compiles to WASM (Go, Rust, etc.) | ||
| - WASM build toolchain | ||
| - KRM functions SDK |
| WASM functions run in a sandbox: | ||
| - No network access | ||
| - No filesystem access (except input/output resources) | ||
| - Can't execute system commands | ||
|
|
||
| This is more secure but also more restrictive. |
| <-make(chan bool) | ||
| return nil |
SurbhiAgarwal1
force-pushed
the
docs/wasm-function-support
branch
from
96cfcf3 to
4f42b2c
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| WASM functions run in a sandbox: | ||
| - No network access | ||
| - No filesystem access (except input/output resources) | ||
| - Can't execute system commands | ||
|
|
||
| This is more secure but also more restrictive. |
| - [kpt alpha wasm push](../../../reference/cli/alpha/wasm/push/) | ||
| - [kpt alpha wasm pull](../../../reference/cli/alpha/wasm/pull/) |
| return js.FuncOf(func(this js.Value, args []js.Value) any { | ||
| rl, err := fn.ParseResourceList(*resourceList) | ||
| if err != nil { | ||
| return "" |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| js.Global().Set("processResourceList", resourceListWrapper(&resourceList)) | ||
| js.Global().Set("processResourceListErrors", resourceListErrors(&resourceList)) |
| You can run local `.wasm` files with the `--exec` flag: | ||
|
|
||
| ```shell | ||
| kpt fn eval my-package --allow-alpha-wasm --exec ./my-function.wasm |
| ### Test locally | ||
|
|
||
| ```shell | ||
| kpt fn eval ./test-package --allow-alpha-wasm --exec ./my-function.wasm |
| GOOS=js GOARCH=wasm go build -o my-function.wasm . | ||
|
|
||
| # 3. Test locally | ||
| kpt fn eval ./test-package --allow-alpha-wasm --exec ./my-function.wasm |
| "os" | ||
|
|
||
| "github.com/kptdev/krm-functions-sdk/go/fn" | ||
| ) | ||
|
|
||
| func main() { | ||
| if err := fn.AsMain(fn.ResourceListProcessorFunc(process)); err != nil { | ||
| os.Exit(1) | ||
| } | ||
| } | ||
|
|
||
| func process(rl *fn.ResourceList) (bool, error) { | ||
| for i := range rl.Items { | ||
| // Your transformation logic | ||
| rl.Items[i].SetAnnotation("processed-by", "my-fn") | ||
| } | ||
| return true, nil |
Add comprehensive documentation for WASM function support in kpt, covering how to run, develop, and deploy WASM functions. Closes kptdev#4296 Signed-off-by: Surbhi <agarwalsurbhi1807@gmail.com>
Replace <-make(chan bool) + return nil with select{} to avoid
the unreachable code and clarify the blocking intent.
Signed-off-by: Surbhi <agarwalsurbhi1807@gmail.com>
- Store js.Func values in package-level vars to prevent GC - Add --allow-exec flag to all fn eval --exec examples - Fix gofmt indentation in Go code snippets (tabs not spaces) Signed-off-by: Surbhi <agarwalsurbhi1807@gmail.com>
SurbhiAgarwal1
force-pushed
the
docs/wasm-function-support
branch
from
e316453 to
889fc1b
Compare
|
Hey @liamfallon ,I had addressed all the Copilot review comments:
Should be good to go now! |
| - WASM build toolchain | ||
| - KRM functions SDK | ||
|
|
||
| ### Example: Go WASM function |
There was a problem hiding this comment.
I would avoid adding code examples to the docs and maybe ref/link to an example function instead
| Push to a registry: | ||
|
|
||
| ```shell | ||
| kpt alpha wasm push ./my-function.wasm gcr.io/my-org/my-wasm-fn:v1.0.0 |
There was a problem hiding this comment.
Avoid referencing gcr.io
Maybe use a dummy registry example
|
|
||
| - [KRM Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md) | ||
| - [Functions Catalog](https://catalog.kpt.dev/) | ||
| - [kpt alpha wasm push](../../../reference/cli/alpha/wasm/push/) |
There was a problem hiding this comment.
Use relrefs, and make sure the docs preview renders the links correctly.
eg: ({{% relref "/reference/cli/alpha/wasm/push" %}})
- Replace Go code examples with link to starlark example in krm-functions-catalog - Replace gcr.io registry references with example.registry.io dummy registry Signed-off-by: Surbhi <agarwalsurbhi1807@gmail.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
documentation/content/en/book/04-using-functions/wasm-functions.md
Outdated
Show resolved
Hide resolved
|
|
||
| - A language that compiles to WASM (Go, Rust, etc.) | ||
| - WASM build toolchain | ||
| - KRM functions SDK |
| You can run local `.wasm` files with the `--exec` flag: | ||
|
|
||
| ```shell | ||
| kpt fn eval my-package --allow-alpha-wasm --allow-exec --exec ./my-function.wasm |
| kpt fn render my-package --allow-alpha-wasm | ||
| ``` | ||
|
|
||
| kpt will detect the function as WASM if the OCI image has a `js/wasm` platform manifest. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
documentation/content/en/book/04-using-functions/wasm-functions.md
Outdated
Show resolved
Hide resolved
documentation/content/en/book/04-using-functions/wasm-functions.md
Outdated
Show resolved
Hide resolved
| - [kpt alpha wasm push](../../../reference/cli/alpha/wasm/push/) | ||
| - [kpt alpha wasm pull](../../../reference/cli/alpha/wasm/pull/) |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Test locally | ||
|
|
||
| ```shell | ||
| kpt fn eval ./test-package --allow-alpha-wasm --allow-exec --exec ./my-function.wasm |
| # 3. Test locally | ||
| kpt fn eval ./test-package --allow-alpha-wasm --exec ./my-function.wasm | ||
|
|
| kpt fn render my-package --allow-alpha-wasm | ||
| ``` | ||
|
|
||
| kpt will detect the function as WASM if the OCI image has a `js/wasm` platform manifest. |
Description
WASM functions are supported in kpt but there's no documentation on how to run, develop, or deploy them. This PR adds a comprehensive guide covering the complete WASM function workflow.
Motivation
Users need documentation to understand:
--allow-alpha-wasmflagkpt alpha wasm push/pullWithout this documentation, users have to dig through code or CLI help to figure out WASM support.
Changes
Added
documentation/content/en/book/04-using-functions/wasm-functions.mdcovering:fn renderandfn evalThe code examples are based on actual WASM functions in krm-functions-catalog (set-namespace, set-labels, starlark) and follow the same pattern with separate build tags for regular and WASM builds.
Fixes #4296