Knowledge Base›Solutions›Upgrade ZStack Cube HCI to 2.4.17 in a dual-management-node HA environment

Upgrade ZStack Cube HCI to 2.4.17 in a dual-management-node HA environment

SolutionsHCI · ZStack Cube HCIVersions2.0.0 / 2.4.17Article IDKB-200141Updated2026-09-17

Environment

Product: ZStack HCI.
Source version: recorded in the source case as Cube 2.0.0.
Target version: Cube 2.4.17.
Primary storage type: Ceph.
Deployment mode: dual management node HA.
Related components: zsha2, zstack-hamon, zstack-upgrade, QEMU, and libvirt.

The source case includes the following ISO files:

ZStackCloud-x86_64-DVD-4.8.18-c76.iso
Cube-x86_64-DVD-2.4.17-c76-Enterprise-upgrade-241024.iso

Diagnosis

Use this article for a planned Cube cloud platform upgrade in a dual-management-node HA environment.

Before performing this procedure, confirm that:

Both management nodes are reachable.
A customer-approved maintenance window has been arranged.
The current system ISO and the target upgrade ISO are ready.
The dual-management-node HA toolkit is ready.
The management nodes can be accessed through IPMI or another out-of-band management method.

Cause

This article is a planned upgrade guide, not a defect recovery procedure. In the source case, the goal is to upgrade the Cube cloud platform to Cube 2.4.17.

In a dual-management-node HA environment, confirm the node that holds the VIP before the upgrade. The dual-management-node HA toolkit upgrade and cloud platform upgrade must be performed on the VIP-holding management node. Database backup, upgrade script backup, and repo dependency update must be completed on both management nodes.

Resolution

1. Disable global VM HA

Before the upgrade, disable global VM HA in the UI to avoid accidentally triggering VM HA during the maintenance window.

UI path:

Settings > HA Policy

Set the global VM HA switch to Disabled.

2. Confirm the management node that holds the VIP

Run the following command on either management node:

zsha2 status

The node whose output shows VIP as yes is the current VIP-holding management node. This node can also be treated as the primary database node.

3. Back up the database and upgrade script

On the VIP-holding management node, back up the database and copy the backup file to /root/:

zstack-ctl dump_mysql --file-name zstack-db-backup-master
cp /var/lib/zstack/mysql-backup/zstack-db-backup-master-*.gz /root/

On the other management node, back up the database and copy the backup file to /root/:

zstack-ctl dump_mysql --file-name zstack-db-backup-slave
cp /var/lib/zstack/mysql-backup/zstack-db-backup-slave-*.gz /root/

Back up the upgrade script on both management nodes:

cp /usr/local/bin/zstack-upgrade /root/zstack-upgrade-bak

4. Refresh the local repo on both management nodes

Run the following command on both management nodes to refresh the local repo:

bash zstack-upgrade -r ZStackCloud-x86_64-DVD-4.8.18-c76.iso

Wait until the repo update is complete on both management nodes.

5. Log in to the VIP-holding management node and prepare the dual-management-node HA toolkit

tar zxvf ZStack-Multinode-HA-Suite.tar.gz

Grant executable permission to the extracted zsha2 and zstack-hamon files:

chmod +x zsha2 zstack-hamon

6. Upgrade the dual-management-node HA toolkit

Run the following command on the VIP-holding management node:

./zsha2 upgrade-ha

Wait until the dual-management-node HA toolkit upgrade is complete.

7. Upgrade the cloud platform

Run the following command on the VIP-holding management node:

zsha2 upgrade-mn -peerpass 'rootpassword' /root/zstack-installer.bin

Wait until the cloud platform upgrade is complete.

8. Upgrade QEMU and libvirt by cluster

During the cloud platform upgrade, QEMU and libvirt virtualization components are upgraded by cluster.

Before continuing, wait until the cluster-level virtualization component upgrade task is complete.

9. Verify resource connection status

After logging in to the UI, confirm the following:

Each host is connected.
Each primary storage is connected.
VM instances are in a normal state.

Wait until all hosts and primary storage are connected, and confirm that VM status is normal before continuing.

10. Re-enable global VM HA

After confirming that VMs, hosts, and primary storage are healthy, re-enable global VM HA in the UI.

Verification

After the upgrade, verify the following:

Run zsha2 status on both management nodes. The dual-management-node HA status is normal.
Each host in the UI host list is connected.
Each primary storage resource in the UI primary storage list is connected.
VM instance status is normal.
Global VM HA has been re-enabled.

Risk

Maintenance window required. This procedure is performed on the management nodes in a dual-management-node HA deployment. During the operation, the management plane may become temporarily unavailable. Perform the upgrade during a customer-approved maintenance window, and confirm that hosts, primary storage, and VMs are healthy after the upgrade.
Disable global VM HA before the upgrade to avoid accidentally triggering VM HA during the maintenance window.
Back up the database and upgrade script on both management nodes before the upgrade so that they can be used for recovery if an exception occurs.
Confirm that the ISO file used for the upgrade matches the onsite upgrade version.