add examples, guides and README

examples/set-namespace-v2-simple/.expected/diff.patch

@@ -0,0 +1,43 @@
+diff --git a/resources.yaml b/resources.yaml
+index 85885ac..f93e6a4 100644
+--- a/resources.yaml
++++ b/resources.yaml
+@@ -2,12 +2,12 @@ apiVersion: v1
+ kind: Service
+ metadata:
+   name: the-service
+-  namespace: example
++  namespace: example-ns
+ ---
+ apiVersion: v1
+ kind: Namespace
+ metadata:
+-  name: example
++  name: example-ns
+ ---
+ apiVersion: apiextensions.k8s.io/v1
+ kind: CustomResourceDefinition
+@@ -20,7 +20,7 @@ spec:
+       clientConfig:
+         service:
+           name: crd-svc
+-          namespace: example
++          namespace: example-ns
+ ---
+ apiVersion: apiregistration.k8s.io/v1
+ kind: APIService
+@@ -29,7 +29,7 @@ metadata:
+ spec:
+   service:
+     name: api-svc
+-    namespace: example
++    namespace: example-ns
+ ---
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRoleBinding
+@@ -38,4 +38,4 @@ metadata:
+ subjects:
+   - kind: ServiceAccount
+     name: default
+-    namespace: example
++    namespace: example-ns

examples/set-namespace-v2-simple/.krmignore

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

examples/set-namespace-v2-simple/Kptfile

@@ -0,0 +1,9 @@
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: example
+pipeline:
+  mutators:
+    - image: gcr.io/kpt-fn/set-namespace-v2:unstable
+      configMap:
+        namespace: example-ns

examples/set-namespace-v2-simple/README.md

@@ -0,0 +1,44 @@
+# set-namespace-v2: Simple example
+
+### Overview
+
+This example demonstrates how to run [`set-namespace`] function
+to replace the  `namespace` resource type in a variety of KRM resources.
+
+### Fetch the example package
+
+Get the example package by running the following commands:
+
+```shell
+$ kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-catalog.git/examples/set-namespace-v2-simple
+```
+
+We use the following `Kptfile` to configure the function.
+
+```yaml
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: example
+pipeline:
+  mutators:
+    - image: gcr.io/kpt-fn/set-namespace-v2:unstable
+      configMap:
+        namespace: example-ns
+```
+
+The function configuration is provided using a `ConfigMap`. We set only one
+key-value pair:
+- `namespace: example-ns`: The desired namespace.
+
+### Function invocation
+
+Invoke the function by running the following commands:
+
+```shell
+$ kpt fn render set-namespace-v2
+```
+
+### Expected result
+
+Check all resources have `metadata.namespace` set to `example-ns`

examples/set-namespace-v2-simple/resources.yaml

@@ -0,0 +1,41 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: the-service
+  namespace: example
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: example
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: the-crd
+spec:
+  conversion:
+    strategy: Webhook
+    webhook:
+      clientConfig:
+        service:
+          name: crd-svc
+          namespace: example
+---
+apiVersion: apiregistration.k8s.io/v1
+kind: APIService
+metadata:
+  name: the-api-service
+spec:
+  service:
+    name: api-svc
+    namespace: example
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: crb1
+subjects:
+  - kind: ServiceAccount
+    name: default
+    namespace: example

functions/go/Makefile

@@ -35,7 +35,7 @@ FUNCTIONS := \
 	set-enforcement-action \
 	set-image \
 	set-labels \
-	set-namespace \
+	set-namespace-v2 \
 	set-project-id \
 	source-gcloud-config \
 	starlark \

functions/go/set-namespace-v2/README.md

@@ -0,0 +1,82 @@
+# set-namespace-v2
+
+## Overview
+
+<!--mdtogo:Short-->
+
+The `set-namespace-v2` function replace the `namespace` specific resource type in a variety
+of KRM resources.
+
+<!--mdtogo-->
+
+<!--mdtogo:Long-->
+
+## Usage
+
+This function can be used with any KRM function orchestrators (e.g. kpt).
+
+- If the resource is `Namespace`, `set-namespace-v2` updates the `metadata.name` field.
+- If the resource is `RoleBinding` or `ClusterRoleBinding` resource, the function updates 
+  the namespace field in the `subjects` element whose name is `default`.
+- If the resource is `CustomResourceDefinition` (CRD), `set-namespace-v2` updates the 
+  `spec/conversion/webhook/clientConfig/service/namespace` field.
+- If the resource is `APIService`, `set-namespace-v2` updates the
+  `spec/service/namespace` field.
+- If there is a [`depends-on`] annotation for a namespaced resource, the namespace
+  section of the annotation will be updated if the referenced resource is also
+  declared in the package.
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: sa
+  namespace: example
+  annotations:
+    config.kubernetes.io/depends-on: /namespaces/example/ServiceAccount/foo # <= this will NOT be updated (resource not declared)
+---
+kind: RoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  ...
+  annotations:
+    config.kubernetes.io/depends-on: /namespaces/example/ServiceAccount/sa # <== this will be updated (resource declared)
+subjects:
+  - kind: ServiceAccount
+    name: default # <================== name default is used
+    namespace: example # <================== this will be updated
+roleRef:
+  kind: Role
+  name: confluent-operator
+  apiGroup: rbac.authorization.k8s.io
+```
+
+This function can be used both declaratively and imperatively.
+
+### FunctionConfig
+
+There are 2 kinds of `functionConfig` supported by this function:
+
+- `ConfigMap`
+- A custom resource of kind `SetNamespace`
+
+To use a `ConfigMap` as the `functionConfig`, the desired namespace must be
+specified in the `data.namespace` field.
+
+To add a namespace `staging` to all resources, we use the
+following `functionConfig`:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: my-config
+data:
+  namespace: staging
+```
+
+<!--mdtogo-->
+
+[namespace]: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/
+
+[depends-on]: https://kpt.dev/reference/annotations/depends-on/

functions/go/set-namespace-v2/main.go

@@ -29,27 +29,20 @@ func main() {
 func run(rl *fn.ResourceList) error {
 	tc := NamespaceTransformer{}
 	// Get "namespace" arguments from FunctionConfig
-	if err := tc.Config(rl.FunctionConfig); err != nil {
-		rl.Results = fn.Results{
-			{
-				Severity: fn.Error,
-				Message: err.Error(),
-			},
-		}
+	err := tc.Config(rl.FunctionConfig)
+	if err != nil {
+		rl.Results = append(rl.Results, fn.ErrorConfigObjectResult(err, rl.FunctionConfig))
 		return nil
 	}
 	// Update "namespace" to the proper resources.
 	tc.Transform(rl.Items)
+	var result *fn.Result
 	if len(tc.Errors) != 0 {
-		rl.Results =  fn.Results{
-			{
-				Severity: fn.Error,
-				Message: strings.Join(tc.Errors, "\n"),
-			},
-		}
+		errMsg := strings.Join(tc.Errors, "\n")
+		result = fn.GeneralResult(errMsg, fn.Error)
 	} else {
-		rl.Results = append(rl.Results,
-			&fn.Result{Severity: fn.Info, Message: "namespace updated"})
+		result = fn.GeneralResult("namespace updated", fn.Info)
 	}
+	rl.Results = append(rl.Results, result)
 	return nil
 }

functions/go/set-namespace-v2/metadata.yaml

@@ -0,0 +1,10 @@
+image: gcr.io/kpt-fn/set-namespace-v2
+description: Update namespace.
+tags:
+  - mutator
+sourceURL: https://github.com/GoogleContainerTools/kpt-functions-catalog/tree/master/functions/go/set-namespace-v2
+examplePackageURLs:
+  - https://github.com/GoogleContainerTools/kpt-functions-catalog/tree/master/examples/set-namespace-v2-simple
+emails:
+  - [email protected]
+license: Apache-2.0