From 86bcb47b7d04eb47c9b87e1ba759dd7890c556d2 Mon Sep 17 00:00:00 2001
From: Jeffrey Regan <jregan@google.com>
Date: Mon, 6 Apr 2020 16:16:33 -0700
Subject: [PATCH] Better multi-patch demo.

---
 examples/jsonpatch.md            |  16 ++-
 examples/patchMultipleObjects.md | 173 +++++++++++++++++--------------
 2 files changed, 109 insertions(+), 80 deletions(-)

diff --git a/examples/jsonpatch.md b/examples/jsonpatch.md
index 2ed60d6f0..7c9a843e0 100644
--- a/examples/jsonpatch.md
+++ b/examples/jsonpatch.md
@@ -1,6 +1,10 @@
-# Demo: applying a json patch
+# JSON Patching
 
-A kustomization file supports customizing resources via [JSON patches](https://tools.ietf.org/html/rfc6902).
+[JSON patches]: https://tools.ietf.org/html/rfc6902
+[JSON patch]: https://tools.ietf.org/html/rfc6902
+
+A kustomization file supports customizing
+resources via [JSON patches].
 
 Make a place to work:
 
@@ -140,9 +144,8 @@ Confirm they match:
 diff $DEMO_HOME/out_actual.yaml $DEMO_HOME/out_expected.yaml
 ```
 
-Let's further edit the same `Ingress` object,
-but using a patch written in YAML instead of JSON.
-
+If you prefer YAML to JSON, the patch can be expressed
+in YAML format (neverthless following [JSON patch] rules):
 
 <!-- @writeYamlPatch @testAgainstLatestRelease -->
 ```
@@ -193,3 +196,6 @@ Try it:
 kustomize build $DEMO_HOME | tail -n 8 |\
     diff  $DEMO_HOME/out_expected.yaml -
 ```
+
+To see how to apply one JSON patch to many resources,
+see the [multi-patch](../patchMultipleObjects.md) demo.
diff --git a/examples/patchMultipleObjects.md b/examples/patchMultipleObjects.md
index cf7421efe..b6519a2c5 100644
--- a/examples/patchMultipleObjects.md
+++ b/examples/patchMultipleObjects.md
@@ -1,43 +1,78 @@
-[Strategic Merge Patch]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md
-[JSON patches]: https://tools.ietf.org/html/rfc6902
-[label selector]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
+# Patching multiple resources at once.
+
+kustomize supports patching via either a
+[strategic merge patch] (wherein you
+partially re-specify the thing you want to
+modify, with in-place changes) or a
+[JSON patch] (wherein you specify specific
+operation/target/value tuples in a particular
+syntax).
+
+A kustomize file lets one specify many
+patches.  Each patch must be associated with
+a _target selector_:
+
+[strategic merge patch]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md
+[JSON patch]: ../jsonpatch.md
+
+> ```yaml
+> patches:
+> - path: <relative path to file containing patch>
+>   target:
+>     group: <optional group>
+>     version: <optional version>
+>     kind: <optional kind>
+>     name: <optional name>
+>     namespace: <optional namespace>
+>     labelSelector: <optional label selector>
+>     annotationSelector: <optional annotation selector>
+> ```
+
+E.g. select resources with _name_ matching `foo*`:
+
+> ```yaml
+> target:
+>   name: foo*
+> ```
+
+Select all resources of _kind_ `Deployment`:
+
+> ```yaml
+> target:
+>   kind: Deployment
+> ```
+
+[label/annotation selector rules]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
+
+Using multiple fields just makes the target
+more specific. The following selects only
+Deployments that also have the _label_ `app=hello`
+(full [label/annotation selector rules]):
+
+> ```yaml
+> target:
+>   kind: Deployment
+>   labelSelector: app=hello
+> ```
+
+### Demo
+
+The example below shows how to inject a
+sidecar container for multiple Deployment
+resources.
 
 
-# Demo: applying a patch to multiple resources
+Make a place to work:
 
-A kustomization file supports customizing resources via both
-[Strategic Merge Patch] and [JSON patches]. Now one patch can be
-applied to multiple resources.
-
-This can be done by specifying a patch and a target selector as follows:
-```
-patches:
-- path: <PatchFile>
-  target:
-    group: <Group>
-    version: <Version>
-    kind: <Kind>
-    name: <Name>
-    namespace: <Namespace>
-    labelSelector: <LabelSelector>
-    annotationSelector: <AnnotationSelector>
-```
-Both `labelSelector` and `annotationSelector` should follow the convention in [label selector].
-Kustomize selects the targets which match all the fields in `target` to apply the patch.
-
-The example below shows how to inject a sidecar container for all deployment resources.
-
-Make a `kustomization` containing a Deployment resource.
-
-<!-- @createDeployment @testAgainstLatestRelease -->
+<!-- @demoHome @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
+```
 
-cat <<EOF >$DEMO_HOME/kustomization.yaml
-resources:
-- deployments.yaml
-EOF
+Make a file describing two Deployments:
 
+<!-- @createDeployments @testAgainstLatestRelease -->
+```
 cat <<EOF >$DEMO_HOME/deployments.yaml
 apiVersion: apps/v1
 kind: Deployment
@@ -72,9 +107,10 @@ spec:
 EOF
 ```
 
-Declare a Strategic Merge Patch file to inject a sidecar container:
+Declare a [strategic merge patch] file
+to inject a sidecar container:
 
-<!-- @addPatch @testAgainstLatestRelease -->
+<!-- @definePatch @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/patch.yaml
 apiVersion: apps/v1
@@ -93,11 +129,16 @@ spec:
 EOF
 ```
 
-Apply the patch by adding _patches_ field in kustomization.yaml
+Finally, define a kustomization file
+that specifies both a `patches` and `resources`
+entry:
 
-<!-- @applyPatch @testAgainstLatestRelease -->
+<!-- @createKustomization @testAgainstLatestRelease -->
 ```
-cat <<EOF >>$DEMO_HOME/kustomization.yaml
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- deployments.yaml
+
 patches:
 - path: patch.yaml
   target:
@@ -105,18 +146,11 @@ patches:
 EOF
 ```
 
-Running `kustomize build $DEMO_HOME`, in the output confirm that both Deployment resources are patched correctly.
+The expected result is:
 
-<!-- @confirmPatch @testAgainstLatestRelease -->
+<!-- @definedExpectedOutput @testAgainstLatestRelease -->
 ```
-test 2 == \
-  $(kustomize build $DEMO_HOME | grep "image: docker.io/istio/proxyv2" | wc -l); \
-  echo $?
-```
-
-The output is as follows:
-
-```yaml
+cat <<EOF >$DEMO_HOME/out_expected.yaml
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -157,32 +191,21 @@ spec:
         name: istio-proxy
       - image: busybox
         name: busybox
+EOF
 ```
 
-## Target selector
-- Select resources with name matching `name*`
-  ```yaml
-  target:
-    name: name*
-  ```
-- Select all Deployment resources
-  ```yaml
-  target:
-    kind: Deployment
-  ```
-- Select resources matching label `app=hello`
-  ```yaml
-  target:
-    labelSelector: app=hello
-  ```
-- Select resources matching annotation `app=hello`
-  ```yaml
-  target:
-    annotationSelector: app=hello
-  ```
-- Select all Deployment resources matching label `app=hello`
-  ```yaml
-  target:
-    kind: Deployment
-    labelSelector: app=hello
-  ```
\ No newline at end of file
+Run the build:
+<!-- @runIt @testAgainstLatestRelease -->
+```
+kustomize build $DEMO_HOME >$DEMO_HOME/out_actual.yaml
+```
+
+Confirm expectations:
+
+<!-- @diffShouldExitZero @testAgainstLatestRelease -->
+```
+diff $DEMO_HOME/out_actual.yaml $DEMO_HOME/out_expected.yaml
+```
+
+To see how to do this with JSON patches,
+try the [JSON patch] demo.