Skip to main content
Version: 3.1

Installation guide for one-click update and upgrade in CubeCOS

This guide shows how to upgrade the firmware and update the fixpack. It covers the entire update process, from file upload and MD5 verification to automated rolling upgrades and VM evacuation. The guide also includes troubleshooting steps and a reference for error codes.

Prerequisites​

Before starting the upgrade/update, ensure the following:

  1. Review release notes & changelog for the new version.
    • Release notes: Learn about the new features, known issues, and compatibility in this release.
    • Changelog: View the list of specific code fixes and component updates.
  2. Confirm all services are in a Healthy state and have no errors.
  3. Schedule the upgrade/update during off-peak hours to minimize the impact on your production environment.
  4. Also read the CubeCOS upgrade guide for more information.

Upgrade CubeCOS firmware​

Firmware upgrades are used to transition the entire system to a new base version, which involves node partitioning and will reset all existing fixpack data.

note

After upgrading the firmware, the history and packages of all fixpacks are reset.

  1. Go to the Firmware List page. Navigate Home > Maintenance > Update > Firmware List tab.

  2. Upload firmware files & MD5 checksum files.

    1. Click Upload Firmware.

    2. Click Upload from computer and select the firmware file.

    3. Click Choose checksum to upload the checksum file

    4. To begin upload operations after files are chosen, click Done.

      note

      If the upload fails at the MD5 sum check, verify the integrity of the file.

  3. To start the upgrade process, click Update.

  4. For non-disruptive rolling cluster upgrade, click the Rolling update checkbox.

    warning

    This enables non-disruptive cluster operation in a rolling fashion. Without it, the cluster will reboot simultaneously.

    • Each node will be updated one by one.
    • The system automatically evacuates VMs from nodes before the update to prevent service disruption.

  5. Monitor the update: The system starts a parallel firmware update (partitioning phase) on all nodes.

    • If you select Rolling upgrade, the rolling procedure starts automatically after the partitioning phase completes on all nodes.
    • If a node fails. For example, due to a VM evacuation failure, the auto-rolling upgrade stops immediately. To resolve this, check the CubeCOS logs to identify the cause. If it is safe to proceed, click continue anyway.

  6. After all nodes are successfully updated, click Done to return and the Firmware List page.

  7. Ensure that the displayed version matches the uploaded version.

Install CubeCOS fixpacks​

Fixpack provides targeted patches for specific issues and can be installed or rolled back without a full system version change.

  1. Go to the Fixpack List page. Navigate Home > Maintenance > Update > Fixpack List.

  2. Upload fixpack files & MD5 checksum files.

    1. Click Upload Fixpack.

    2. Click Upload from computer and select the fixpack file.

    3. Click Choose checksum to upload the checksum file

    4. To begin upload operations after files are chosen, click Done.

      note

      If the upload fails at the MD5 sum check, verify the integrity of the file.

  3. Start the installation procedure. Click Install.

    note

    Installing the latest fixpack requires all previous dependencies to be installed first.

  4. If a reboot is required for the fixpack, reboot the CubeCOS system. Click Reboot now.

  5. Install fixpacks with rollback considerations.

    • For fixpacks that support rollback.
      1. To roll back to the previous fixpack, click Yes, rollback.
      2. If a reboot is required for the fixpack, select the checkbox and click Yes, install.
    • For fixpacks that don't support rollback prompt to accept. Check the box, then click Yes, Install.

  6. After all nodes are successfully updated, click Done and return to the Fixpack List page.

Rollback​

If the fixpack installation fails (step 4 in section Install CubeCOS fixpack), you can roll back to the previous version. This is only necessary if the installation creates errors.

Rollback to previous version​

If you encounter issues with a fixpack, follow these steps to perform a rollback.

  1. In the Fixpack List, locate the fixpack you want to remove.
  2. Verify that the fixpack includes a rollback option.
  3. Click Rollback.
  4. To complete the process, click Confirm.

Troubleshooting​

In the event of a node failure, log in to the failed node and check the logs using the following command:

journalctl -fu cube-cos-api

The following table lists the error codes for the firmware partitioning phase and provides recommended actions to resolve each issue:

CodeMessageRecommended Actions
UPG1001Unable to connect node node_nameCheck the SSH connection between VIP node and target node
UPG1002Unable to sync firmware pkg to node node_nameCheck if the firmware pkg does exist on the VIP node and target node
UPG2001Firmware update failed with only num_success/num_node nodes successfully partitionedRun the update command via the CLI.
UPG2002Firmware update failed with target partition corruptedRun the update command on failed nodes. Otherwise, confirm firmware source, verify checksum and disk health
UPG2003Firmware update failed with unknown errors that need to be investigatedFirmware update failed with unknown errors that need to be investigated

Placeholder definitions:

  • num_success: The number of nodes that completed the partitioning phase successfully.
  • num_node: The total number of nodes in the cluster.
  • node-name: The hostname or ID of the node.
info

For details on how to run the update command via the CLI, see Manual upgrade via CLI.

Last updated on by Brian Su