diff --git a/content/en/docs/faq/changes_since_helm2.md b/content/en/docs/faq/changes_since_helm2.md index 53cd7e2c2..041bd4892 100644 --- a/content/en/docs/faq/changes_since_helm2.md +++ b/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 diff --git a/content/en/docs/topics/resource_upgrades.md b/content/en/docs/topics/resource_upgrades.md new file mode 100644 index 000000000..aeef7e4d5 --- /dev/null +++ b/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 +```