Merge pull request #2331 from monopole/moreExamplesInJsonPatch

Improve json6902 patch example.

examples/jsonpatch.md

@@ -2,19 +2,17 @@
 
 A kustomization file supports customizing resources via [JSON patches](https://tools.ietf.org/html/rfc6902).
 
-The example below modifies an `Ingress` object with such a patch.
+Make a place to work:
 
-Make a `kustomization` containing an ingress resource.
+<!-- @placeToWork @testAgainstLatestRelease -->
-
-<!-- @createIngress @testAgainstLatestRelease -->
 ```
 DEMO_HOME=$(mktemp -d)
+```
 
-cat <<EOF >$DEMO_HOME/kustomization.yaml
+We'll be editting an `Ingress` object:
-resources:
-- ingress.yaml
-EOF
 
+<!-- @ingress @testAgainstLatestRelease -->
+```
 cat <<EOF >$DEMO_HOME/ingress.yaml
 apiVersion: networking.k8s.io/v1beta1
 kind: Ingress
@@ -25,94 +23,173 @@ spec:
   - host: foo.bar.com
     http:
       paths:
-      - backend:
+      - path: /
+        backend:
+          serviceName: homepage
+          servicePort: 8888
+      - path: /api
+        backend:
           serviceName: my-api
-          servicePort: 80
+          servicePort: 7701
+      - path: /test
+        backend:
+          serviceName: hello
+          servicePort: 7702
 EOF
 ```
 
-Declare a JSON patch file to update two fields of the Ingress object:
+The edits we want to make are:
 
-- change host from `foo.bar.com` to `foo.bar.io`
+ - change the value of `host` to _foo.bar.io_
-- change servicePort from `80` to `8080`
+ - change the port for `'/'` from _8888_ to _80_
+ - insert an entirely new serving path `/healthz`
+   at a particular point in the `paths` list,
+   rather than at the end or the beginning.
+
+Here's the patch file to do that:
 
 <!-- @addJsonPatch @testAgainstLatestRelease -->
 ```
 cat <<EOF >$DEMO_HOME/ingress_patch.json
 [
-  {"op": "replace", "path": "/spec/rules/0/host", "value": "foo.bar.io"},
+  {"op": "replace",
-  {"op": "replace", "path": "/spec/rules/0/http/paths/0/backend/servicePort", "value": 8080}
+   "path": "/spec/rules/0/host",
+   "value": "foo.bar.io"},
+
+  {"op": "replace",
+   "path": "/spec/rules/0/http/paths/0/backend/servicePort",
+   "value": 80},
+
+  {"op": "add",
+   "path": "/spec/rules/0/http/paths/1",
+   "value": { "path": "/healthz", "backend": {"servicePort":7700} }}
 ]
 EOF
 ```
 
-You can also write the patch in YAML format. This example also shows the "add" operation:
+We'll of course need a `kustomization` file
+referring to the `Ingress`:
 
-<!-- @addYamlPatch @testAgainstLatestRelease -->
+<!-- @kustomization @testAgainstLatestRelease -->
 ```
-cat <<EOF >$DEMO_HOME/ingress_patch.yaml
+cat <<EOF >$DEMO_HOME/kustomization.yaml
-- op: replace
+resources:
-  path: /spec/rules/0/host
+- ingress.yaml
-  value: foo.bar.io
-
-- op: add
-  path: /spec/rules/0/http/paths/-
-  value:
-    path: '/test'
-    backend:
-      serviceName: my-test
-      servicePort: 8081
 EOF
 ```
 
-Apply the patch by adding _patchesJson6902_ field in kustomization.yaml
+To this same `kustomization` file, add a
+`patchesJson6902` field refering to
+the patch file we just made and
+target it to the `Ingress` object:
 
 <!-- @applyJsonPatch @testAgainstLatestRelease -->
 ```
 cat <<EOF >>$DEMO_HOME/kustomization.yaml
 patchesJson6902:
-- target:
+- path: ingress_patch.json
+  target:
     group: networking.k8s.io
     version: v1beta1
     kind: Ingress
     name: my-ingress
-  path: ingress_patch.json
 EOF
 ```
 
-Running `kustomize build $DEMO_HOME`, in the output confirm that host has been updated correctly.
+Define the expected output:
-<!-- @confirmHost @testAgainstLatestRelease -->
+<!-- @expected @testAgainstLatestRelease -->
 ```
-test 1 == \
+cat <<EOF >$DEMO_HOME/out_expected.yaml
-  $(kustomize build $DEMO_HOME | grep "host: foo.bar.io" | wc -l); \
+apiVersion: networking.k8s.io/v1beta1
-  echo $?
+kind: Ingress
-```
+metadata:
-Running `kustomize build $DEMO_HOME`, in the output confirm that the servicePort has been updated correctly.
+  name: my-ingress
-<!-- @confirmServicePort @testAgainstLatestRelease -->
+spec:
-```
+  rules:
-test 1 == \
+  - host: foo.bar.io
-  $(kustomize build $DEMO_HOME | grep "servicePort: 8080" | wc -l); \
+    http:
-  echo $?
+      paths:
+      - backend:
+          serviceName: homepage
+          servicePort: 80
+        path: /
+      - backend:
+          servicePort: 7700
+        path: /healthz
+      - backend:
+          serviceName: my-api
+          servicePort: 7701
+        path: /api
+      - backend:
+          serviceName: hello
+          servicePort: 7702
+        path: /test
+EOF
 ```
 
-If the patch is YAML-formatted, it will be parsed correctly:
+Run the build:
+<!-- @runIt @testAgainstLatestRelease -->
+```
+kustomize build $DEMO_HOME >$DEMO_HOME/out_actual.yaml
+```
 
-<!-- @applyYamlPatch @testAgainstLatestRelease -->
+Confirm they match:
+
+<!-- @diffShouldExitZero @testAgainstLatestRelease -->
+```
+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.
+
+
+<!-- @writeYamlPatch @testAgainstLatestRelease -->
+```
+cat <<EOF >$DEMO_HOME/ingress_patch.yaml
+- op: add
+  path: /spec/rules/0/http/paths/-
+  value:
+    path: '/canada'
+    backend:
+      serviceName: hoser
+      servicePort: 7703
+EOF
+```
+
+Now add this to the list of patches in the `kustomization` file:
+
+<!-- @addYamlPatch @testAgainstLatestRelease -->
 ```
 cat <<EOF >>$DEMO_HOME/kustomization.yaml
-patchesJson6902:
+- path: ingress_patch.yaml
-- target:
+  target:
     group: networking.k8s.io
     version: v1beta1
     kind: Ingress
     name: my-ingress
-  path: ingress_patch.yaml
 EOF
 ```
 
-<!-- @confirmYamlPatch @testAgainstLatestRelease -->
+We expect the following at the end of the output:
+<!-- @expected @testAgainstLatestRelease -->
 ```
-test 1 == \
+cat <<EOF >$DEMO_HOME/out_expected.yaml
-  $(kustomize build $DEMO_HOME | grep "path: /test" | wc -l); \
+      - backend:
-  echo $?
+          serviceName: hello
+          servicePort: 7702
+        path: /test
+      - backend:
+          serviceName: hoser
+          servicePort: 7703
+        path: /canada
+EOF
+```
+
+Try it:
+
+<!-- @runIt @testAgainstLatestRelease -->
+```
+kustomize build $DEMO_HOME | tail -n 8 |\
+    diff  $DEMO_HOME/out_expected.yaml -
 ```