Upgrade from v1.7.x to v1.7.y

General information

An Upgrade button appears on the Dashboard screen whenever a new SUSE Virtualization version that you can upgrade to becomes available. For more information, see Start an upgrade.

For information about upgrading SUSE Virtualization in air-gapped environments, see Prepare an air-gapped upgrade.

Update the Harvester UI Extension on SUSE Rancher Prime v2.13

You must use a compatible version (v1.7.x) of the Harvester UI Extension to import SUSE Virtualization v1.7.x clusters on Rancher v2.13.

  1. On the Rancher UI, go to local → Apps → Repositories.

  2. Locate the repository named harvester, and then select ⋮ → Refresh.

  3. Go to the Extensions screen.

  4. Locate the extension named Harvester, and then click Update.

  5. Select a compatible version, and then click Update.

  6. Allow some time for the extension to be updated, and then refresh the screen.

Known issues

Upgrade is stuck in the "Post-draining" state

During the node draining process, the upgrade-repo deployment may get stuck when its SUSE Storage volume remains in the "Attaching" state. This causes the upgrade flow to stall in the "Post-draining" phase, since the post-drain jobs wait for the upgrade-repo deployment to become ready before proceeding.

The workaround is to delete the SUSE Storage replica of the upgrade-repo volume on the drained node. This allows the volume to attach and the upgrade flow to continue. Note that any node being drained during the upgrade may encounter this issue, so this workaround may need to be applied whenever it occurs.

Related issues: #9597 and #12226

Unnecessary live migrations during the upgrade

SUSE Virtualization v1.6.x enables CPU and memory hot-plugging for virtual machines through KubeVirt’s LiveMigrate workload update strategy. However, upgrading the KubeVirt operator triggers simultaneous live migrations of all running virtual machines to immediately update their virt-launcher pods. This mass migration can overwhelm cluster resources and degrade performance.

To prevent this issue, temporarily disable the LiveMigrate workload update method before upgrading and re-enable it once the upgrade completes. Virtual machines will then migrate naturally during node upgrades, allowing the virt-launcher image to update gradually.

Starting with v1.8.0, this process is handled automatically. The workaround is only necessary when upgrading to a version earlier than v1.8.0.

Pre-upgrade workaround steps

  1. Disable the LiveMigrate workload update method.

       kubectl patch kubevirt kubevirt -n harvester-system --type=merge --patch-file=/dev/stdin <<EOF
   spec:
     workloadUpdateStrategy:
       workloadUpdateMethods: []
   EOF

  2. Edit the harvester ManagedChart resource to prevent drift warnings.

       kubectl edit managedchart.management.cattle.io harvester -n fleet-local

  3. Add the following entry to the spec.diff.comparePatches field:

       spec:
     diff:
       comparePatches:
       # Keep existing entries
       - apiVersion: kubevirt.io/v1
         jsonPointers:
         - /spec/workloadUpdateStrategy/workloadUpdateMethods
         kind: KubeVirt
         name: kubevirt

    You must preserve the existing entries.

  4. Verify that the ManagedChart resource is ready.

       kubectl get managedchart.management.cattle.io harvester -n fleet-local

With these changes, virtual machines will not be scheduled for live migration because of virt-launcher pod image mismatches during the upgrade.

CPU and memory hot-plugging is temporarily unavailable during the upgrade. For more information about decoupling this feature from workload update flags, see KubeVirt issue #17329.

Post-upgrade workaround steps

After the upgrade completes successfully, restore the LiveMigrate workload update method to re-enable CPU and memory hot-plugging.

  1. Re-enable the LiveMigrate workload update method.

       kubectl patch kubevirt kubevirt -n harvester-system --type=merge --patch-file=/dev/stdin <<EOF
   spec:
     workloadUpdateStrategy:
       workloadUpdateMethods:
       - LiveMigrate
   EOF

  2. Edit the harvester ManagedChart resource.

       kubectl edit managedchart.management.cattle.io harvester -n fleet-local

  3. Remove the entry you added to the spec.diff.comparePatches field.

  4. Verify that the LiveMigrate method has been restored.

       kubectl get kubevirt kubevirt -n harvester-system -o yaml | grep -A 3 workloadUpdateStrategy

    Expected output:

       workloadUpdateStrategy:
     workloadUpdateMethods:
     - LiveMigrate

Related issue: #10349