From 1c616b196258b4c41abc754b3c69b52abba4d6cd Mon Sep 17 00:00:00 2001
From: Jingfang Liu <jingfangliu@google.com>
Date: Thu, 6 Sep 2018 16:04:12 -0700
Subject: [PATCH] Add examples and docs for patchesJson6902

---
 docs/glossary.md        | 13 +++++++
 docs/kustomization.yaml | 35 +++++++++++++++++++
 examples/README.md      |  2 ++
 examples/jsonpatch.md   | 77 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 127 insertions(+)
 create mode 100644 examples/jsonpatch.md

diff --git a/docs/glossary.md b/docs/glossary.md
index 866efeb66..1a4d07746 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -2,6 +2,7 @@
 
 [DAM]: #declarative-application-management
 [JSON]: https://www.json.org/
+[JSONPatch]: https://tools.ietf.org/html/rfc6902
 [Resource]: #resource
 [YAML]: http://www.yaml.org/start.html
 [application]: #application
@@ -20,11 +21,14 @@
 [overlays]: #overlay
 [patch]: #patch
 [patches]: #patch
+[patchJson6902]: #patchJson6902
+[patchesJson6902]: #patchjson6902
 [proposal]: https://github.com/kubernetes/community/pull/1629
 [rebase]: https://git-scm.com/docs/git-rebase
 [resource]: #resource
 [resources]: #resource
 [rpm]: https://en.wikipedia.org/wiki/Rpm_(software)
+[strategic merge]: https://github.com/kubernetes/community/blob/master/contributors/devel/strategic-merge-patch.md
 [target]: #target
 [variant]: #variant
 [variants]: #variant
@@ -254,6 +258,15 @@ dependencies.  Since any resource file can be used as a
 patch, one cannot reliably distinguish a resource from
 a patch just by looking at the file's [YAML].
 
+## patchJson6902
+A _patchJson6902_ refers to a kubernetes object and a [JSONPatch]
+that can patch the object. A [JSONPatch] contains a list of operations to change the object's field directly. 
+This is different from [patch], which is
+applied to a target kubernetes object by [strategic merge]. 
+
+_patchesJson6902_ is a field in kustomization. It contains a list of
+_patchJson6902_.
+
 ## resource
 
 A _resource_, in the context of kustomize, is a path to
diff --git a/docs/kustomization.yaml b/docs/kustomization.yaml
index 2cfb89a4e..30821c99b 100644
--- a/docs/kustomization.yaml
+++ b/docs/kustomization.yaml
@@ -138,6 +138,41 @@ patches:
 - deployment_increase_replicas.yaml
 - deployment_increase_memory.yaml
 
+# Each entry in this list should resolve to
+# a kubernetes object and a JSON patch that will be applied
+# to the object.
+# The JSON patch is documented at https://tools.ietf.org/html/rfc6902
+#
+# target field points to a kubernetes object within the same kustomization
+# by the object's group, version, kind, name and namespace.
+# path field is a relative file path of a JSON patch file.
+# The content in this patch file can be either in JSON format as
+#
+#  [
+#    {"op": "add", "path": "/some/new/path", "value": "value"},
+#    {"op": "replace", "path": "/some/existing/path", "value": "new value"}
+#  ]
+#
+# or in YAML format as
+#
+# - op: add
+#   path: /some/new/path
+#   value: value
+# - op:replace
+#   path: /some/existing/path
+#   value: new value
+#
+patchesJson6902
+- target:
+    version: v1
+    kind: Deployment
+    name: my-deployment
+  path: add_init_container.yaml
+- target:
+    version: v1
+    kind: Service
+    name: my-service
+  path: add_service_annotation.yaml
 
 # Each entry in this list should be a relative path to
 # a file for custom resource definition(CRD).
diff --git a/examples/README.md b/examples/README.md
index 675811982..0b150ffef 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -40,3 +40,5 @@ go get github.com/kubernetes-sigs/kustomize
  * [multibases](multibases/README.md) - Composing three variants (dev, staging, production) with a common base.
 
  * [remote target](remoteBuild.md) - Building a kustomization from a github URL
+ 
+ * [json patch](jsonpatch.md) - Apply a json patch in a kustomization
diff --git a/examples/jsonpatch.md b/examples/jsonpatch.md
new file mode 100644
index 000000000..99dcb6d3c
--- /dev/null
+++ b/examples/jsonpatch.md
@@ -0,0 +1,77 @@
+# Demo: applying a json patch
+
+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 `kustomization` containing an ingress resource.
+
+<!-- @createIngress @test -->
+```
+DEMO_HOME=$(mktemp -d)
+
+cat <<EOF >$DEMO_HOME/kustomization.yaml
+resources:
+- ingress.yaml
+EOF
+
+cat <<EOF >$DEMO_HOME/ingress.yaml
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: my-ingress
+spec:
+  rules:
+  - host: foo.bar.com
+    http:
+      paths:
+      - backend:
+          serviceName: my-api
+          servicePort: 80
+EOF
+```
+
+Declare a JSON patch file to update two fields of the Ingress object:
+
+- change host from `foo.bar.com` to `foo.bar.io`
+- change servicePort from `80` to `8080`
+
+<!-- @addJsonPatch @test -->
+```
+cat <<EOF >$DEMO_HOME/ingress_patch.json
+[
+  {"op": "replace", "path": "/spec/rules/0/host", "value": "foo.bar.io"},
+  {"op": "replace", "path": "/spec/rules/0/http/paths/0/backend/servicePort", "value": 8080}
+]
+EOF
+```
+
+Apply the patch by adding _patchesJson6902_ field in kustomization.yaml
+
+<!-- @applyJsonPatch @test -->
+```
+cat <<EOF >>$DEMO_HOME/kustomization.yaml
+patchesJson6902:
+- target:
+    group: extensions
+    version: v1beta1
+    kind: Ingress
+    name: my-ingress
+  path: ingress_patch.json
+EOF
+```
+
+Running `kustomize build $DEMO_HOME`, in the ourput confirm that host has been updated correctly.
+<!-- @confirmHost @test -->
+```
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "host: foo.bar.io" | wc -l); \
+  echo $?
+```
+Running `kustomize build $DEMO_HOME`, in the ourput confirm that the servicePort has been updated correctly.
+<!-- @confirmServicePort @test -->
+```
+test 1 == \
+  $(kustomize build $DEMO_HOME | grep "servicePort: 8080" | wc -l); \
+  echo $?
+```