Upgrades

Upgrade support matrix

The following table shows the upgrade path of all supported versions.

Upgrade from version	Supported new version(s)
v1.3.1	v1.3.2
v1.2.2/v1.3.0	v1.3.1
v1.2.1	v1.2.2
v1.1.2/v1.1.3/v1.2.0	v1.2.1

Upgrade from version

Supported new version(s)

v1.3.2

v1.3.1

v1.2.2

v1.2.1

Rancher upgrade

If you are using Rancher to manage your Harvester cluster, we recommend upgrading your Rancher server first. For more information, please refer to the Rancher upgrade guide.

For the SUSE Virtualization & Rancher support matrix, please visit our website here.

Upgrading Rancher will not automatically upgrade your SUSE Virtualization cluster. You still need to upgrade your SUSE Virtualization cluster after upgrading Rancher.
Upgrading Rancher will not bring your SUSE Virtualization cluster down. You can still access your SUSE Virtualization cluster using its virtual IP.

Start an upgrade

Before you upgrade your SUSE Virtualization cluster, we highly recommend:
- Back up your VMs if needed.
Do not operate the cluster during an upgrade. For example, creating new VMs, uploading new images, etc.
Make sure your hardware meets the preferred hardware requirements. This is due to there will be intermediate resources consumed by an upgrade.
Make sure each node has at least 30 GiB of free system partition space (df -h /usr/local/). If any node in the cluster has less than 30 GiB of free system partition space, the upgrade will be denied. Check free system partition space requirement for more information.
Run the pre-check script on a SUSE Virtualization control-plane node. Please pick a script according to your cluster’s version: https://github.com/harvester/upgrade-helpers/tree/main/pre-check.

Make sure all nodes' times are in sync. Using an NTP server to synchronize time is recommended. If an NTP server is not configured during the installation, you can manually add an NTP server on each node:

  $ sudo -i

  # Add time servers
  $ vim /etc/systemd/timesyncd.conf
  [ntp]
  NTP=0.pool.ntp.org

  # Enable and start the systemd-timesyncd
  $ timedatectl set-ntp true

  # Check status
  $ sudo timedatectl status

NICs that connect to a PCI bridge might be renamed after an upgrade. Please check the knowledge base article for further information.

Make sure to read the Warning paragraph at the top of this document first.
SUSE Virtualization checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard screen.
- If the cluster is in an air-gapped environment, please see Prepare an air-gapped upgrade section first. You can also speed up the ISO download by using the approach in that section.
Navigate to SUSE Virtualization GUI and click the upgrade button on the Dashboard screen.
Select a version to start upgrading.
Click the circle on the top to display the upgrade progress.

Prepare an air-gapped upgrade

Make sure to check Upgrade support matrix section first about upgradable versions.

Download an ISO file from the Releases page.
Save the ISO to a local HTTP server. Assume the file is hosted at http://10.10.0.1/harvester.iso.

Download the version file from the Releases page (for example, https://releases.rancher.com/harvester/{version}/version.yaml).

Replace isoURL value in the version.yaml file:

  apiVersion: harvesterhci.io/v1beta1
  kind: Version
  metadata:
    name: v1.0.2
    namespace: harvester-system
  spec:
    isoChecksum: <SHA-512 checksum of the ISO>
    isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
    releaseDate: '20220512'

Assume the file is hosted at http://10.10.0.1/version.yaml.

Become root and create a version:

  rancher@node1:~> sudo -i
  rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml

An upgrade button should show up on the SUSE Virtualization UI Dashboard screen.

Free system partition space requirement

The minimum free system partition space requirement is 30 GiB, which will be revised in each release.

SUSE Virtualization checks the amount of free system partition space on each node when you select Upgrade. If any node does not meet the requirement, the upgrade will be denied as follows

If some nodes do not have enough free system partition space, but you still want to try upgrading, you can customize the upgrade by updating the harvesterhci.io/minFreeDiskSpaceGB annotation of Version object.

apiVersion: harvesterhci.io/v1beta1
kind: Version
metadata:
  annotations:
    harvesterhci.io/minFreeDiskSpaceGB: "30" # the value is pre-defined and may be customized
  name: 1.2.0
  namespace: harvester-system
spec:
  isoChecksum: <SHA-512 checksum of the ISO>
  isoURL: http://192.168.0.181:8000/harvester-master-amd64.iso
  minUpgradableVersion: 1.1.2
  releaseDate: "20230609"

Setting a smaller value than the pre-defined value may cause the upgrade to fail and is not recommended in a production environment.