[WIP] Function SDK guide #3367

yuwenma · 2022-07-13T23:48:43Z

This guide focuses on explaining the KRM resource editing patterns.

…g patterns

justinsb · 2022-07-14T16:06:51Z

site/guides/effective-go-krm-function.md

+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-runner@master ${FUNCTION_NAME}


This line didn't work for me ...

Error: path "/go/get-started-runner" does not exist in repo "https://github.com/GoogleContainerTools/kpt-functions-sdk"

Do I need to merge a PR in kpt-functions-sdk?

justinsb · 2022-07-14T16:08:24Z

site/guides/effective-go-krm-function.md

+    }
+}
+```
+`FunctionX` implements the [`Runner`] interface that can process the input KRM resources as [`fn.ResourceList`], it initializes `fn.KubeObject` to hold the KRM resources,


Do we need to mention ResourceList?

justinsb · 2022-07-14T16:10:02Z

site/guides/effective-go-krm-function.md

+}
+```
+`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 use [`fn.KubeObject` and `fn.SubObject`] methods directly. After `Run`, it will convert the modified `fn.KubeObjects` to KRM resources.


Instead of "it initializes fn.KubeObject to hold the KRM resources, so that you can use [fn.KubeObject and fn.SubObject] methods directly", I would just say that something like "the objects passed to the function are available in items. These objects can be modified in place and are used as the output of the function".

justinsb · 2022-07-14T16:10:25Z

site/guides/effective-go-krm-function.md

+`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 use [`fn.KubeObject` and `fn.SubObject`] methods directly. After `Run`, it will convert the modified `fn.KubeObjects` to KRM resources.
+
+### Define configures


Maybe Define function parameters or Define function arguments?

justinsb · 2022-07-14T16:11:11Z

site/guides/effective-go-krm-function.md

+Otherwise you can skip this step and move to next. 
+```go 
+type FunctionX struct {
+  FnConfigBool bool


Maybe SomeBoolValue, SomeIntValue, SomeStringValue instead of the FnConfig prefix - otherwise the question is whether the FnConfig prefix matters

justinsb · 2022-07-14T16:13:36Z

site/guides/effective-go-krm-function.md

+## Write the 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.


I think we've said this already?

justinsb · 2022-07-14T16:14:12Z

site/guides/effective-go-krm-function.md

+    // clusterScoped contains only cluster scoped resources
+    clusterScoped := objects.Where(func(o *fn.KubeObject) bool { return o.IsClusterScoped() })
+    // customDeployment contains all resources of Kind "CustomDeployment", in Group "fn.kpt.dev" with any Versions.  
+    customDeployment := objects.Where(fn.IsGVK("fn.kpt.dev", "", "CustomDeployment") })


Nit: I would support IsGK instead of IsGVK with a magic empty value

justinsb · 2022-07-14T16:14:39Z

site/guides/effective-go-krm-function.md

+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` to filter different types of resources.
+```go
+func (r *YourFunction) Run(context *fn.Context, functionConfig *fn.KubeObject, items fn.KubeObjects) {


Nit: if these are just examples, don't wrap them in a Run function ... otherwise users will think we're actually doing something here....

justinsb · 2022-07-14T16:15:34Z

site/guides/effective-go-krm-function.md

+```go
+func (r *YourFunction) Run(context *fn.Context, functionConfig *fn.KubeObject, items fn.KubeObjects) {
+	// Get first deployment object.
+	deployment := items.Where(fn.IsGVK("apps", "v1", "Deployment")).Where(func(o *fn.KubeObject) bool{return o.GetName() == "nginx"})[0]


We probably want HasName or IsName, but OTOH it is helpful to spell this out.

You could spell it out, and then say "you can also use the IsName helper method, which produces the same filter function"

justinsb · 2022-07-14T16:16:29Z

site/guides/effective-go-krm-function.md

+### 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`


I would add an explicit warning that this copies the object and thus you have to copy it back

droot

Thanks for writing this. I have a few minor comments.

droot · 2022-07-14T15:57:05Z

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.


nit: config.kubernetes.io/managed-by:kpt ( s/=/:)

droot · 2022-07-14T16:07:34Z

site/guides/effective-go-krm-function.md

+This guide gives tips to effectively write a KRM function. 
+
+This guide is for advanced kpt function users who find the [catalog.kpt.dev] cannot fulfil their needs 
+and want to design their own KRM functions. 


I think advanced kpt users can confuse users and might discourage users to read further.

Maybe we can combine this line and previous line with something along the lines of ...

This guide describes best practices and patterns on how to structure your Go KRM functions.

droot · 2022-07-14T16:08:05Z

site/guides/effective-go-krm-function.md

+This guide is for advanced kpt function users who find the [catalog.kpt.dev] cannot fulfil their needs 
+and want to design their own KRM functions. 
+
+Suggest reading [Developing in Go] first


nit . missing at the end.

droot · 2022-07-14T16:10:05Z

site/guides/effective-go-krm-function.md

+## Prerequisites
+
+- [Install kpt]
+- [Install Docker]


It will be good to specify minimum version of Go. I think Go 1.17+ is what we have been using for the toolset.

droot · 2022-07-14T16:13:40Z

site/guides/effective-go-krm-function.md

+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-runner@master ${FUNCTION_NAME}


Assuming myself as a Go developer, I will find this step to be awkward :) and I will also be surprised to see files such as Kptfile etc. It might get confusing. Can we just use git clone or something to fetch the skeleton code ?

droot · 2022-07-14T16:23:39Z

site/guides/effective-go-krm-function.md

+```go
+func (r *YourFunction) Run(context *fn.Context, functionConfig *fn.KubeObject, items fn.KubeObjects) {
+    // Get first deployment object.
+	deployment := items.Where(fn.IsGVK("apps", "v1", "Deployment")).Where(func(o *fn.KubeObject) bool{return o.GetName() == "nginx"})[0]


I think it's okay to have this expression in multiple lines that helps with readability.

droot · 2022-07-14T16:26:02Z

site/sidebar.md

@@ -107,5 +107,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)


Would it makes sense to have it alongside Getting Started instead of guides ?

yuwenma requested review from bgrant0607, droot, justinsb, mengqiy, mortent and natasha41575 as code owners July 13, 2022 23:48

yuwenma changed the title ~~Function SDK guide~~ [WIP] Function SDK guide Jul 13, 2022

A guide for function SDK. It focuses more on explaining the fn editin…

9767e0d

…g patterns

yuwenma force-pushed the sdk-doc branch from 59df835 to 9767e0d Compare July 14, 2022 07:09

justinsb reviewed Jul 14, 2022

View reviewed changes

droot reviewed Jul 14, 2022

View reviewed changes

yuwenma mentioned this pull request Jul 29, 2022

docs: Write a "effective-go-krm-function" guide #3420

Open

3 tasks

yuwenma mentioned this pull request Nov 4, 2022

feat: add example for effective go krm function kptdev/krm-functions-sdk#602

Merged

		@@ -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.

[WIP] Function SDK guide #3367

Are you sure you want to change the base?

[WIP] Function SDK guide #3367

Uh oh!

Conversation

yuwenma commented Jul 13, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

droot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!