docs for kpt fn exclude (#3022)

Author: natasha41575

site/book/04-using-functions/01-declarative-function-execution.md

@@ -325,12 +325,86 @@ Successfully executed 5 function(s) in 2 package(s).
 Note that the `ensure-name-substring` function is applied only to the 
 resources matching the selection criteria.
 
+If you have resources with particular labels or annotations that you want to use to
+select your resources, you can do so. For example, here is a function that will only
+be applied to resources matching the label `foo: bar`:
+
+```yaml
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: wordpress
+pipeline:
+  mutators:
+    - image: gcr.io/kpt-fn/set-annotations:v0.1
+      configMap:
+        tier: mysql
+      selectors:
+        - labels:
+            foo: bar
+  validators:
+    - image: gcr.io/kpt-fn/kubeval:v0.1
+```
+
 The following are the matchers you can specify in a selector:
 
 1. `apiVersion`: `apiVersion` field value of resources to be selected.
 2. `kind`: `kind` field value of resources to be selected.
 3. `name`: `metadata.name` field value of resources to be selected.
 4. `namespace`: `metadata.namespace` field of resources to be selected.
+5. `annotations`: resources with matching annotations will be selected.
+6. `labels`: resources with matching labels will be selected.
+
+### Specifying exclusions
+
+Similar to `selectors`, you can also specify resources that should be excluded from functions.
+
+For example, you can exclude a resource if it has both kind "Deployment" and name "nginx":
+
+```yaml
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: wordpress
+pipeline:
+  mutators:
+    - image: gcr.io/kpt-fn/set-annotations:v0.1
+      configMap:
+        tier: mysql
+      exclude:
+        - kind: Deployment
+          name: nginx
+  validators:
+    - image: gcr.io/kpt-fn/kubeval:v0.1
+```
+
+This is distinct from the following, which excludes a resource if it has either kind "Deployment" or name "nginx":
+
+```yaml
+apiVersion: kpt.dev/v1
+kind: Kptfile
+metadata:
+  name: wordpress
+pipeline:
+  mutators:
+    - image: gcr.io/kpt-fn/set-annotations:v0.1
+      configMap:
+        tier: mysql
+      exclude:
+        - kind: Deployment
+        - name: nginx
+  validators:
+    - image: gcr.io/kpt-fn/kubeval:v0.1
+```
+
+The following are the matchers you can specify in an exclusion:
+
+1. `apiVersion`: `apiVersion` field value of resources to be excluded.
+2. `kind`: `kind` field value of resources to be excluded.
+3. `name`: `metadata.name` field value of resources to be excluded.
+4. `namespace`: `metadata.namespace` field of resources to be excluded.
+5. `annotations`: resources with matching annotations will be excluded.
+6. `labels`: resources with matching labels will be excluded.
 
 [chapter 2]: /book/02-concepts/03-functions
 [render-doc]: /reference/cli/fn/render/

site/book/04-using-functions/02-imperative-function-execution.md

@@ -101,6 +101,34 @@ Here is the list of available selector matcher flags:
 2. `match-kind`
 3. `match-name`
 4. `match-namespace`
+5. `match-annotations`
+6. `match-labels`
+
+## Specifying `exclusions`
+
+Exclusions can be used to exclude specific resources for a function execution.
+
+For example, you can set the namespace of all resources in the wordpress package, 
+except for the ones with the label `foo: bar`:
+
+```shell
+$ kpt fn eval wordpress -i set-namespace:v0.1 --exclude-labels foo=bar -- namespace=my-namespace
+```
+
+If you use multiple exclusions, it will exclude resources that match all provided exclusions. For
+example, you can set the namespace of all resources, except for those that have both kind "Deployment" 
+and name "nginx":
+
+`$ kpt fn eval wordpress -i set-namespace:v0.1 --exclude-kind Deployment --exclude-name nginx -- namespace=my-namespace`
+
+Here is the list of available exclusion flags:
+
+1. `exclude-api-version`
+2. `exclude-kind`
+3. `exclude-name`
+4. `exclude-namespace`
+5. `exclude-annotations`
+6. `exclude-labels`
 
 ## Privileged Execution