improve fn authoring

kyaml/fn/framework/command/command.go

@@ -166,3 +166,35 @@ func (fr *deferredFileReader) Read(dest []byte) (int, error) {
 	}
 	return fr.srcReader.Read(dest)
 }
+
+// AsMain reads the resourceList in yaml format from stdin, evaluates the
+// function and write the updated resourceList in yaml to stdout. Errors if any
+// will be printed to stderr.
+func AsMain(p framework.ResourceListProcessor) error {
+	e := func() error {
+		in, err := ioutil.ReadAll(os.Stdin)
+		if err != nil {
+			return fmt.Errorf("unable to read from stdin: %v", err)
+		}
+		out, err := framework.Run(p, in)
+		if err != nil {
+			switch err.(type) {
+			case framework.Results, *framework.Results, framework.Result, *framework.Result:
+				// do nothing
+			default:
+				return err
+			}
+		}
+		// If there is an error and the error is Result(s), we don't return the
+		// error immediately. We write out to stdout before returning any error.
+		_, er := os.Stdout.Write(out)
+		if er != nil {
+			return fmt.Errorf("unable to write to stdout: %v", er)
+		}
+		return err
+	}()
+	if e != nil {
+		framework.Log(e)
+	}
+	return e
+}

kyaml/fn/framework/example_filter_GVK_test.go

@@ -0,0 +1,34 @@
+package framework_test
+
+import (
+	"os"
+
+	"sigs.k8s.io/kustomize/kyaml/fn/framework"
+	"sigs.k8s.io/kustomize/kyaml/fn/framework/command"
+)
+
+// This example implements a function that reads the desired replicas from the
+// functionConfig and updates the replicas field for all deployments.
+
+func Example_filterGVK() {
+	if err := command.AsMain(framework.ResourceListProcessorFunc(updateReplicas)); err != nil {
+		os.Exit(1)
+	}
+}
+
+// updateReplicas sets a field in resources selecting by GVK.
+func updateReplicas(rl *framework.ResourceList) error {
+	if rl.FunctionConfig == nil {
+		return framework.ErrMissingFnConfig{}
+	}
+	replicas, found, err := rl.FunctionConfig.GetNestedInt("replicas")
+	if !found || err != nil {
+		return err
+	}
+	for i, obj := range rl.Items {
+		if obj.GetApiVersion() == "apps/v1" && obj.GetKind() == "Deployment" {
+			rl.Items[i].SetOrDie(replicas, "spec", "replicas")
+		}
+	}
+	return nil
+}

kyaml/fn/framework/example_generator_test.go

@@ -0,0 +1,87 @@
+package framework_test
+
+import (
+	"fmt"
+	"io/ioutil"
+	"net/http"
+	"os"
+
+	"sigs.k8s.io/kustomize/kyaml/fn/framework"
+	"sigs.k8s.io/kustomize/kyaml/fn/framework/command"
+	"sigs.k8s.io/kustomize/kyaml/yaml"
+)
+
+// This function generates Graphana configuration in the form of ConfigMap. It
+// accepts Revision and ID as input.
+
+func Example_generator() {
+	if err := command.AsMain(framework.ResourceListProcessorFunc(generate)); err != nil {
+		os.Exit(1)
+	}
+}
+
+// generate generates a ConfigMap.
+func generate(rl *framework.ResourceList) error {
+	if rl.FunctionConfig == nil {
+		return framework.ErrMissingFnConfig{}
+	}
+
+	revision, foundRevision, err := rl.FunctionConfig.GetNestedString("data", "revision")
+	if err != nil {
+		return fmt.Errorf("failed to find field revision: %w", err)
+	}
+	id, foundId, err := rl.FunctionConfig.GetNestedString("data", "id")
+	if err != nil {
+		return fmt.Errorf("failed to find field id: %w", err)
+	}
+	if !foundRevision || !foundId {
+		return nil
+	}
+	js, err := fetchDashboard(revision, id)
+	if err != nil {
+		return fmt.Errorf("fetch dashboard: %v", err)
+	}
+
+	// corev1.ConfigMap should be used here. But we can't use it here due to dependency restriction in the kustomize repo.
+	cm := ConfigMap{
+		ResourceMeta: yaml.ResourceMeta{
+			TypeMeta: yaml.TypeMeta{
+				APIVersion: "v1",
+				Kind:       "ConfigMap",
+			},
+			ObjectMeta: yaml.ObjectMeta{
+				NameMeta: yaml.NameMeta{
+					Name:      fmt.Sprintf("%v-gen", rl.FunctionConfig.GetName()),
+					Namespace: rl.FunctionConfig.GetNamespace(),
+				},
+				Labels: map[string]string{
+					"grafana_dashboard": "true",
+				},
+			},
+		},
+		Data: map[string]string{
+			fmt.Sprintf("%v.json", rl.FunctionConfig.GetName()): fmt.Sprintf("%q", js),
+		},
+	}
+	return rl.UpsertObjectToItems(cm, nil, false)
+}
+
+func fetchDashboard(revision, id string) (string, error) {
+	url := fmt.Sprintf("https://grafana.com/api/dashboards/%s/revisions/%s/download", id, revision)
+	resp, err := http.Get(url)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	b, err := ioutil.ReadAll(resp.Body)
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}
+
+// ConfigMap is a copy of corev1.ConfigMap.
+type ConfigMap struct {
+	yaml.ResourceMeta `json:",inline" yaml:",inline"`
+	Data              map[string]string `json:"data,omitempty" yaml:"data,omitempty"`
+}

kyaml/fn/framework/example_logger_injector_test.go

@@ -0,0 +1,63 @@
+package framework_test
+
+import (
+	"fmt"
+	"os"
+
+	"sigs.k8s.io/kustomize/kyaml/fn/framework"
+	"sigs.k8s.io/kustomize/kyaml/fn/framework/command"
+	"sigs.k8s.io/kustomize/kyaml/yaml"
+)
+
+// In this example, we implement a function that injects a logger as a sidecar
+// container in workload APIs.
+
+func Example_loggeInjector() {
+	if err := command.AsMain(framework.ResourceListProcessorFunc(injectLogger)); err != nil {
+		os.Exit(1)
+	}
+}
+
+// injectLogger injects a logger container into the workload API resources.
+// generate implements the goframework.KRMFunction interface.
+func injectLogger(rl *framework.ResourceList) error {
+	var li LoggerInjection
+	if err := rl.FunctionConfig.As(&li); err != nil {
+		return err
+	}
+	for i, obj := range rl.Items {
+		if obj.GetApiVersion() == "apps/v1" && (obj.GetKind() == "Deployment" || obj.GetKind() == "StatefulSet" || obj.GetKind() == "DaemonSet" || obj.GetKind() == "ReplicaSet") {
+			var container Container
+			found, err := obj.Get(&container, "spec", "template", "spec", "containers", fmt.Sprintf("[name=%v]", li.ContainerName))
+			if err != nil {
+				return err
+			}
+			if found {
+				container.Image = li.ImageName
+			} else {
+				container = Container{
+					Name:  li.ContainerName,
+					Image: li.ImageName,
+				}
+			}
+			if err = rl.Items[i].Set(container, "spec", "template", "spec", "containers", fmt.Sprintf("[name=%v]", li.ContainerName)); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// LoggerInjection is type definition of the functionConfig.
+type LoggerInjection struct {
+	yaml.ResourceMeta `json:",inline" yaml:",inline"`
+
+	ContainerName string `json:"containerName" yaml:"containerName"`
+	ImageName     string `json:"imageName" yaml:"imageName"`
+}
+
+// Container is a copy of corev1.Container.
+type Container struct {
+	Name  string `json:"name" yaml:"name"`
+	Image string `json:"image,omitempty" yaml:"image,omitempty"`
+}

kyaml/fn/framework/example_mutate_comments_test.go

@@ -0,0 +1,38 @@
+package framework_test
+
+import (
+	"os"
+	"strings"
+
+	"sigs.k8s.io/kustomize/kyaml/fn/framework"
+	"sigs.k8s.io/kustomize/kyaml/fn/framework/command"
+)
+
+// In this example, we mutate line comments for field metadata.name.
+// Some function may want to store some information in the comments (e.g.
+// apply-setters function: https://catalog.kpt.dev/apply-setters/v0.2/)
+
+func Example_dMutateComments() {
+	if err := command.AsMain(framework.ResourceListProcessorFunc(mutateComments)); err != nil {
+		os.Exit(1)
+	}
+}
+
+func mutateComments(rl *framework.ResourceList) error {
+	for i := range rl.Items {
+		lineComment, err := rl.Items[i].GetLineComment("metadata", "name")
+		if err != nil {
+			return err
+		}
+
+		if strings.TrimSpace(lineComment) == "" {
+			lineComment = "# bar-system"
+		} else {
+			lineComment = strings.Replace(lineComment, "foo", "bar", -1)
+		}
+		if err = rl.Items[i].SetLineComment(lineComment, "metadata", "name"); err != nil {
+			return err
+		}
+	}
+	return nil
+}

kyaml/fn/framework/example_read_field_test.go

@@ -0,0 +1,29 @@
+package framework_test
+
+import (
+	"os"
+
+	"sigs.k8s.io/kustomize/kyaml/fn/framework"
+	"sigs.k8s.io/kustomize/kyaml/fn/framework/command"
+)
+
+// In this example, we read a field from the input object and print it to the log.
+
+func Example_aReadField() {
+	if err := command.AsMain(framework.ResourceListProcessorFunc(readField)); err != nil {
+		os.Exit(1)
+	}
+}
+
+func readField(rl *framework.ResourceList) error {
+	for _, obj := range rl.Items {
+		if obj.GetApiVersion() == "apps/v1" && obj.GetKind() == "Deployment" {
+			replicas, found, err := obj.GetNestedInt("spec", "replicas")
+			if !found || err != nil {
+				return err
+			}
+			framework.Logf("replicas is %v\n", replicas)
+		}
+	}
+	return nil
+}

kyaml/fn/framework/example_read_functionConfig_test.go

@@ -0,0 +1,33 @@
+package framework_test
+
+import (
+	"os"
+
+	"sigs.k8s.io/kustomize/kyaml/fn/framework"
+	"sigs.k8s.io/kustomize/kyaml/fn/framework/command"
+	"sigs.k8s.io/kustomize/kyaml/yaml"
+)
+
+// In this example, we convert the functionConfig as strong typed object and then
+// read a field from the functionConfig object.
+
+func Example_bReadFunctionConfig() {
+	if err := command.AsMain(framework.ResourceListProcessorFunc(readFunctionConfig)); err != nil {
+		os.Exit(1)
+	}
+}
+
+func readFunctionConfig(rl *framework.ResourceList) error {
+	var sr SetReplicas
+	if err := rl.FunctionConfig.As(&sr); err != nil {
+		return err
+	}
+	framework.Logf("desired replicas is %v\n", sr.DesiredReplicas)
+	return nil
+}
+
+// SetReplicas is the type definition of the functionConfig
+type SetReplicas struct {
+	yaml.ResourceIdentifier `json:",inline" yaml:",inline"`
+	DesiredReplicas         int `json:"desiredReplicas,omitempty" yaml:"desiredReplicas,omitempty"`
+}

kyaml/fn/framework/example_set_field_test.go

@@ -0,0 +1,25 @@
+package framework_test
+
+import (
+	"os"
+
+	"sigs.k8s.io/kustomize/kyaml/fn/framework"
+	"sigs.k8s.io/kustomize/kyaml/fn/framework/command"
+)
+
+// In this example, we read a field from the input object and print it to the log.
+
+func Example_cSetField() {
+	if err := command.AsMain(framework.ResourceListProcessorFunc(setField)); err != nil {
+		os.Exit(1)
+	}
+}
+
+func setField(rl *framework.ResourceList) error {
+	for _, obj := range rl.Items {
+		if obj.GetKind() == "Deployment" && obj.GetName() == "nginx" {
+			return obj.Set(10, "spec", "replicas")
+		}
+	}
+	return nil
+}

kyaml/fn/framework/example_validator_test.go

@@ -0,0 +1,33 @@
+package framework_test
+
+import (
+	"os"
+
+	"sigs.k8s.io/kustomize/kyaml/fn/framework"
+	"sigs.k8s.io/kustomize/kyaml/fn/framework/command"
+)
+
+// This example implements a function that validate resources to ensure
+// spec.template.spec.securityContext.runAsNonRoot is set in workload APIs.
+
+func Example_validator() {
+	if err := command.AsMain(framework.ResourceListProcessorFunc(validator)); err != nil {
+		os.Exit(1)
+	}
+}
+
+func validator(rl *framework.ResourceList) error {
+	var results framework.Results
+	for _, obj := range rl.Items {
+		if obj.GetApiVersion() == "apps/v1" && (obj.GetKind() == "Deployment" || obj.GetKind() == "StatefulSet" || obj.GetKind() == "DaemonSet" || obj.GetKind() == "ReplicaSet") {
+			runAsNonRoot, _, err := obj.GetNestedBool("spec", "template", "spec", "securityContext", "runAsNonRoot")
+			if err != nil {
+				return framework.ErrorConfigObjectResult(err, obj)
+			}
+			if !runAsNonRoot {
+				results = append(results, framework.ConfigObjectResult("`spec.template.spec.securityContext.runAsNonRoot` must be set to true", obj, framework.Error))
+			}
+		}
+	}
+	return results
+}