diff --git a/site/book/04-using-functions/01-declarative-function-execution.md b/site/book/04-using-functions/01-declarative-function-execution.md index 6bf9e39e09..cded4fd0ba 100644 --- a/site/book/04-using-functions/01-declarative-function-execution.md +++ b/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/ diff --git a/site/book/04-using-functions/02-imperative-function-execution.md b/site/book/04-using-functions/02-imperative-function-execution.md index b108b26cca..cb851eff9e 100644 --- a/site/book/04-using-functions/02-imperative-function-execution.md +++ b/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