A guide for function SDK. It focuses more on explaining the fn editing patterns

yuwenma · yuwenma · commit 59df835236e8 · 2022-07-13T16:48:26.000-07:00
diff --git a/scripts/generate_site_sidebar/sidebar_template.md.tmpl b/scripts/generate_site_sidebar/sidebar_template.md.tmpl
@@ -68,5 +68,6 @@
   - [Namespace Provisioning UI](guides/namespace-provisioning-ui.md)
   - [Variant Constructor Pattern](guides/variant-constructor-pattern.md)
   - [Value Propagation Pattern](guides/value-propagation.md)
+  - [Effective Go KRM functions](guides/effective-go-krm-function.md)
 - [FAQ](faq/)
 - [Contact](contact/)
diff --git a/site/book/05-developing-functions/02-developing-in-Go.md b/site/book/05-developing-functions/02-developing-in-Go.md
@@ -18,6 +18,8 @@ You can develop a KRM function in Go using [the kpt function SDK].
 In this quickstart, we will write a function that adds an annotation 
 `config.kubernetes.io/managed-by=kpt` to all `Deployment` resources.
 
+This quickstart takes 15 minutes to finish.
+
 ### Initialize your project
 
 We start from a "get-started" package which contains a `main.go` file with some scaffolding code.
@@ -126,11 +128,13 @@ kpt fn eval ./data --image ${FN_CONTAINER_REGISTRY}/${FUNCTION_NAME}:${TAG}
 
 ## Next Steps
 
-- See other [go doc examples] to use KubeObject.
+- Read [effective go KRM function]
+- See the [go doc examples] to use KubeObject.
 - To contribute to KRM catalog functions, please follow the [contributor guide](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/CONTRIBUTING.md)
 
 [the kpt function SDK]: https://pkg.go.dev/github.com/GoogleContainerTools/kpt-functions-sdk/go/fn
 [go doc examples]: https://pkg.go.dev/github.com/GoogleContainerTools/kpt-functions-sdk/go/fn/examples
 [`fn`]: https://pkg.go.dev/github.com/GoogleContainerTools/kpt-functions-sdk/go/fn
 [`ResourceList`]: https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md
 [`unstructured.Unstrucutred`]: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1/unstructured
+[effective go KRM function]: guides/effective-go-krm-function.md
diff --git a/site/guides/README.md b/site/guides/README.md
@@ -7,4 +7,5 @@
 - [Namespace Provisioning CLI](guides/namespace-provisioning-cli.md)
 - [Namespace Provisioning UI](guides/namespace-provisioning-ui.md)
 - [Variant Constructor Pattern](guides/variant-constructor-pattern.md)
-- [Value Propagation Pattern](guides/value-propagation.md)
+- [Value Propagation Pattern](guides/value-propagation.md)
+- [Effective Go KRM functions](guides/effective-go-krm-function.md)
diff --git a/site/guides/effective-go-krm-function.md b/site/guides/effective-go-krm-function.md
@@ -0,0 +1,182 @@
+# Effective GO KRM functions
+
+This guide gives some tips on how to write your own KRM function to mutate or/and validate a package.
+
+This guide is for kpt beginners who are familiar with [Golang] and container runtime (e.g. Docker)
+
+Suggested prerequisite reading: [Developing in Go]
+
+## Prerequisites
+
+- [Install kpt]
+- [Install Docker]
+
+## Setup 
+
+<!--- TODO: Use scaffolding to generate the get-started package --->
+
+We start from a "get-started-simple" package which contains a `main.go` file with some scaffolding code.
+
+
+```shell
+# Set your KRM function name.
+export FUNCTION_NAME=<YOUR FUNCTION NAME>
+export GOPATH=$(go env GOPATH)
+export FUNCTION_PATH=github.com/<YOUR USERNAME>
+
+# Create and direct to your Go working directory
+mkdir -p $GOPATH/src/${FUNCTION_PATH} && cd $GOPATH/src/${FUNCTION_PATH}
+
+# Get the "get-started" package.
+kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-sdk.git/go/get-started-simple@master ${FUNCTION_NAME}
+
+cd ${FUNCTION_NAME}
+
+# Initialize Go module and install the kpt KRM function SDK.
+go mod init && go mod tidy -compat=1.17
+```
+
+## Write your KRM function code in Go 
+
+Let's write the `FunctionX` and `Run` method. 
+
+`FunctionX` implements the [`Runner`] interface 
+that can process the input KRM resources as [`fn.ResourceList`], it initializes `fn.KubeObject` to hold the KRM resources,
+so that you can call [`fn.KubeObject` and `fn.SubObject`] methods. Then it converts the modified `fn.KubeObjects` to KRM resources.
+
+### Add your configures in `FunctionX`
+
+If you need to use configurable variables, you can define them as `FunctionX` fields.
+Otherwise you can skip this step and move to next. 
+```go 
+type FunctionX struct {
+  FnConfigBool bool
+  FnConfigInt  int
+  FnConfigFoo string
+}
+```
+
+For example, define a `SetImage` and add two variables to compare-and-swap the image value.
+```go
+type SetImage struct {
+  OldImage string // Existing image
+  NewImage string // New image to replace
+}
+```
+
+The `SetImage` is a KRM resource. It should be passed from the input as:
+```yaml
+apiVersion: config.kubernetes.io/v1
+kind: ResourceList
+functionConfig:
+  apiVersion: fn.kpt.dev/v1alpha1
+  kind: SetImage
+  metadata:
+     name: try-out
+  oldImage: example
+  newImage: <YOUR NEW IMAGE NAME>
+items:
+...
+```
+<!--- TODO: we should not require users to understand and provide the input ResourceList. 
+We should build a test infra that users only provide the KRM resources--->
+
+### Add main logic in `Run`
+
+The SDK will initialize a slice of `*fn.KubeObject` to hold your KRM resources. You will need to pass the
+KRM resources from the input in `items` fields:
+```yaml
+apiVersion: config.kubernetes.io/v1
+kind: ResourceList
+functionConfig:
+  ...
+items:
+- apiVersion: apps/v1
+  kind: Deployment
+  ...
+- apiVersion: v1
+  kind: ConfigMap
+  data:
+    owner: kpt
+...
+```
+<!--- TODO: we should not require users to understand and provide the input ResourceList. 
+We should build a test infra that users only provide the KRM resources--->
+
+#### Select KRM resources 
+The `fn.KubeObjects` is a slice of `*fn.KubeObject`, that you can apply some select logic to easily choose
+the target KRM resources. See below example on using `Where` and `WhereNot`
+```go
+func (r *YourFunction) Run(context *fn.Context, functionConfig *fn.KubeObject, items fn.KubeObjects) {
+    namespaceScopedObjects := objects.Where(func(o *fn.KubeObject) bool { return o.IsNamespaceScoped() })
+    clusterScopedObjects := objects.Where(func(o *fn.KubeObject) bool { return o.IsClusterScoped() })
+    targetKindObjects := objects.Where(fn.IsGVK("", "", "CustomDeployment") })
+    excludeObjects := objects.WhereNot(fn.IsGVK("v1", "", "Namespace") })
+}
+```
+
+#### Read/Write a field path of a KRM resource
+
+Like [unstructured.Unstructured], `fn.KubeObject` (and `fn.SubObject`) provides a series of read and write 
+methods to let you read and write different types of resources. You can work on 
+
+```go
+func (r *YourFunction) Run(context *fn.Context, functionConfig *fn.KubeObject, items fn.KubeObjects) {
+	deployment := items.Where(fn.IsGVK("apps", "v1", "Deployment")).Where(func(o *fn.KubeObject) bool{return o.GetName() == "nginx"})[0]
+	replicas := deployment.NestedInt64OrDie("spec", "replicas")
+	fn.Logf("replicas is %v\n", replicas)
+    paused := obj.NestedBoolOrDie("spec", "paused")
+    fn.Logf("paused is %v\n", paused)
+    // Update strategy from Recreate to RollingUpdate.
+    if strategy := obj.NestedStringOrDie("spec", "strategy", "type"); strategy == "Recreate" {
+    	obj.SetNestedStringOrDie("RollingUpdate", "spec", "strategy", "type")
+    }
+}
+```
+
+Besides the [unstructured.Unstructured] style, you can also run functions on each sub-field as a `fn.SubObject`  
+```go
+func (r *YourFunction) Run(context *fn.Context, functionConfig *fn.KubeObject, items fn.KubeObjects) {
+    // operate each resource layer via `GetMap`
+	deployment := items.Where(fn.IsGVK("apps", "v1", "Deployment")).Where(func(o *fn.KubeObject) bool{return o.GetName() == "nginx"})[0]
+    spec := deployment.GetMap("spec")
+    replicas = spec.GetInt("replicas")
+    fn.Logf("replicas is %v\n", replicas)
+    nodeSelector := spec.GetMap("template").GetMap("spec").GetMap("nodeSelector")
+    if nodeSelector.GetString("disktype") != "ssd" {
+    nodeSelector.SetNestedStringOrDie("ssd", "disktype")
+}
+```
+
+#### Copy `KubeObject` to a typed struct
+
+If you already have some struct to define a KRM resource (like `corev1.ConfigMap`), you can switch the `KubeObject` 
+to the other type via `As`
+```go
+func (r *YourFunction) Run(context *fn.Context, functionConfig *fn.KubeObject, items fn.KubeObjects) {
+    deploymentObject := objects.WhereNot(fn.IsGVK("apps", "v1", "Deployment") })[0]
+    deploymentSpec := deploymentObject.GetMap("spec")
+	var dpSpec appsv1.DeploymentSpec
+    deploymentSpec.As(&dpSpec)
+    dpSpec.Size()
+}
+```
+
+<!-- TODO: We need a "Test the KRM function" section, which reuqires the SDK to provide the test infra so users only provide the input resource and expected output in YAML--->
+
+[Install kpt]:
+  https://kpt.dev/installation/
+[Install Docker]:
+  https://docs.docker.com/get-docker/
+[`fn.ResourceList`]:
+  https://pkg.go.dev/github.com/GoogleContainerTools/kpt-functions-sdk/go/fn#ResourceList
+[`fn.KubeObject` and `fn.SubObject`]:
+  https://pkg.go.dev/github.com/GoogleContainerTools/kpt-functions-sdk/go/fn#KubeObject
+[Golang]:
+  https://go.dev/doc/gopath_code
+[Runner]:
+  https://pkg.go.dev/github.com/GoogleContainerTools/kpt-functions-sdk/go/fn#Runner
+[unstructured.Unstructured]:
+  https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1/unstructured
+["Developing in Go"]:
+  https://kpt.dev/book/05-developing-functions/02-developing-in-Go
