kustomize docs tweaks

site/content/en/api-reference/kustomization/commonannotations/_index.md

@@ -6,7 +6,8 @@ description: >
     Add annotations to add all resources.
 ---
 
-Add annotations (non-identifying metadata) to all resources.  These are key value pairs.
+Add annotations to all resources.  If the annotation key already is present on the resource,
+the value will be overridden.
 
 ```yaml
 apiVersion: kustomize.config.k8s.io/v1beta1
@@ -15,3 +16,43 @@ kind: Kustomization
 commonAnnotations:
   oncallPager: 800-555-1212
 ```
+
+## Example
+
+### File Input
+
+```yaml
+# kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+commonAnnotations:
+  oncallPager: 800-555-1212
+
+resources:
+- deploy.yaml
+```
+
+```yaml
+# deploy.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: example
+spec:
+  ...
+```
+
+### Build Output
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: example
+  annotations:
+    oncallPager: 800-555-1212
+spec:
+  ...
+```
+

site/content/en/api-reference/kustomization/commonlabels/_index.md

@@ -6,7 +6,15 @@ description: >
     Add labels and selectors to add all resources.
 ---
 
-Add labels and selectors to all resources.
+Add labels and selectors to all resources.  If the label key already is present on the resource,
+the value will be overridden.
+
+{{% pageinfo color="warning" %}}
+Selectors for resources such as Deployments and Services shouldn't be changed once the
+resource has been applied to a cluster.
+
+Changing commonLabels to live resources could result in failures.
+{{% /pageinfo %}}
 
 ```yaml
 apiVersion: kustomize.config.k8s.io/v1beta1
@@ -17,3 +25,77 @@ commonLabels:
   owner: alice
   app: bingo
 ```
+
+## Example
+
+### File Input
+
+```yaml
+# kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+commonLabels:
+  someName: someValue
+  owner: alice
+  app: bingo
+
+resources:
+- deploy.yaml
+- service.yaml
+```
+
+```yaml
+# deploy.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: example
+```
+
+```yaml
+# service.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: example
+```
+
+### Build Output
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: bingo
+    owner: alice
+    someName: someValue
+  name: example
+spec:
+  selector:
+    app: bingo
+    owner: alice
+    someName: someValue
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app: bingo
+    owner: alice
+    someName: someValue
+  name: example
+spec:
+  selector:
+    matchLabels:
+      app: bingo
+      owner: alice
+      someName: someValue
+  template:
+    metadata:
+      labels:
+        app: bingo
+        owner: alice
+        someName: someValue
+```

site/content/en/api-reference/kustomization/patches/_index.md

@@ -6,10 +6,23 @@ description: >
     Patch resources
 ---
 
-Each entry in this list should resolve to patch object, which includes a patch and a target selector. 
-The patch can be either a strategic merge patch or a JSON patch.  It can be either a patch file, or an inline
-string. The target selects resources by group, version, kind, name, namespace, labelSelector and
-annotationSelector. Any resource which matches all the specified fields has the patch applied.
+[strategic merge]: /kustomize/api-reference/glossary#patchstrategicmerge
+[JSON]: /kustomize/api-reference/glossary#patchjson6902
+
+Patches (also call overlays) add or override fields on resources.  They are provided using the
+`patches` Kustomization field.
+
+The `patches` field contains a list of patches to be applied in the order they are specified.
+
+Each patch may:
+ 
+- be either a [strategic merge] patch, or a [JSON] patch
+- be either a file, or an inline string
+- target a single resource or multiple resources 
+
+The patch target selects resources by group, version, kind, name, namespace, labelSelector and
+annotationSelector.  Any resource which matches all the **specified** fields has the patch applied
+to it (regular expressions).
 
 ```yaml
 apiVersion: kustomize.config.k8s.io/v1beta1