# Introduction to one-click update and upgrade in CubeCOS

> This guide explains the technical differences between firmware and fixpack updates to help ensure high availability and business continuity during cluster upgrades.

## Overview {#overview}

Starting with version 3.1.0, CubeCOS includes a rolling update and upgrade feature. This feature automates cluster scheduling and maintenance to simplify multi-node operations and reduce deployment risk.

- **Upgrade Type**:
  - **Fixpack Update**: Updates packages, most of them involves a part of components. These updates typically do not interrupt system operations.
  - **Firmware Update**: Upgrades the operating system (OS). Affected nodes reboot during this process, which temporarily impacts system performance.
- **Version Note**: To upgrade from a version earlier than 3.1.0, you must follow the CLI upgrade guide.
- **Important**: To ensure a successful upgrade, you must review all instructions in this article and the next section. Carefully examine all system-provided information before proceeding.

:::info[Prerequisite]

The one-click update and upgrade operation is only supported by CubeCOS versions **3.1.0** and later.

:::

## Overview of Update and Upgrade Types {#overview-of-update-and-upgrade-types}

CubeCOS classifies upgrades/update into two types based on their impact on the operating system and the upgrade/update mechanism.

| Feature         | Firmware Upgrade      | Fixpack update            |
| :-------------- | :-------------------- | :------------------------ |
| **Method**      | Image-Based (Full OS) | Package-Based (Component) |
| **Pre-process** | Parallel Partitioning | Sequential Install        |
| **Reboot**      | Yes                   | Depends on Version        |
| **Rollback**    | Not Supported         | Supported                 |

### 1. Firmware Upgrade {#1-firmware-upgrade}

- Version number: The major version changes for firmware upgrades (for example, from 3.0.0 to 3.1.0).
- **Image-Based**: Replaces the entire operating system image.
- **Parallel Install**: Prepares partitions on all nodes simultaneously to save time.
- **Irreversible**: Once upgraded, previous fixpack records and package info are cleared.

### 2. Fixpack Upgrade {#2-fixpack-upgrade}

- **Package-based**: Patches or modifies specific software components, including small patches and security fixes.
- **Rolling Install**: Installs on nodes one-by-one to maintain high availability.
- **Safe**: Allows reverting to the previous state if the fixpack supports rollback.

:::warning

Hotfixes are typically emergency patches provided by official technical support. These are manual operations and must be performed under the guidance of Bigstack Technical Support.

:::

## Prerequisites {#prerequisites}

Before starting the upgrade, follow the following checklist to ensure the upgrades/updates do not impact your production workloads.

### Upgrade/Update Type {#upgradeupdate-type}

Determine the scope and type of the update to properly allocate resources and schedule downtime. The specific update type dictates the potential system impact and may increase the number of prerequisites required for a successful implementation.

- **Fixpack update**: Small-scale updates to specific components. These are generally low-impact.
  - **Impact**: Updates typically have minimal impact. Most updates affect only specific components, the system remains operational during the process.
  - **Prerequisites**: Before starting the update, ensure the following:
    - **Dependencies**: Ensure all previous fixpacks are installed, as updates may depend on earlier patches.
    - **Files integrity**: Verify the integrity of the update files.
    - **Rollback**: Check if the update supports rollback, so that you can revert to the previous version if an error occurs.
    - **Reboot**: Depending on the version, some updates may require a system reboot. Ensure it won't impact your production workloads.
- **Firmware upgrade**: Large-scale infrastructure updates. These operations can significantly the cluster performance during upgrade procedures. Schedule dedicated maintenance windows for upgrades.
- **Impact**: Upgrades typically have a major impact. It requires a reboot of each node, which degrades system performance.
  - **Prerequisites**: Before starting the upgrade, ensure the following:
    - **Healthy**: Ensure all nodes are in a healthy state.
    - **Schedule a Maintenance Window**: Plan a time when the upgrade can be performed during off-peak hours.
    - **Reboot**: Ensure the system can reboot during the upgrade process.
    - **Files integrity**: Verify the integrity of the update files.
    - **Rollback**: Note that firmware upgrades are irreversible. Review the release notes and ensure compatibility and "breaking changes".

### Review Release Notes & Compatibility {#review-release-notes--compatibility}

Perform a technical audit to ensure the new version does not break existing production environments.

- **Change Analysis**: Review release notes for "Breaking Changes" or deprecated APIs.
- **Workload Validation**: Verify that your current workloads and third-party integrations are compatible with the target version.
  1. Review the following items that might impact your cluster:
     1. [New features or changes](../release/release-notes#new-features)
     2. Breaking changes
     3. [Known issues](../release/release-notes#known-issues)
     4. [Feature deprecation and EOL notices](../release/release-notes#known-issues)
  2. This version includes updates for several third-party and internal components.
     1. For a list of all updated components and related details, see the [Release Notes](../release/release-notes#components-updated).
     2. Before you upgrade, verify that your environment meets the compatibility requirements. See the [Release Notes](../release/release-notes#compatibility) for more details.

### Schedule a Maintenance Window {#schedule-a-maintenance-window}

Schedule the upgrade during maintenance windows to minimize the impact on your production environment.

### Health Checks {#health-checks}

A healthy baseline is required for a successful upgrade/update.

- **System Integrity**: Run a cluster check and repair to verify all services are Healthy .
- **Error Mitigation**: Resolve any existing system errors or degraded states before beginning, as upgrades/updates can exacerbate minor instability.
  - Ensure all services are healthy before starting an update. Services in an Error state can cause upgrade operations to fail.
  - Upgrading with error-state services can result in a degraded cluster state.
  - For instructions on how to resolve service errors, see [repair services health](../maintenance/cluster/check-repair#repair-service-health-through-the-web-ui).

### Stage and Execute Deployment {#stage-and-execute-deployment}

Finalize the preparation by staging files and initiating the automated workflow.

- **Upload Binaries**: Securely upload the Fixpack or Firmware files to the platform's repository.
- **Trigger Update**: Use the One-Click update feature to start the automated sequence only after all the above prerequisites are verified.

:::warning

Firmware upgrades are **irreversible**. Always verify the compatibility of your workloads with the target version in a staging environment first.

:::

## Upgrade Workflow {#upgrade-workflow}

The lifecycle management engine will track and monitor every stage of the upgrade process.

### Firmware {#firmware}

The CubeCOS upgrade process is designed for speed and flexibility. During an update, the system downloads a new OS image to all nodes and writes it to a secondary partition in parallel. This background process ensures the upgrade files are staged without impacting active services.

:::warning

Following a **firmware upgrade**, individual fixpacks will no longer be displayed in the system history. All previous fixpacks are included in the upgrade.

:::

#### Upgrade Mode {#upgrade-mode}

You can configure the upgrade mode in the Cluster Settings menu. Select the mode that best fits your availability requirements:

- Rolling mode (Default): Best for production environments. The system uses Live Migration to evacuate VMs from a node before rebooting it. Nodes are updated sequentially, ensuring zero downtime for your workloads.
- Non-rolling mode: Best for maintenance windows where speed is the priority. The administrator manually triggers a simultaneous reboot across all nodes. This mode results in workload downtime but completes the cluster-wide update faster.

#### Upgrade Lifecycle {#upgrade-lifecycle}

1. **Installing**: All nodes download and write to partitions simultaneously (No service impact).
2. **Pending reboot**: Nodes sit in idle, ready for the OS switch.
3. **Rebooting**:
   - **Rolling Mode(Defauld)**: System evacuates VMs (Live Migration) and reboots nodes sequentially.
   - **Non-rolling Mode**: Administrator manually triggers a simultaneous reboot.
4. **Succeeded**: Nodes successfully boot from the new partition.

:::tip

For non-disruptive operations in production environments, always select **Rolling Upgrade**. The system will automatically perform VM evacuation to keep services online during node reboots.

:::

### Fixpack {#fixpack}

Ensure safe and recoverable service patching with a sequential approach. Depending on the version, some upgrades may require a system reboot.

#### Fixpack Install (Reboot Required) {#fixpack-install-reboot-required}

1. **Installing**: Nodes apply patches one-by-one (Sequential).
2. **Installed**: Status transitions here if no reboot is required.
3. **Pending reboot**: If a patch requires a kernel/service restart, it enters this state before completing the cycle.
4. **Rollback or Reboot**:
   - **Rollback (Optional)**: If an error occurs, the system reverts nodes to the **Available** state.
   - **Rebooting**: If a patch requires a kernel/service restart, the system reboots the node.

#### Fixpack Install (No Reboot Required) {#fixpack-install-no-reboot-required}

1. **Installing**: Nodes apply patches one-by-one (Sequential).
2. **Installed**: Status transitions here if no reboot is required.
3. **Rollback (Optional)**: If an error occurs, the state can transition to RollingBack to return to Available.

## Summary {#summary}

Understanding the logic helps you choose the right strategy for your maintenance window:

- **Pre-check**: Before starting any upgrade/update, ensure all nodes are in `Healthy` status and check if there is sufficient disk space for the new image.
- **Firmware Upgrade**: Use **Firmware Upgrade**. Parallel partitioning drastically reduces the preparation window for large clusters.
- **Fixpack Update**: Use **Fixpack Update**. It provides a safety net via the rollback mechanism.