Resource upgrades three way merge

content/en/docs/faq/changes_since_helm2.md

@@ -43,6 +43,8 @@ functionality remains.
 
 ### Improved Upgrade Strategy: 3-way Strategic Merge Patches
 
+_Note: Details on 3-way Strategic Merge Patches is now maintained in [Resource Upgrades](../topics/resource_upgrades.md)_
+
 Helm 2 used a two-way strategic merge patch. During an upgrade, it compared the
 most recent chart's manifest against the proposed chart's manifest (the one
 supplied during `helm upgrade`). It compared the differences between these two
@@ -56,110 +58,6 @@ in the chart's state, the live state was left unchanged.
 In Helm 3, we now use a three-way strategic merge patch. Helm considers the old
 manifest, its live state, and the new manifest when generating a patch.
 
-#### Examples
-
-Let's go through a few common examples what this change impacts.
-
-##### Rolling back where live state has changed
-
-Your team just deployed their application to production on Kubernetes using
-Helm. The chart contains a Deployment object where the number of replicas is set
-to three:
-
-```console
-$ helm install myapp ./myapp
-```
-
-A new developer joins the team. On their first day while observing the
-production cluster, a horrible coffee-spilling-on-the-keyboard accident happens
-and they `kubectl scale` the production deployment from three replicas down to
-zero.
-
-```console
-$ kubectl scale --replicas=0 deployment/myapp
-```
-
-Another developer on your team notices that the production site is down and
-decides to rollback the release to its previous state:
-
-```console
-$ helm rollback myapp
-```
-
-What happens?
-
-In Helm 2, it would generate a patch, comparing the old manifest against the new
-manifest. Because this is a rollback, it's the same manifest. Helm would
-determine that there is nothing to change because there is no difference between
-the old manifest and the new manifest. The replica count continues to stay at
-zero. Panic ensues.
-
-In Helm 3, the patch is generated using the old manifest, the live state, and
-the new manifest. Helm recognizes that the old state was at three, the live
-state is at zero and the new manifest wishes to change it back to three, so it
-generates a patch to change the state back to three.
-
-##### Upgrades where live state has changed
-
-Many service meshes and other controller-based applications inject data into
-Kubernetes objects. This can be something like a sidecar, labels, or other
-information. Previously if you had the given manifest rendered from a Chart:
-
-```yaml
-containers:
-- name: server
-  image: nginx:2.0.0
-```
-
-And the live state was modified by another application to
-
-```yaml
-containers:
-- name: server
-  image: nginx:2.0.0
-- name: my-injected-sidecar
-  image: my-cool-mesh:1.0.0
-```
-
-Now, you want to upgrade the `nginx` image tag to `2.1.0`. So, you upgrade to a
-chart with the given manifest:
-
-```yaml
-containers:
-- name: server
-  image: nginx:2.1.0
-```
-
-What happens?
-
-In Helm 2, Helm generates a patch of the `containers` object between the old
-manifest and the new manifest. The cluster's live state is not considered during
-the patch generation.
-
-The cluster's live state is modified to look like the following:
-
-```yaml
-containers:
-- name: server
-  image: nginx:2.1.0
-```
-
-The sidecar pod is removed from live state. More panic ensues.
-
-In Helm 3, Helm generates a patch of the `containers` object between the old
-manifest, the live state, and the new manifest. It notices that the new manifest
-changes the image tag to `2.1.0`, but live state contains a sidecar container.
-
-The cluster's live state is modified to look like the following:
-
-```yaml
-containers:
-- name: server
-  image: nginx:2.1.0
-- name: my-injected-sidecar
-  image: my-cool-mesh:1.0.0
-```
-
 ### Release Names are now scoped to the Namespace
 
 With the removal of Tiller, the information about each release had to go

content/en/docs/topics/resource_upgrades.md

@@ -0,0 +1,98 @@
+---
+title: "Resource Upgrades"
+description: "Describes Helm's approach to updating resources during upgrades."
+---
+
+Helm uses a three-way strategic merge and patch process to update resources when upgrading a chart.
+
+The three-way strategic merge allows Helm to upgrade resources that get modified out-of-band. Without 'over-writing' those modifications. Also allowing Helm to similarly rollback only Helm managed updates. For example, if a service mesh controller injects a side-car.
+
+During an upgrade, Helm compares a resource's old manifest, its live state, and the new/updated manifest. Then generates a patch to apply.
+
+Properties of a resource which are declared in the chart are always updated/reverted. Even if updated out-of-band. As helm "converges" to the declared state from the chart.
+
+Helm can also replace existing resources on upgrades with the `--force` flag.
+
+## Examples
+
+Let's go through a few common examples for how this change impacts Helm's ability to manage resources
+
+### Rolling back where live state has changed
+
+Your team just deployed their application to production on Kubernetes using
+Helm. The chart contains a Deployment object where the number of replicas is set
+to three:
+
+```console
+$ helm install myapp ./myapp
+```
+
+A new developer joins the team. On their first day while observing the
+production cluster, a horrible coffee-spilling-on-the-keyboard accident happens
+and they `kubectl scale` the production deployment from three replicas down to
+zero.
+
+```console
+$ kubectl scale --replicas=0 deployment/myapp
+```
+
+Another developer on your team notices that the production site is down and
+decides to rollback the release to its previous state:
+
+```console
+$ helm rollback myapp
+```
+
+What happens?
+
+Helm generates a patch using the old manifest, the live state, and
+the new manifest. Helm recognizes that the old state was at three, the live
+state is at zero and the new manifest wishes to change it back to three, so it
+generates a patch to change the state back to three.
+
+### Upgrades where live state has changed
+
+Many service meshes and other controller-based applications inject data into
+Kubernetes objects. This can be something like a sidecar, labels, or other
+information. Previously if you had the given manifest rendered from a Chart:
+
+```yaml
+containers:
+- name: server
+  image: nginx:2.0.0
+```
+
+And the live state was modified by another application to
+
+```yaml
+containers:
+- name: server
+  image: nginx:2.0.0
+- name: my-injected-sidecar
+  image: my-cool-mesh:1.0.0
+```
+
+Now, you want to upgrade the `nginx` image tag to `2.1.0`. So, you upgrade to a
+chart with the given manifest:
+
+```yaml
+containers:
+- name: server
+  image: nginx:2.1.0
+```
+
+What happens?
+
+Helm generates a patch of the `containers` object between the old
+manifest, the live state, and the new manifest. It notices that the new manifest
+changes the image tag to `2.1.0`, but live state contains a sidecar container.
+
+The cluster's live state is modified to look like the following:
+
+```yaml
+containers:
+- name: server
+  image: nginx:2.1.0
+- name: my-injected-sidecar
+  image: my-cool-mesh:1.0.0
+```