merge master to 1.10, with fixes (#7682)

docs/tasks/run-application/update-api-object-kubectl-patch.md

@@ -127,6 +127,7 @@ containers:
 ### Notes on the strategic merge patch
 
 The patch you did in the preceding exercise is called a *strategic merge patch*.
+<<<<<<< HEAD
 Notice that the patch did not replace the `containers` list. Instead it added a new
 Container to the list. In other words, the list in the patch was merged with the
 existing list. This is not always what happens when you use a strategic merge patch on a list.
@@ -202,6 +203,88 @@ type PodSpec struct {
   ...
   Tolerations []Toleration `json:"tolerations,omitempty" protobuf:"bytes,22,opt,name=tolerations"`
 ```
+||||||| merged common ancestors
+With a strategic merge patch, you can update a list by specifying only the elements
+that you want to add to the list. The existing list elements remain, and the new elements
+are merged with the existing elements. In the preceding exercise, the resulting `containers`
+list has both the original nginx Container and the new redis Container.
+=======
+Notice that the patch did not replace the `containers` list. Instead it added a new
+Container to the list. In other words, the list in the patch was merged with the
+existing list. This is not always what happens when you use a strategic merge patch on a list.
+In some cases, the list is replaced, not merged.
+
+With a strategic merge patch, a list is either replaced or merged depending on its
+patch strategy. The patch strategy is specified by the value of the `patchStrategy` key
+in a field tag in the Kubernetes source code. For example, the `Containers` field of `PodSpec`
+struct has a `patchStrategy` of `merge`:
+
+```go
+type PodSpec struct {
+  ...
+  Containers []Container `json:"containers" patchStrategy:"merge" patchMergeKey:"name" ...`
+```
+
+You can also see the patch strategy in the
+[OpenApi spec](https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json):
+
+```json
+"io.k8s.api.core.v1.PodSpec": {
+    ...
+     "containers": {
+      "description": "List of containers belonging to the pod. ...
+      },
+      "x-kubernetes-patch-merge-key": "name",
+      "x-kubernetes-patch-strategy": "merge"
+     },
+```
+
+And you can see the patch strategy in the
+[Kubernetes API documentation](/docs/reference/generated/kubernetes-api/v1.9/#podspec-v1-core).
+
+Create a file named `patch-file-tolerations.yaml` that has this content:
+
+```yaml
+spec:
+  template:
+    spec:
+      tolerations:
+      - effect: NoSchedule
+        key: disktype
+        value: ssd
+```
+
+Patch your Deployment:
+
+```shell
+kubectl patch deployment patch-demo --patch "$(cat patch-file-tolerations.yaml)"
+```
+
+View the patched Deployment:
+
+```shell
+kubectl get deployment patch-demo --output yaml
+```
+
+The output shows that the PodSpec in the Deployment has only one Toleration:
+
+```shell
+tolerations:
+      - effect: NoSchedule
+        key: disktype
+        value: ssd
+```
+
+Notice that the `tolerations` list in the PodSpec was replaced, not merged. This is because
+the Tolerations field of PodSpec does not have a `patchStrategy` key in its field tag. So the
+strategic merge patch uses the default patch strategy, which is `replace`.
+
+```go
+type PodSpec struct {
+  ...
+  Tolerations []Toleration `json:"tolerations,omitempty" protobuf:"bytes,22,opt,name=tolerations"`
+```
+>>>>>>> merge master to 1.10, with fixes (#7682)
 
 ## Use a JSON merge patch to update a Deployment