From v0.2 and older

The upgrade procedure for Longhorn v0.2 and v0.1 deployments is more involved.

Backup Existing Volumes

It’s recommended to create a recent backup of every volume to the backupstore before upgrade. If you don’t have a on-cluster backupstore already, create one.

We’ll use NFS backupstore for this example.

  1. Execute following command to create the backupstore
  1. kubectl --kubeconfig=kube_configxxx.yml  apply  -f https://raw.githubusercontent.com/rancher/longhorn/master/deploy/backupstores/nfs-backupstore.yml
  1. On Longhorn UI Settings page, set Backup Target to nfs://longhorn-test-nfs-svc.default:/opt/backupstore and click Save.

Navigate to each volume detail page and click Take Snapshot (it’s recommended to run sync in the host command line before Take Snapshot). Click the new snapshot and click Backup. Wait for the new backup to show up in the volume’s backup list before continuing.

Check For Issues

Make sure no volume is in degraded or faulted state. Wait for degraded volumes to heal and delete/salvage faulted volumes before proceeding.

Detach Volumes

Shutdown all Kubernetes Pods using Longhorn volumes in order to detach the volumes. The easiest way to achieve this is by deleting all workloads and recreate them later after upgrade. If this is not desirable, some workloads may be suspended. We will cover how each workload can be modified to shut down its pods.

Deployment

Edit the deployment with kubectl --kubeconfig=kube_configxxx.yml edit deploy/<name>. Set .spec.replicas to 0.

StatefulSet

Edit the statefulset with kubectl --kubeconfig=kube_configxxx.yml edit statefulset/<name>. Set .spec.replicas to 0.

DaemonSet

There is no way to suspend this workload. Delete the daemonset with kubectl --kubeconfig=kube_configxxx.yml delete ds/<name>.

Pod

Delete the pod with kubectl --kubeconfig=kube_configxxx.yml delete pod/<name>. There is no way to suspend a pod not managed by a workload controller.

CronJob

Edit the cronjob with kubectl --kubeconfig=kube_configxxx.yml edit cronjob/<name>. Set .spec.suspend to true. Wait for any currently executing jobs to complete, or terminate them by deleting relevant pods.

Job

Consider allowing the single-run job to complete. Otherwise, delete the job with kubectl --kubeconfig=kube_configxxx.yml delete job/<name>.

ReplicaSet

Edit the replicaset with kubectl --kubeconfig=kube_configxxx.yml edit replicaset/<name>. Set .spec.replicas to 0.

ReplicationController

Edit the replicationcontroller with kubectl --kubeconfig=kube_configxxx.yml edit rc/<name>. Set .spec.replicas to 0.

Wait for the volumes using by the Kubernetes to complete detaching.

Then detach all remaining volumes from Longhorn UI. These volumes were most likely created and attached outside of Kubernetes via Longhorn UI or REST API.

Uninstall the Old Version of Longhorn

Make note of BackupTarget on the Setting page. You will need to manually set BackupTarget after upgrading from either v0.1 or v0.2.

Delete Longhorn components.

For Longhorn v0.1 (most likely installed using Longhorn App in Rancher 2.0):

  1. kubectl --kubeconfig=kube_configxxx.yml delete  -f https://raw.githubusercontent.com/llparse/longhorn/v0.1/deploy/uninstall-for-upgrade.yml

For Longhorn v0.2:

  1. kubectl --kubeconfig=kube_configxxx.yml delete  -f https://raw.githubusercontent.com/rancher/longhorn/v0.2/deploy/uninstall-for-upgrade.yml

If both commands returned Not found for all components, Longhorn is probably deployed in a different namespace. Determine which namespace is in use and adjust NAMESPACE here accordingly:

  1. NAMESPACE=<some_longhorn_namespace>
  2. curl -sSfL https://raw.githubusercontent.com/rancher/longhorn/v0.1/deploy/uninstall-for-upgrade.yml|sed "s#^\( *\)namespace: longhorn#\1namespace: ${NAMESPACE}#g" > longhorn.yml
  3. kubectl --kubeconfig=kube_configxxx.yml delete  -f longhorn.yml

Backup Longhorn System

We’re going to backup Longhorn CRD yaml to local directory, so we can restore or inspect them later.

Upgrade from v0.1

User must backup the CRDs for v0.1 because we will change the default deploying namespace for Longhorn. Check your backups to make sure Longhorn was running in namespace longhorn, otherwise change the value of NAMESPACE below.

  1. NAMESPACE=longhorn
  2. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get volumes.longhorn.rancher.io -o yaml > longhorn-v0.1-backup-volumes.yml
  3. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get engines.longhorn.rancher.io -o yaml > longhorn-v0.1-backup-engines.yml
  4. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get replicas.longhorn.rancher.io -o yaml > longhorn-v0.1-backup-replicas.yml
  5. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get settings.longhorn.rancher.io -o yaml > longhorn-v0.1-backup-settings.yml

After it’s done, check those files, make sure they’re not empty (unless you have no existing volumes).

Upgrade from v0.2

Check your backups to make sure Longhorn was running in namespace longhorn-system, otherwise change the value of NAMESPACE below.

  1. NAMESPACE=longhorn-system
  2. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get volumes.longhorn.rancher.io -o yaml > longhorn-v0.2-backup-volumes.yml
  3. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get engines.longhorn.rancher.io -o yaml > longhorn-v0.2-backup-engines.yml
  4. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get replicas.longhorn.rancher.io -o yaml > longhorn-v0.2-backup-replicas.yml
  5. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get settings.longhorn.rancher.io -o yaml > longhorn-v0.2-backup-settings.yml

After it’s done, check those files, make sure they’re not empty (unless you have no existing volumes).

Delete CRDs in Different Namespace

This is only required for Rancher users running Longhorn App v0.1. Delete all CRDs from your namespace which is longhorn by default.

  1. NAMESPACE=longhorn
  2. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get volumes.longhorn.rancher.io -o yaml | sed "s/\- longhorn.rancher.io//g" | kubectl --kubeconfig=kube_configxxx.yml  apply  -f -
  3. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get engines.longhorn.rancher.io -o yaml | sed "s/\- longhorn.rancher.io//g" | kubectl --kubeconfig=kube_configxxx.yml  apply  -f -
  4. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get replicas.longhorn.rancher.io -o yaml | sed "s/\- longhorn.rancher.io//g" | kubectl --kubeconfig=kube_configxxx.yml  apply  -f -
  5. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} get settings.longhorn.rancher.io -o yaml | sed "s/\- longhorn.rancher.io//g" | kubectl --kubeconfig=kube_configxxx.yml  apply  -f -
  6. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} delete volumes.longhorn.rancher.io --all
  7. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} delete engines.longhorn.rancher.io --all
  8. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} delete replicas.longhorn.rancher.io --all
  9. kubectl --kubeconfig=kube_configxxx.yml -n   ${NAMESPACE} delete settings.longhorn.rancher.io --all

Install Longhorn

Upgrade from v0.1

For Rancher users who are running Longhorn v0.1, do not click the upgrade button in the Rancher App.

  1. Delete the Longhorn App from Catalog Apps screen in Rancher UI.
  2. Launch Longhorn App template version 0.3.1.
  3. Restore Longhorn System data. This step is required for Rancher users running Longhorn App v0.1. Don’t change the NAMESPACE variable below, since the newly installed Longhorn system will be installed in the longhorn-system namespace.
  1. NAMESPACE=longhorn-system
  2. sed "s#^\( *\)namespace: .*#\1namespace: ${NAMESPACE}#g" longhorn-v0.1-backup-settings.yml | kubectl --kubeconfig=kube_configxxx.yml  apply  -f -
  3. sed "s#^\( *\)namespace: .*#\1namespace: ${NAMESPACE}#g" longhorn-v0.1-backup-replicas.yml | kubectl --kubeconfig=kube_configxxx.yml  apply  -f -
  4. sed "s#^\( *\)namespace: .*#\1namespace: ${NAMESPACE}#g" longhorn-v0.1-backup-engines.yml | kubectl --kubeconfig=kube_configxxx.yml  apply  -f -
  5. sed "s#^\( *\)namespace: .*#\1namespace: ${NAMESPACE}#g" longhorn-v0.1-backup-volumes.yml | kubectl --kubeconfig=kube_configxxx.yml  apply  -f -

Upgrade from v0.2

For Longhorn v0.2 users who are not using Rancher, follow the official Longhorn Deployment instructions.

Access UI and Set BackupTarget

Wait until the longhorn-ui and longhorn-manager pods are Running:

  1. kubectl --kubeconfig=kube_configxxx.yml -n   longhorn-system get pod -w

Access the UI.

On Setting > General, set Backup Target to the backup target used in the previous version. In our example, this is nfs://longhorn-test-nfs-svc.default:/opt/backupstore.