Docs: Rationalize and document local-config annotation in the book (#4679)

Signed-off-by: Aravindhan Ayyanathan <aravindhan.a@est.tech>

Author: aravindtga

documentation/content/en/book/02-concepts/_index.md

@@ -186,6 +186,29 @@ kpt pkg get https://github.com/kubernetes/examples/tree/master/_archived/spark
 
 We will go into details of how to work with packages in [Chapter 3]({{% relref "/book/03-packages" %}}).
 
+### Local Configuration
+
+A package can contain resources that are used only during rendering and should not
+be applied to the cluster. These are called local configuration resources.
+Common examples include function configs (referenced via `configPath`) and helper
+resources used as input to pipeline functions.
+
+You mark a resource as local by adding the `config.kubernetes.io/local-config`
+annotation:
+
+```yaml
+metadata:
+  annotations:
+    config.kubernetes.io/local-config: "true"
+```
+
+When you deploy the package with `kpt live apply`, local configuration resources
+are automatically filtered out. They exist in the package solely to support the
+pipeline. See [Chapter 4]({{% relref "/book/04-using-functions" %}}) for how function configs use
+this annotation, and the
+[`local-config` annotation reference]({{% relref "/reference/annotations/local-config" %}}) for
+full details.
+
 ## Workflows
 
 In this section, we'll describe the typical workflows in kpt. We say "typical", because there is no single right way of

documentation/content/en/book/04-using-functions/_index.md

@@ -305,10 +305,16 @@ apiVersion: v1
 kind: ConfigMap
 metadata:
   name: labels
+  annotations:
+    config.kubernetes.io/local-config: "true"
 data:
   tier: mysql
 ```
 
+Note the `local-config` annotation: it ensures this resource is not applied to
+the cluster when you run `kpt live apply`. See
+[Marking function configs as local](#marking-function-configs-as-local) below.
+
 #### `configMap`
 
 Many functions take a `functionConfig` of kind `ConfigMap`, since they only need simple key/value pairs as an argument. For convenience, there is a way to inline the key/value pairs in the `Kptfile`.
@@ -368,6 +374,42 @@ The `configRef` fields are as follows:
 
 The reference must match exactly one resource in the package. An error is raised if zero or multiple resources match.
 
+### Marking function configs as local
+
+When you use `configPath` to reference a function config file, that resource is
+automatically excluded from the pipeline input (it is not passed to functions as
+a regular resource). However, the resource still exists in the package and will
+be sent to the cluster when you run `kpt live apply`, unless you mark it as
+local configuration.
+
+To prevent a function config from being applied to the cluster, add the
+`config.kubernetes.io/local-config` annotation:
+
+```yaml
+# wordpress/mysql/labels.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: labels
+  annotations:
+    config.kubernetes.io/local-config: "true"
+data:
+  tier: mysql
+```
+
+Resources with this annotation set to any value other than `"false"` are filtered
+out during `kpt live apply`. They remain in the package for use by the pipeline
+but are never sent to the cluster.
+
+This annotation is useful for:
+
+- Function configs referenced by `configPath`
+- Template or helper resources used only during rendering
+- Any resource that should exist in the package but not on the cluster
+
+For full details on the annotation schema and behavior, see the
+[`local-config` annotation reference]({{% relref "/reference/annotations/local-config" %}}).
+
 ### Specifying function `name`
 
 The functions can optionally be named using the `pipeline.mutators.name` field or the `pipeline.validators.name` field to identify a function.

documentation/content/en/book/06-deploying-packages/_index.md

@@ -129,6 +129,12 @@ Once a package is applied to the cluster, do not change the `ResourceGroup` CR.
 
 Once you have initialized the package, you can deploy it using `kpt live apply`.
 
+Note that not all resources in the package are applied to the cluster. Resources
+annotated with `config.kubernetes.io/local-config: "true"` are automatically
+filtered out. These are typically function configs or helper resources used only
+during rendering. The `Kptfile` itself is also excluded. For more details, see
+the [`local-config` annotation reference]({{% relref "/reference/annotations/local-config" %}}).
+
 The `wordpress` package requires a `Secret` containing the mysql password.
 Let's create that first: