Add examples and docs for patchesJson6902

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

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).