Helm in Practice

The Upgrade Workflow

Helm upgrades occur when you want to apply a new version of a chart or change its values for an existing release. The helm upgrade process is conceptually similar to an install, but with some differences in how existing resources are handled. These are the overall steps Helm takes when you run helm upgrade:

Chart and Config Preparation: Helm loads the specified new chart (or the same chart with new values) and merges in any value overrides, just like an install. It also fetches any updated dependencies if the chart's dependencies have changed (for example, if the new chart version points to a newer subchart version). Essentially, we have a new desired set of manifests.

Template Rendering: Helm renders the templates of the new chart with the new values, producing a full manifest for the "desired state" of the release after the upgrade. At the same time, Helm retrieves the previous release's manifest (from its release record) for comparison.

Pre-Upgrade Hooks: Before applying any changes to the cluster, Helm will run any pre-upgrade hooks in the new chart.

The chart might include jobs to back up data or pause processes. These hooks are executed similarly to pre-install: sorted, created, and waited upon. They run while the old version's resources are still active (since we haven't modified or deleted anything yet). If any pre-upgrade hook fails, the upgrade is aborted (and the release remains at the old version).

Applying Resource Changes: After pre-upgrade hooks succeed, Helm proceeds to apply the new manifests to the cluster. Under the hood, Helm uses a three-way diff/merge strategy to determine what to create, update, or delete. It compares the following to decide on the minimal changes:

1. The old manifest
2. The new manifest
3. The live state

In practice, if a resource is present in the new manifest and was also part of the old release, Helm will update that resource (performing a Kubernetes API update/patch). For example, if the WordPress Deployment image tag changed, Helm updates the Deployment object (which triggers Kubernetes to roll out pods with the new image).

If a new resource is in the new manifest that didn't exist before, Helm will create it. (E.g., a new ConfigMap or an additional component introduced in the new chart version will be created.)

If a resource existed in the old release but is removed in the new manifest, Helm will delete it from the cluster to reconcile the release to the desired state. For instance, if the old chart had a certain Kubernetes object that the new chart no longer includes, Helm will delete that object so it doesn't linger, orphaned.

Helm's way of handling the resource lifecycle is advantageous compared to other tools or manual kubectl apply. Helm tracks and prunes removed resources automatically.

You can use the helm.sh/resource-policy: keep annotation on specific resources to prevent Helm from deleting them during upgrades.

For example, to keep a ConfigMap:

metadata:
  name