🔁Upgrades and rollbacks

This document will guide you through the recommended process and best practices for upgrading a Helm release in a Kubernetes cluster to minimize the risk of service disruption or deployment failure.

Procedure

1. Review the changelog for the new version.

   shell

   helm pull --version <version> oci://quay.io/toucantoco/charts/toucan-stack
   tar -xzf toucan-stack-*.tgz --strip-components=1 toucan-stack/CHANGELOG.md toucan-stack/README.md

The README.md contains instructions on how to upgrade the release and handle breaking changes. The CHANGELOG.md contains a summary of the changes made in the release.

In Helm, there is two types of versions: the chart version and the app version. The chart version is the version of the chart itself, while the app version is the version of the application deployed by the chart.

When the major version of the chart is incremented, the changes of the Helm Chart are considered breaking changes, meaning you will need to update the values.override.yaml file. Minor changes are considered non-breaking changes and will add new flags to the chart, meaning you will not need to update the values.override.yaml file. Patch releases contain fixes and appVersion updates.

1. (optional) For safety, you can check the difference in Kubernetes resources before upgrading the release.

shell

helm diff upgrade toucan-stack --version <version> oci://quay.io/toucantoco/charts/toucan-stack -f ./values.override.yaml

1. Upgrade the release.

shell

helm upgrade --install toucan-stack oci://quay.io/toucantoco/charts/toucan-stack \
  --namespace toucan \
  --values ./values.override.yaml

1. (optional) Check the logs of the deployment to ensure the upgrade was successful.

Failed to upgrade the release?

Run:

shell

helm rollback toucan-stack