Helm Release Upgrades and Rollbacks

1. Introduction

Helm is a versatile package manager for Kubernetes. It provides advanced functions for locating packages and their specific versions, as well as performing complex installations and custom deployments.

In this tutorial, we explore release upgrades and the Helm rollback mechanism. First, we look at releases and upgrade one to see the result. After that, we go through the release change history. Finally, we perform rollbacks to specific states.

We tested the code in this tutorial on Debian 12 (Bookworm) with GNU Bash 5.2.15 and Helm 3.14.2. Unless otherwise specified, it should work in most POSIX-compliant environments.

2. Releases and Upgrades

Helm charts turn into Helm releases upon installation:

$ helm install banzaicloud-stable/satellite --generate-name --version 0.0.3
NAME: satellite-1709766601
LAST DEPLOYED: Sun Mar  3 03:03:24 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

In this case, the banzaicloud-stable/satellite chart is installed as the satellite-1709766601 release:

$ helm list
NAME                    NAMESPACE       REVISION        UPDATED                                 STATUS        CHART          
satellite-1709766601    default         1               2024-03-03 03:03:24.286660388 -0500 EST deployed      satellite-0.0.3

As expected, we see satellite-0.0.3 is the chart of the new release. Further, the current REVISION is 1.

If we keep a release long enough, an updated chart can be published for it. Then, we can upgrade to the newer version via the upgrade subcommand:

$ helm upgrade satellite-1709766601 banzaicloud-stable/satellite --version 0.0.4
Release "satellite-1709766601" has been upgraded. Happy Helming!
NAME: satellite-1709766601
LAST DEPLOYED: Wed Mar  3 10:00:00 2024
NAMESPACE: default
STATUS: deployed
REVISION: 2
TEST SUITE: None

At this point, we can see that the REVISION number changed to 2.

Let’s verify the version as well:

$ helm list
NAME                    NAMESPACE       REVISION        UPDATED                                 STATUS        CHART          
satellite-1709766601    default         2               2024-03-03 10:00:00.881000667 -0500 EST deployed      satellite-0.0.4

So, we have the satellite-1709766601 release with two revisions.

3. History and Rollbacks

As we already saw, if a release has gone through at least one upgrade, it has a trail of revisions.

These revisions comprise a history of chart deployment states, mainly differing by version. This log can be helpful in different situations:

• restore release to the last working condition
• test older release versions
• integration testing

In any case, to bring a release to an older revision, we use the rollback subcommand.

3.1. Revision History

Before rolling back, we usually employ the history subcommand to get the current revision list for a given release:

$ helm history satellite-1709766601
REVISION        UPDATED                         STATUS          CHART            DESCRIPTION
1               Sun Mar  3 03:03:24 2024        superseded      satellite-0.0.3  Install complete
2               Sun Mar  3 10:00:00 2024        deployed        satellite-0.0.4  Upgrade complete

Here, we supply the satellite-1709766601 release name. As a result, we see its revisions in order. Each revision has a number identifier, date, current STATUS, CHART name, and activity DESCRIPTION.

This way, we know which revisions are deployed, which are available, and how to identify each.

3.2. Rollback

At this point, we should be ready to perform a rollback:

$ helm rollback satellite-1709766601 1
Rollback was a success! Happy Helming!

Specifically, we request a rollback of release satellite-1709766601 to revision 1.

In this case, we can also do the same but with no specific revision :

$ helm rollback satellite-1709766601

Without indicating a revision number, rollback assumes we want to restore the release to its previous revision. Notably, we might have to specify the –namespace if the release is outside the default namespace.

Either way, the operation is complete. Due to the ephemeral nature of this deployment, we don’t see any complications. Still, persistent volumes and persistent volume claims can make this action more prone to issues.

3.3. Rollback Revisions

Conveniently, if we turn on Helm autocompletion, we can also press Tab after the helm rollback command to get a list of releases and after adding a release name to get an overview of its revisions:

$ helm rollback satellite-1709766601 [Tab]
1  (App: , Chart: satellite-0.0.3)  3  (App: , Chart: satellite-0.0.3)
2  (App: , Chart: satellite-0.0.4)

This way, we don’t need to always run a history check unless more details are necessary.

Notably, we see that there are now three revisions, as also confirmed by history:

$ helm history satellite-1709766601
REVISION        UPDATED                         STATUS          CHART            DESCRIPTION
1               Sun Mar  3 03:03:24 2024        superseded      satellite-0.0.3  Install complete
2               Sun Mar  3 10:00:00 2024        superseded      satellite-0.0.4  Upgrade complete
3               Sun Mar  3 13:00:00 2024        deployed        satellite-0.0.3  Rollback to 1

As the DESCRIPTION of revision 3 shows, this is because rollbacks produce revisions as well.

3.4. Maximum Revision History

By default, the revision count limit is 10. However, both the upgrade and rollback subcommands support the –history-max option to modify that.

If specified, the argument to –history-max can set the revision count limit to a positive integer with 0, indicating we allow unlimited revisions.

3.5. Advanced Options

Similar to the install subcommand, rollback offers several advanced features:

• –cleanup-on-fail: similar to install –atomic, wipes traces of a failed rollback
• –dry-run: perform a simulated rollback
• –no-hooks: don’t run hooks during rollback
• –wait: ensure rollback completes successfully by waiting for all related objects

By leveraging the above, we can augment the rollback just like a new installation.

4. Summary

In this article, we talked about Helm release upgrades and rollbacks.

In conclusion, since Kubernetes deployments are often complex, failing upgrades may cause a lot of problems while rolling back to a revision with a single command can restore functionality.