# 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.

## Reviewing the changelog and breaking changes

Review the [changelog](/self-hosted-toucan/changelog.md) before deploying a new release. It is accessible at this page: [Self-Hosted Toucan - Changelog](/self-hosted-toucan/changelog.md).

If you notice any breaking changes, read this document: [Self-Hosted Toucan - Upgrading](/self-hosted-toucan/upgrading.md).

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.

Our release process dictates these rules:

* A major version is released when the configuration is breaking upon upgrade.
* A minor version is released when a new feature is added, or a dependency is updated by major or minor.
* A patch version is released when a fix is developped, or a dependency is updated by patch.

**We will always assure that these rules are followed.**

## Procedure

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

   <pre class="language-shell" data-title="shell" data-overflow="wrap"><code class="lang-shell">helm diff upgrade toucan-stack --version &#x3C;version> oci://quay.io/toucantoco/charts/toucan-stack -f ./values.override.yaml
   </code></pre>
2. Upgrade the release.

{% code title="shell" overflow="wrap" %}

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

{% endcode %}

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

{% hint style="warning" %}
**Failed to upgrade the release?**

Run:

{% code title="shell" overflow="wrap" %}

```shell
helm rollback toucan-stack
```

{% endcode %}
{% endhint %}

## Getting notified

It's up to you to use you own solution to get notified for updates. However, if you're getting started, we can recommend you into using [Renovate](https://www.mend.io/renovate/) to track updates.

It is self-hostable, or can run as Github App, and will notify about any updates to the chart by creating a PR in your repository.

You can configure Renovate using a configuration file at the root of your repository, but, normally, Renovate will create a PR to also create a configuration for you.

Usually, Renovate automatically detects the Helm charts.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-v3.toucantoco.com/self-hosted-toucan/maintenance/updates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.