Mention --default-label-scoping-rules CLI option

Mention the --default-label-scoping-rules=false CLI option,
add a FAQ section about kapp's labels, and cross-link the
docs in the apply section with the configuration.

Signed-off-by: Craig Ringer <[email protected]>

Author: ringerc

site/content/kapp/docs/develop/apply.md

@@ -8,6 +8,8 @@ Once change set is calculated (see [Diff](diff.md) section for details), kapp as
 
 Changes are applied in particular order as described in [Apply ordering](apply-ordering.md).
 
+### Resource labels
+
 All created resources are labeled with several labels:
 
 - `kapp.k14s.io/app` to track which application "owns" resource

site/content/kapp/docs/develop/config.md

@@ -128,7 +128,12 @@ See [ytt rebase rule](https://github.com/carvel-dev/kapp/blob/d3ee9a01b5f0d7d563
 
 ### labelScopingRules
 
-`labelScopingRules` specify locations for inserting kapp generated labels that scope resources to resources within current application. `kapp.k14s.io/disable-default-label-scoping-rules: ""` (as of v0.33.0+, or use `kapp.k14s.io/disable-label-scoping: ""` in earlier versions) annotation can be used to exclude an individual resource from label scoping.
+`labelScopingRules` specify locations for inserting [kapp generated labels](apply.md#resource-labels) that scope resources to resources within current application.
+
+The annotations `kapp.k14s.io/disable-default-label-scoping-rules: ""` (as of v0.33.0+, or use `kapp.k14s.io/disable-label-scoping: ""` in earlier versions) can be used to exclude an individual resource from label scoping.
+
+The global CLI option `--default-label-scoping-rules=false` can be used to disable addition of ownership labels
+entirely, but it's recommended to limit the scope of this option to specific use cases so kapp can do a better job of tracking the application's resources.
 
 ### waitRules
 

site/content/kapp/docs/develop/faq.md

@@ -125,3 +125,14 @@ Additional resources: [tty flag in kapp code](https://github.com/carvel-dev/kapp
 ## How can I get kapp to skip waiting on some resources?
 
 kapp allows to control waiting behavior per resource via [resource annotations](apply-waiting.md#controlling-waiting-via-resource-annotations). When used, the resource will be applied to the cluster, but will not wait to reconcile.
+
+---
+## Why does kapp add `kapp.k14s.io/app` labels to my resources?
+
+[`kapp` adds the label `kapp.k14s.io/app` and other related labels](apply.md#resource-labels) to keep track of which app resources are part of.
+
+This can cause issues in situations where controllers or custom resources are used to deploy resources, as it may result in mismatches between selectors and the resources selected, e.g. a service selector not matching any pods.
+
+It may also result in [Field is immutable errors](#-field-is-immutable-error) when updating resources that were not previously managed by `kapp`, so they lacked the kapp labels. See [migration](#migrating-from-kubectl-apply-to-kapp).
+
+See [label scoping rules](config#labelscopingrules) for details and configuration.