---
id: upgrade
title: Upgrade Support for OpenEBS
keywords:
- Upgrading OpenEBS
- OpenEBS upgrade
- Supported upgrade paths
description: Upgrade to the latest OpenEBS 2.11.0 version is supported only from v1.0.0 and later.
---

To upgrade to the latest version of **OpenEBS** (2.11.0), you must have version 1.0.0 or later. The latest stable version of OpenEBS is **3.6.0**. You can find the release notes [here](https://github.com/openebs/openebs/releases/tag/v3.6.0).

Upgrading to the latest version of **cStor** or **Jiva** is only supported from version 1.12.0 or later. Detailed steps for upgrading can be found [here](https://github.com/openebs/upgrade/blob/develop/docs/upgrade.md).

For further queries or support, reach out to the [OpenEBS Community](https://kubernetes.slack.com/archives/CUAKPFU78) for assistance with the upgrade.

| Important pointers |
| -------- |
| The community e2e pipelines only verify upgrade testing from non-deprecated releases (1.12 and higher) to version 3.4.0. If you are running on a release older than 1.12, it is recommended to upgrade to the latest version as soon as possible. |
| OpenEBS has deprecated arch-specific container images in favor of multi-arch container images. Starting from version 2.6, the arch-specific images are no longer pushed to Docker or Quay repositories. For example, images like `cstor-pool-arm64:2.8.0` should be replaced with the corresponding multi-arch image `cstor-pool:2.8.0`. |
| If you are upgrading Jiva volumes running in version 1.6 and 1.7, you must follow these [pre-upgrade steps](https://github.com/openebs/charts/tree/gh-pages/scripts/jiva-tools) to check if your Jiva volumes are impacted by [#2956](https://github.com/openebs/openebs/issues/2956). If they are, please reach out to the OpenEBS Community for assistance with the upgrade. |

-----------

## Mayastor upgrade

The upgrade for Mayastor is supported from **version 2.0.x to version 2.1.0 and above**. Before uprading Mayastor, determine the deployment method used for Mayastor in your Kubernetes cluster. The upgrade instructions differ based on the deployment strategy used. Two deployment methods are:
- [Mayastor helm chart](https://github.com/openebs/mayastor-extensions/tree/develop/chart)
- [Openebs helm chart](https://github.com/openebs/charts/tree/main/charts/openebs)

-----

## Step 1: Identify the helm chart used to deploy Mayastor

To determine whether your Mayastor deployment uses the **openebs helm chart**, follow the steps below to identify the helm chart:

1. Ensure that you have the helm v3 binary available on your $PATH. You can verify this by running the following command:

{% tabs %}
{% tab title="Command" %}

helm version --short

{% endtab %}

{% tab title="Output" %}

v3.9.4+gdbc6d8e

{% endtab %}
{% endtabs %}

2. Run the following command to list the helm releases in the namespace where Mayastor is installed:
{% tabs %}
{% tab title="Command" %}

helm list -n openebs

{% endtab %}

{% tab title="Output" %}

NAME            	NAMESPACE	REVISION	UPDATED                             	STATUS  	CHART        	APP VERSION
openebs-mayastor	openebs  	1       	2023-05-26 22:03:15.473035 +0530 IST	deployed	openebs-3.6.0	3.6.0 

{% endtab %}
{% endtabs %}

Analyze the output of the above command and locate the row that corresponds to the helm chart for Mayastor.
- If the CHART column reads **openebs-...**, then your Mayastor deployment uses the openebs helm chart.
- If the CHART column reads **mayastor-...**, then your Mayastor deployment uses the mayastor helm chart.

:::info
If your Mayastor deployment uses the **mayastor helm chart**, refer to the [Mayastor documentation](https://mayastor.gitbook.io/introduction/additional-information/upgrade) for the upgrade steps.
:::

If your Mayastor deployment uses the **openebs helm chart**, follow step #2.

-----

## Step 2: Upgrade Mayastor installed from the openebs helm chart

### 1. Plan the upgrade

If you have Mayastor installed with the openebs helm chart, you can follow the supported upgrade paths outlined below:
- Source versions: 3.4.x or above
- Target versions: 3.7.y or above

You can upgrade from any source version to any target version as long as the release semVer of the target version is greater than that of the source version.

#### Determine the latest released version of Mayastor available

1. Execute the following command to update the helm repository for openebs:

{% tabs %}
{% tab title="Command" %}

helm repo update openebs  

{% endtab %}
{% tab title="Output" %}

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "openebs" chart repository
Update Complete. ⎈Happy Helming!⎈

{% endtab %}
{% endtabs %}

2. After the repository update, run the following command to search for the available versions of the openebs helm chart:
> Replace `a.b.c` with your source version, which is the version currently installed on your cluster.

{% tabs %}
{% tab title="Command" %}

helm search repo openebs --version ">a.b.c"

{% endtab %}
{% tab title="Output" %}

NAME           	CHART VERSION	APP VERSION	DESCRIPTION                                  
openebs/openebs	3.7.0        	3.7.0      	Containerized Attached Storage for Kubernetes

{% endtab %}
{% endtabs %}

#### List all the versions available for upgrade

1. Update the helm repository for openebs:

{% tabs %}
{% tab title="Command" %}

helm repo update openebs 

{% endtab %}
{% tab title="Output" %}

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "openebs" chart repository
Update Complete. ⎈Happy Helming!⎈

{% endtab %}
{% endtabs %}

2. Assuming your source version is 3.5.0, run the following command to list all the available versions for upgrade:

{% tabs %}
{% tab title="Command" %}

helm search repo openebs --version ">3.5.0,>=3.7.0" -l

{% endtab %}
{% tab title="Output" %}

NAME           	CHART VERSION	APP VERSION	DESCRIPTION                                  
openebs/openebs	3.7.0        	3.7.0      	Containerized Attached Storage for Kubernetes

{% endtab %}
{% endtabs %}

This will provide a list of versions that you can choose from for the upgrade. Select the desired version from the listed version(s) based on your requirements and proceed to the next step for the upgrade process.

------------

### 2. Build the `helm upgrade` command

If you have multiple storage engines from the openebs helm chart (e.g., localpv-provisioner and mayastor) installed, you need to include the upgrade options for those storage engines in the helm upgrade command.

:::note

For the purpose of this guide, following details are assumed:
- **Helm chart release name**: openebs-mayastor
- **Namespace**: openebs
- **Source version**: 3.6.0
- **Target version**: 3.7.0
:::

To determine the version of the mayastor helm subchart used by the openebs chart, run the following shell script/command:

$ # Using 3.7.0 for the input version of the
$ IMG_TAG=$(helm show chart openebs/openebs --version 3.5.0 | grep "name: mayastor" -A 2 | tail -n 1 | tr -d " " | sed -e s/version:/v/)
$ echo $IMG_TAG
v2.2.0

The output will display the image tag for the mayastor chart, which is the value of the chart version with a 'v' prefix.

The helm upgrade command with the default options (using the variable from above) would be:

helm upgrade openebs openebs/openebs -n openebs --version 3.7.0 --set mayastor.image.tag=$IMG_TAG --set release.version=3.7.0 --reuse-value

To explore all available configuration options, refer to the below documentation:
- **Chart README**: `https://github.com/openebs/mayastor-extensions/blob/<Add_the_required_release-tag>/chart/README.md`
- **Chart values.yaml**:`https://github.com/openebs/mayastor-extensions/blob/<Add_the_required_release-tag>/chart/values.yaml`

:::note
For example, you can visit the following links to access the documentation for release version 2.2.0:
- **Chart README**: https://github.com/openebs/mayastor-extensions/blob/v2.2.0/chart/README.md
- **Chart values.yaml**: https://github.com/openebs/mayastor-extensions/blob/v2.2.0/chart/values.yaml
:::

When setting options using the `--set` flag, make sure to prefix the option with **mayastor** as shown in the default command for the **image.tag** option. This prefixing is necessary because the mayastor chart is a [subchart of the openebs chart](https://github.com/openebs/charts/blob/openebs-3.7.0/charts/openebs/values.yaml#L400).

Since the mayastor chart is actively being developed, the available helm chart values options may change over time. Also, the use of the `--reuse-value` flag can introduce nil YAML values for certain values required by helm's template engine.
This issue is faced by releases 3.4.0, 3.4.1, and 3.5.0. For these releases, additional options are required to perform the default upgrade to version 3.7.0 or above.

Because the mayastor chart is in active development, its helm chart values options may change over time and the convenience of the `--reuse-value` flags may also introduce nil yaml values for values which are required by helm's template engine. The 3.4.0, 3.4.1 and 3.5.0 releases face this issue. These releases require additional options to perform the default upgrade to 3.7.0 or above versions.

Sample helm upgrade command from 3.4.0 to 3.7.0:

helm upgrade openebs openebs/openebs -n openebs --version 3.7.0 --set mayastor.image.tag=$IMG_TAG --set release.version=3.7.0 --reuse-value \
        --set mayastor.image.pullPolicy="IfNotPresent" \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.agents.core.capacity.thin.poolCommitment="250%" \
        --set mayastor.agents.core.capacity.thin.volumeCommitment="40%" \
        --set mayastor.agents.core.capacity.thin.volumeCommitmentInitial="40%" \
        --set mayastor.io_engine.logLevel="info"

Sample helm upgrade command from 3.4.1 to 3.7.0:

helm upgrade openebs openebs/openebs -n openebs --version 3.7.0 --set mayastor.image.tag=$IMG_TAG --set release.version=3.7.0 --reuse-value \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.agents.core.capacity.thin.poolCommitment="250%" \
        --set mayastor.agents.core.capacity.thin.volumeCommitment="40%" \
        --set mayastor.agents.core.capacity.thin.volumeCommitmentInitial="40%" \
        --set mayastor.io_engine.logLevel="info"

Sample helm upgrade command from 3.5.0 to 3.7.0:

helm upgrade openebs openebs/openebs -n openebs --version 3.7.0 --set mayastor.image.tag=$IMG_TAG --set release.version=3.7.0 --reuse-value \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.image.repoTags.controlPlane="" \
        --set mayastor.agents.core.capacity.thin.poolCommitment="250%" \
        --set mayastor.agents.core.capacity.thin.volumeCommitment="40%" \
        --set mayastor.agents.core.capacity.thin.volumeCommitmentInitial="40%"

For the 3.6.0 release, you can use the default upgrade command to upgrade to 3.7.0:

helm upgrade openebs openebs/openebs -n openebs --version 3.7.0 --set mayastor.image.tag=$IMG_TAG --set release.version=3.7.0 --reuse-value

To update to version 3.8.0 or above, you need to add additional options along with the ones required for version 3.7.0. For example:

--set csi.image.snapshotterTag="v6.2.1" \
--set csi.image.snapshotControllerTag="v6.2.1"

> Ensure to include options for other storage engines (if any) in the command. You can refer to the mayastor chart configuration for more available configuration options.

Sample helm upgrade command from v3.4.0 to v3.7.0:

helm upgrade openebs openebs/openebs -n openebs --version 3.8.0 --set mayastor.image.tag=$IMG_TAG --set release.version=3.8.0 --reuse-value \

        --set mayastor.image.pullPolicy="IfNotPresent" \

        --set mayastor.image.repoTags.controlPlane="" \

        --set mayastor.image.repoTags.controlPlane="" \

        --set mayastor.image.repoTags.controlPlane="" \

        --set mayastor.agents.core.capacity.thin.poolCommitment="250%" \

        --set mayastor.agents.core.capacity.thin.volumeCommitment="40%" \

        --set mayastor.agents.core.capacity.thin.volumeCommitmentInitial="40%" \

        --set mayastor.io_engine.logLevel="info" \

        --set csi.image.snapshotterTag="v6.2.1" \

        --set csi.image.snapshotControllerTag="v6.2.1"

It is recommended to use the `--atomic` helm upgrade flag to ensure that the cluster can be rolled back to the source version if the upgrade to the target version fails. For example:

helm upgrade openebs openebs/openebs -n openebs --version 3.7.0 --set mayastor.image.tag=$IMG_TAG --set release.version=3.7.0 --reuse-value --atomic

### 3. Execute the helm upgrade command

To proceed with the upgrade, execute the helm upgrade command. Only continue if the command succeeds and all Mayastor Pods are in a ready state. You can check the Pod status by running the following command:

kubectl get pods -n openebs

### 4. Follow the Mayastor Helm Chart upgrade instructions

Follow the upgrade instructions for the Mayastor Helm Chart found [here](https://mayastor.gitbook.io/introduction/additional-information/upgrade). These instructions provide detailed guidance on how to perform the upgrade process.

----------

## Supported upgrade paths

To upgrade to the latest version of OpenEBS from your current version, you need to follow the appropriate upgrade path based on your current version. Select the appropriate link based on your current version to access the detailed upgrade instructions for OpenEBS. Here are the supported upgrade paths for the respective versions:

- [From 1.12.0 and higher to 3.6.0](https://github.com/openebs/upgrade/blob/develop/docs/upgrade.md)
- [From 1.0.0 and higher to 1.12.0](https://github.com/openebs/openebs/blob/master/k8s/upgrades/README.md)
- [From 0.9.0 to 1.0.0](https://github.com/openebs/openebs/tree/master/k8s/upgrades/0.9.0-1.0.0)
- [From 0.8.2 to 0.9.0](https://github.com/openebs/openebs/tree/master/k8s/upgrades/0.8.2-0.9.0)
- [From 0.8.1 to 0.8.2](https://github.com/openebs/openebs/tree/master/k8s/upgrades/0.8.1-0.8.2)
- [From 0.8.0 to 0.8.1](https://github.com/openebs/openebs/tree/master/k8s/upgrades/0.8.0-0.8.1)
- [From versions prior to 0.8.0](https://github.com/openebs/openebs/tree/master/k8s/upgrades)

-----------
:::info

For more details:
- [See release notes](/introduction/releases)
- [Join our community](/introduction/community)
- [Checkout troubleshooting guides](/troubleshooting)

:::