support exec args (#2272)

* support exec args

* update book

* code review

* code review

Author: Shell32-Natsu

e2e/testdata/fn-eval/exec-function-with-args/.expected/diff.patch

@@ -0,0 +1,21 @@
+diff --git a/resources.yaml b/resources.yaml
+index e8ae6bb..297b99f 100644
+--- a/resources.yaml
++++ b/resources.yaml
+@@ -15,7 +15,7 @@ apiVersion: apps/v1
+ kind: Deployment
+ metadata:
+   name: nginx-deployment
+-  namespace: foo
++  namespace: bar
+ spec:
+   replicas: 3
+ ---
+@@ -23,6 +23,6 @@ apiVersion: custom.io/v1
+ kind: Custom
+ metadata:
+   name: custom
+-  namespace: foo
++  namespace: bar
+ spec:
+   image: nginx:1.2.3

e2e/testdata/fn-eval/exec-function-with-args/.expected/exec.sh

@@ -0,0 +1,18 @@
+#! /bin/bash
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -eo pipefail
+
+kpt fn eval --exec "sed -e 's/foo/bar/'"

e2e/testdata/fn-eval/exec-function-with-args/.krmignore

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

e2e/testdata/fn-eval/exec-function-with-args/resources.yaml

@@ -0,0 +1,28 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-deployment
+  namespace: foo
+spec:
+  replicas: 3
+---
+apiVersion: custom.io/v1
+kind: Custom
+metadata:
+  name: custom
+  namespace: foo
+spec:
+  image: nginx:1.2.3

go.mod

@@ -5,6 +5,7 @@ go 1.16
 require (
 	github.com/cpuguy83/go-md2man/v2 v2.0.0
 	github.com/go-errors/errors v1.4.0
+	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
 	github.com/igorsobreira/titlecase v0.0.0-20140109233139-4156b5b858ac
 	github.com/philopon/go-toposort v0.0.0-20170620085441-9be86dbd762f
 	github.com/posener/complete/v2 v2.0.1-alpha.12

internal/docs/generated/fndocs/docs.go

@@ -26,6 +26,8 @@ type Result struct {
 	// Image and Exec are mutually exclusive
 	Image string `yaml:"image,omitempty"`
 	// ExecPath is the the absolute os-specific path to the executable file
+	// If user provides an executable file with commands, ExecPath should
+	// contain the entire input string.
 	ExecPath string `yaml:"exec,omitempty"`
 	// TODO(droot): This is required for making structured results subpackage aware.
 	// Enable this once test harness supports filepath based assertions.

pkg/api/fnresult/v1alpha2/types.go

@@ -94,9 +94,7 @@ Currently supported platforms: amd64 Linux/Mac
    ```
 
    ```shell
-   $ kpt fn source $CONFIGS \
-     | node dist/label_namespace_run.js -d label_name=color -d label_value=orange \
-     | kpt fn sink $CONFIGS
+   $ kpt fn eval $CONFIGS --exec "node dist/label_namespace_run.js" -- label_name=color label_value=orange
    ```
 
    As the name suggests, this function added the given label to all `Namespace`
@@ -142,9 +140,7 @@ Currently supported platforms: amd64 Linux/Mac
 1. Run `validate-rolebinding` on `example-configs`.
 
    ```shell
-   $ kpt fn source $CONFIGS \
-     | node dist/validate_rolebinding_run.js -d [email protected] \
-     | kpt fn sink $CONFIGS
+   $ kpt fn eval $CONFIGS --exec "node dist/validate_rolebinding_run.js" -- [email protected]
    ```
 
    Look at the changes made by the function:
@@ -219,9 +215,7 @@ Currently supported platforms: amd64 Linux/Mac
 1. Run `expand-team-cr` on `example-configs`.
 
    ```shell
-   $ kpt fn source $CONFIGS \
-    | node dist/expand_team_cr_run.js \
-    | kpt fn sink $CONFIGS
+   $ kpt fn eval $CONFIGS --exec "node dist/expand_team_cr_run.js"
    ```
 
    Look at the changes made by the function:

site/book/05-developing-functions/03-developing-in-Typescript.md

@@ -65,10 +65,11 @@ fn-args:
   the key of an already exported environment variable.
 
 --exec:
-  Path to the local executable binary to execute as a function. `eval` executes
-  only one function, so do not use `--image` flag with this flag. This is useful
-  for testing function locally during development. It enables faster dev iterations
-  by avoiding the function to be published as container image.
+  Path to the local executable binary to execute as a function. Quotes are needed
+  if the executable requires arguments. `eval` executes only one function, so do
+  not use `--image` flag with this flag. This is useful for testing function locally
+  during development. It enables faster dev iterations by avoiding the function to
+  be published as container image.
 
 --fn-config:
   Path to the file containing `functionConfig` for the function.
@@ -146,6 +147,12 @@ $ kpt fn eval DIR -i gcr.io/example.com/my-fn:v1.0.0 -- foo=bar
 $ kpt fn eval DIR --exec ./my-fn
 ```
 
+```shell
+# execute executable my-fn with arguments on the resources in DIR directory and
+# write output back to DIR
+$ kpt fn eval DIR --exec "./my-fn arg1 arg2"
+```
+
 ```shell
 # execute container my-fn on the resources in DIR directory,
 # save structured results in /tmp/my-results dir and write output back to DIR

site/reference/cli/fn/eval/README.md

@@ -150,19 +150,11 @@ runtime.
 
 ### Steps
 
-1. Use the pkg CLI to create an executable from your function's distributable
-   file. For a `my_fn` function built using the typescript SDK, this is
-   `dist/my_fn_run.js`.
-
-   ```shell
-   $ npx pkg dist/my_func_run.js
-   ```
-
 1. Pass the path to the appropriate executable for your OS when running kpt
    using the exec runtime.
 
    ```shell
-   $ kpt fn eval DIR --exec ./my_func_run-macos
+   $ kpt fn eval DIR --exec "node dist/my_func_run.js"
    ```
 
 ## Build and push container images