diff --git a/documentation/content/en/book/02-concepts/_index.md b/documentation/content/en/book/02-concepts/_index.md index e58cf33e97..ba77724eab 100644 --- a/documentation/content/en/book/02-concepts/_index.md +++ b/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](../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](../04-using-functions/) for how function configs use +this annotation, and the +[`local-config` annotation reference](/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 diff --git a/documentation/content/en/book/04-using-functions/_index.md b/documentation/content/en/book/04-using-functions/_index.md index b379ae47ca..f3d1e566ec 100644 --- a/documentation/content/en/book/04-using-functions/_index.md +++ b/documentation/content/en/book/04-using-functions/_index.md @@ -302,10 +302,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`. @@ -365,6 +371,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](/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. diff --git a/documentation/content/en/book/06-deploying-packages/_index.md b/documentation/content/en/book/06-deploying-packages/_index.md index aca6136a1c..480d787630 100644 --- a/documentation/content/en/book/06-deploying-packages/_index.md +++ b/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](/reference/annotations/local-config/). + The `wordpress` package requires a `Secret` containing the mysql password. Let's create that first: