Migrating to SUSE Storage

It is recommended to create a Longhorn system backup before performing the upgrade. This ensures that all critical resources, such as volumes and backing images, are backed up and can be restored in case any issues arise.

Prerequisites

Tools

Helm v3.0 or later is required.
The Longhorn Command Line Tool can be used to check the SUSE Storage environment for potential issues.

Authentication

To authenticate Helm with SUSE Application Collection OCI chart repository, refer to the Helm authentication documentation.
To allow Kubernetes to pull images from the registry, follow the Kubernetes authentication documentation to create a secret and set the global.imagePullSecrets chart value.

Migrating Longhorn Deployed via Helm To SUSE Storage

If your existing Longhorn installation was deployed via Helm, you can verify it by running helm list --all-namespaces. By default, the Helm release used to install Longhorn is named longhorn, but it may also be a custom name defined by the user.

Next, optionally create a values.yaml file with any customized settings you want to apply during the upgrade.

Proceed with the upgrade to SUSE Storage using the SUSE Storage chart:

helm upgrade longhorn oci://dp.apps.rancher.io/charts/suse-storage \
	--namespace longhorn-system \
	--version <version> \ # Replace with the version you would like to upgrade to
	--set global.imagePullSecrets=<PULL_IMAGE_SECRET>

Optionally, if you have a values.yaml file with customized settings, include it with the -f flag:

helm upgrade longhorn oci://dp.apps.rancher.io/charts/suse-storage \
	--namespace longhorn-system \
	--version <version> \ # Replace with the version you would like to upgrade to
	--set global.imagePullSecrets=<PULL_IMAGE_SECRET> \
	-f values.yaml

Migrating Longhorn deployed via Rancher Apps Marketplace to SUSE Storage

If your existing Longhorn installation was deployed via Rancher Apps Marketplace, you will see two Helm releases associated with Longhorn when running helm list --all-namespaces | grep longhorn.

$ helm list --all-namespaces | grep longhorn
longhorn                                         	longhorn-system    	1       	2025-07-21 02:58:40.877484249 +0000 UTC	deployed	longhorn-106.2.1+up1.8.2                                                                               	v1.8.2
longhorn-crd                                     	longhorn-system    	1       	2025-07-21 02:58:38.192579711 +0000 UTC	deployed	longhorn-crd-106.2.1+up1.8.2                                                                           	v1.8.2

To migrate the existing Rancher Longhorn installation to SUSE Storage, you need to delete the longhorn-crd Helm release without removing the CRDs, and then upgrade the longhorn Helm release by following the steps below.

Remove `longhorn-crd` Helm Release while Keeping CRDs

To remove the longhorn-crd Helm release from your system while ensuring the Longhorn CRDs themselves are preserved, follow these steps:

Check the current version of your longhorn-crd Helm release:

helm list --all-namespaces | grep longhorn-crd

The output will show your longhorn-crd release details, for example:

longhorn-crd                                     	longhorn-system    	1       	2025-07-21 02:58:38.192579711 +0000 UTC	deployed	longhorn-crd-106.2.1+up1.8.2                                                                           	v1.8.2

In this example, the release version is 106.2.1+up1.8.2.

Clone the rancher/charts repository containing the specific version of the longhorn-crd chart that matches your current release (for example, 106.2.1+up1.8.2 for Longhorn v1.8.2):
```
git clone https://github.com/rancher/charts.git
```
Navigate into the directory corresponding to your longhorn-crd chart version within the cloned repository.

Or, you can execute this script to longhorn-crd chart.

After running the command bash ./download-longhorn-crd-chart.sh 106.2.1+up1.8.2, the longhorn-crd chart will be downloaded to the local directory 106.2.1+up1.8.2. Then, open 106.2.1+up1.8.2/Chart.yaml to verify that the chart version matches 106.2.1+up1.8.2.
Manually patch the helm.sh/resource-policy: keep annotation to each Custom Resource Definitions (CRDs) in templates/crds.yaml within the longhorn-crd chart that you cloned. This ensures that Helm does not delete the CRDs when the release is uninstalled. Alternatively, you can use the script to automatically patch the annotation:
```
bash ./patch-resource-policy-annotation.sh 106.2.1+up1.8.2/templates/crds.yaml
```
To verify that the CRDs have been correctly patched, run:
```
vimdiff /tmp/crds.yaml.original 106.2.1+up1.8.2/templates/crds.yaml
```
Upgrade the longhorn-crd Helm release using the locally patched chart:
```
helm upgrade longhorn-crd -n longhorn-system ./106.2.1+up1.8.2
```

Uninstall the longhorn-crd Helm release from your system. Due to the applied patch, the CRDs will remain.

helm uninstall longhorn-crd --namespace longhorn-system

You will see the CRDs are kept while uninstalling longhorn-crd Helm release.

$ helm uninstall longhorn-crd --namespace longhorn-system
These resources were kept due to the resource policy:
[CustomResourceDefinition] backingimagedatasources.longhorn.io
[CustomResourceDefinition] backingimagemanagers.longhorn.io
[CustomResourceDefinition] nodes.longhorn.io
[CustomResourceDefinition] orphans.longhorn.io
[CustomResourceDefinition] recurringjobs.longhorn.io
[CustomResourceDefinition] replicas.longhorn.io
[CustomResourceDefinition] settings.longhorn.io
[CustomResourceDefinition] sharemanagers.longhorn.io
[CustomResourceDefinition] snapshots.longhorn.io
[CustomResourceDefinition] supportbundles.longhorn.io
[CustomResourceDefinition] systembackups.longhorn.io
[CustomResourceDefinition] systemrestores.longhorn.io
[CustomResourceDefinition] backingimages.longhorn.io
[CustomResourceDefinition] volumeattachments.longhorn.io
[CustomResourceDefinition] volumes.longhorn.io
[CustomResourceDefinition] backupbackingimages.longhorn.io
[CustomResourceDefinition] backups.longhorn.io
[CustomResourceDefinition] backuptargets.longhorn.io
[CustomResourceDefinition] backupvolumes.longhorn.io
[CustomResourceDefinition] engineimages.longhorn.io
[CustomResourceDefinition] engines.longhorn.io
[CustomResourceDefinition] instancemanagers.longhorn.io

Replace `longhorn-crd` with `longhorn` in Longhorn CRDs

After ensuring the longhorn-crd Helm release is uninstalled but the CRDs are kept, you need to update the ownership labels on the existing Longhorn CRDs to prepare for the main longhorn Helm chart. Apply the shell script to perform the replacement.

Upgrade to SUSE Storage

After the CRDs have been prepared, you can proceed with upgrading your Longhorn installation to SUSE Storage:

helm upgrade longhorn oci://dp.apps.rancher.io/charts/suse-storage \
	--namespace longhorn-system \
	--version <version> \ # Replace with the version you would like to upgrade to
	--set global.imagePullSecrets=<PULL_IMAGE_SECRET>