DocsKnowledge BaseAPI Explorer
Documentation›ZCF›UpgradeZCF

Upgrade

Upgrade Overview

A ZCF upgrade consists of two parts: upgrading infrastructure components and upgrading ZCF. Infrastructure components provide cloud platform, storage, container, and network service resources, and must be upgraded separately according to the corresponding product documentation. Upgrading ZCF means using a ZCF Bundle to upgrade the global management capabilities delivered with the Bundle.

In Lifecycle Management, administrators can upload a ZCF Bundle, create an upgrade plan, and complete backup, precheck, execution, and result verification from the UI. Before upgrading ZCF, confirm that infrastructure component versions meet the version mapping required by the target ZCF release. If they do not, upgrade the corresponding infrastructure components first.

Object Upgrade Scope
ZCF upgrade

Uses a ZCF Bundle to upgrade ZCF global management capabilities, such as the ZCF control plane, Unified Portal, authentication, Cloud Federation, Observability, Lifecycle Management, and license management. Administrators create and run the upgrade plan from the Upgrade Management page. The actual scope is determined by the Bundle manifest and the upgrade plan.
Infrastructure components Includes product environments that provide cloud platform, storage, container, and network resources, such as ZStack Cloud, ZStack ZStone, ZStack Zaku, and ZStack ZNS. Upgrade these components according to their own release notes and upgrade documentation. Before upgrading ZCF, confirm that their versions meet the target ZCF version mapping. After the upgrade, verify component access, resource collection, and observability data in ZCF.

Upgrade Infrastructure Components

If the current versions of ZStack Cloud, ZStack ZStone, ZStack Zaku, or ZStack ZNS do not meet the target ZCF version requirements, upgrade the infrastructure components first. A typical infrastructure component upgrade follows this sequence:

  1. Confirm the version mapping between the target ZCF release and each infrastructure component.
  2. Upgrade infrastructure components according to the corresponding product release notes and upgrade documentation.
  3. In ZCF, verify component access, resource collection, observability data, and unified authentication access.

Upgrade ZCF

After infrastructure component versions meet the requirements, use a ZCF Bundle to upgrade ZCF global management capabilities. A typical ZCF upgrade follows this sequence:

  1. Obtain the ZCF Bundle that matches the current environment and target version.
  2. Upload the ZCF Bundle and confirm that the package can be used to create an upgrade plan.
  3. Check the current version, target version, upgrade path, and component health.
  4. Create an upgrade plan and confirm the upgrade objects, component changes, and impact scope.
  5. Run upgrade backup and precheck, then resolve blockers or confirm risks.
  6. Execute the ZCF upgrade and track progress, step status, and events on the page.
  7. After the upgrade, verify the ZCF version, platform health, component access, resource collection, observability data, and upgrade history.

Notes

Note: This guide describes the ZCF Bundle-based upgrade workflow. The actual upgrade path must be supported by the target Bundle and pass the checks on the page. If the page reports that the upgrade path is unsupported or that the package cannot be upgraded, resolve the issue as prompted before executing the upgrade.

Prepare for Upgrade

Before upgrading, confirm infrastructure component version mapping, the upgrade package, the maintenance window, permissions, and environment status. This reduces the risk of upgrade interruption caused by version mismatch, health exceptions, or conflicting tasks.

  1. Confirm whether infrastructure component versions meet the target ZCF version requirements.

    Infrastructure components include ZStack Cloud, ZStack ZStone, ZStack Zaku, and ZStack ZNS. These components provide cloud platform, storage, container, and network resources. They are not upgraded individually by the ZCF Bundle upgrade workflow.

    Check each infrastructure component version against the version mapping required by the target ZCF release. If a version does not meet the requirement, see Upgrade Infrastructure Components to complete the product-side upgrade and post-upgrade checks first. If all versions meet the requirements, record the current versions for later checks and troubleshooting.

  2. Obtain the target ZCF Bundle.

    Obtain the ZCF Bundle for the target version and architecture from the official ZCF download page. Read the release notes to confirm the target version, upgrade scope, and known limitations.

    Select the Bundle that matches the current environment architecture. The actual package name is subject to the download page. Common package names include:

    • x86 architecture: zcf-bundle-latest-amd64.bin
    • ARM architecture: zcf-bundle-latest-arm64.bin
    • Download: Click Here

    After the Bundle is uploaded, ZCF calculates upgrade availability based on the package metadata and the current environment. If the page reports an architecture mismatch or a missing target-architecture package, upload a Bundle for the correct architecture.

  3. Confirm that the current administrator has the required upgrade permissions.

    The administrator must have permissions to upload installation packages, create upgrade plans, and execute upgrades.

  4. Confirm that the platform is ready for upgrade.
    Check ItemDescription
    Maintenance windowReserve an upgrade window based on business impact and notify related operations and business teams in advance.
    Platform healthConfirm that ZCF key services and connected components are running properly. Resolve health exceptions before upgrading.
    Upgrade scopeConfirm the ZCF global management capabilities covered by the target Bundle and upgrade plan. Maintain infrastructure components such as ZStack Cloud, ZStack ZStone, ZStack Zaku, and ZStack ZNS according to their own release notes and upgrade documentation.
    Version mappingConfirm that infrastructure component versions, including ZStack Cloud, ZStack ZStone, ZStack Zaku, and ZStack ZNS, meet the requirements of the target ZCF release. If a component version does not meet the requirement, upgrade that component first.
    Resource capacityConfirm that node disk, CPU, memory, and other resources meet upgrade and backup requirements.
    Conflicting tasksConfirm that no upgrade, deployment, or other critical task that may affect platform status is running.
    Backup strategyConfirm that a usable backup is available before upgrade, and keep required recovery information and operations contacts.

After preparation is complete, go to Lifecycle Management > ZCF Upgrade, and upload the ZCF Bundle from the Package Management area on the Upgrade Management page.

Upgrade Infrastructure Components

Before upgrading infrastructure components, read the release notes for the target ZCF version and the corresponding product versions, and prepare the required product upgrade packages, maintenance window, backups, and operation permissions.

Infrastructure components include ZStack Cloud, ZStack ZStone, ZStack Zaku, and ZStack ZNS. They provide the cloud platform, storage, container, and network service environments. These components are not upgraded individually on the Upgrade Management page. If a current component version does not meet the version mapping required by the target ZCF release, complete the product-side upgrade first, and then continue with the ZCF Bundle upgrade workflow.

  1. Identify the infrastructure components that need to be upgraded.

    Based on the target ZCF version mapping and current environment versions, determine whether ZStack Cloud, ZStack ZStone, ZStack Zaku, or ZStack ZNS meets the requirements. If multiple components must be upgraded, follow the dependency and sequencing requirements in the corresponding product upgrade documentation. If an infrastructure component already meets the requirements, skip the product-side upgrade but still complete the post-upgrade checks.

  2. Upgrade infrastructure components according to the corresponding product documentation.
    Component Product-side Upgrade Product-side Check
    ZStack Cloud Upgrade the cloud platform environment according to the ZStack Cloud release notes and upgrade documentation. Before upgrading, confirm version compatibility with ZCF and reserve a maintenance window. Verify the management UI, management nodes, VM instances, networks, primary storage, image storage, and other key services.
    ZStack ZStone Upgrade the storage environment according to the ZStack ZStone release notes and upgrade documentation. Before upgrading, confirm storage service impact and the recovery plan. Verify storage clusters, storage pools, data services, and the management UI.
    ZStack Zaku Upgrade the container environment according to the ZStack Zaku release notes and upgrade documentation. Before upgrading, confirm cluster, node, and workload status. Verify Kubernetes clusters, nodes, workloads, and the management UI.
    ZStack ZNS Maintain the network service environment according to the ZStack ZNS release notes, upgrade documentation, or Application Market instructions. Before upgrading, confirm the impact on gateways, load balancing, NAT, and related services. Verify network services, gateways, load balancing, NAT, and the management UI.
  3. Verify infrastructure component access in ZCF.

    Go to Cloud Federation > Platform Management, and verify the connection status, version information, collection configuration, and update time of the upgraded components in the Platform Access list or area. If the connection is abnormal, check the component service status and access address, and then verify the connection again.

  4. Verify resource collection and observability data.

    Based on the collection items enabled during component access, check resource, metric, log, dashboard, and report data on the observability pages. If data is empty or the update time is abnormal, check the component connection status and the corresponding collection configuration.

  5. Verify component access and SSO.

    If SSO configuration has been delivered to the components, log in to ZCF through the unified authentication entry and access the corresponding component pages based on your permissions. Confirm that login, redirection, and resource access work as expected.

After infrastructure component upgrades and checks are complete, upload the target ZCF Bundle and create a ZCF upgrade plan.

Upgrade ZCF

Upgrading ZCF means using a ZCF Bundle to upgrade the global management capabilities delivered with the Bundle, such as the ZCF control plane, Unified Portal, authentication, Cloud Federation, Observability, Lifecycle Management, and license management. The ZCF Bundle does not separately upgrade infrastructure components such as ZStack Cloud, ZStack ZStone, ZStack Zaku, and ZStack ZNS.

Before upgrading ZCF, confirm that the infrastructure component versions meet the version mapping required by the target ZCF release. If they do not, upgrade the infrastructure components first, and then upload the ZCF Bundle and create an upgrade plan.

Upload a ZCF Bundle

You have obtained the target ZCF Bundle. Currently, only Bundle files in .bin format can be uploaded.

The Package Management area on the Upgrade Management page manages Bundles stored in Depot. A ready ZCF Bundle can be used to create an upgrade plan.

  1. In the upper-right corner of the main menu, switch to Global Management.
  2. Go to Lifecycle Management > ZCF Upgrade.
  3. Click Upload Bundle.
    Figure 1. Upload Bundle


  4. Select the ZCF Bundle for the target version and click Upload.
  5. On the Bundle Management tab, confirm the package status.
    ItemDescription
    PackageConfirm that the Bundle name is zcf and that the included component count is displayed.
    VersionConfirm that the version matches the planned target version.
    ArchitectureConfirm that the Bundle architecture matches the current environment architecture.
    StatusConfirm that the package is ready or available for upgrade. If the status is blocked, view the reason on the page. Common causes include a version lower than the current environment, an unsupported upgrade path, or a component version mismatch.
    UsageConfirm whether the Bundle is already used by an upgrade plan to avoid deleting or re-uploading a package required by the plan.
    Figure 2. Package Management


After the Bundle is uploaded and its status meets upgrade requirements, go to the Upgrade Management page to view available upgrade targets.

View Available Upgrades

Use the Upgrade Management page to select an upgrade package, confirm the upgrade path, and check whether the current environment meets the basic requirements for creating an upgrade plan.

  1. In the upper-right corner of the main menu, switch to Global Management.
  2. Go to Lifecycle Management > ZCF Upgrade.
  3. In Available Packages, select the target upgrade package.

    You can search by package or version, or filter Bundles by status, such as All, Ready, Blocked, and Current Version. Prefer a Bundle in Ready status. If a Bundle is blocked, view its details and blocking reason first.

  4. In Environment Summary, confirm the current version, target version, upgrade path, component health, and package content.
    ItemDescription
    Current versionThe ZCF version currently running in the environment.
    Target versionThe target version provided by the selected Bundle.
    Upgrade pathWhether a supported path exists from the current version to the target version.
    BundleThe name, version, and manifest checksum of the selected Bundle.
    AvailabilityWhether the selected Bundle can be used in the current environment. If the page reports that the version cannot be upgraded to, resolve the blocking reason first.
    Minimum upgrade versionWhether the current ZCF version meets the minimum upgrade version declared by the Bundle.
    Component healthA health summary of key components before upgrade. If a component is abnormal, go to Observability to locate the issue first.
    Component changesComponent version changes included in this ZCF upgrade. Maintain infrastructure components such as ZStack Cloud, ZStack ZStone, ZStack Zaku, and ZStack ZNS according to their own release notes and upgrade documentation.
    Component package summaryPackage completeness and architecture compatibility in the Bundle. If packages for the current environment architecture are missing, an upgrade plan cannot be created.

    When the selected Bundle is Ready and the environment summary meets upgrade requirements, Create Upgrade Plan is enabled. If the button is unavailable, resolve the blocking items shown on the page first.

After confirming that the target Bundle can be upgraded, create an upgrade plan.

Create an Upgrade Plan and Complete Pre-upgrade Checks

The target ZCF Bundle has been uploaded and is available for upgrade on the Upgrade Management page.

An upgrade plan records the target version, upgrade scope, execution sequence, and check results for this upgrade. Before executing the upgrade, run backup and precheck to confirm that the environment is ready.

  1. On the Upgrade Management page, select the target Bundle and click Create Upgrade Plan.
  2. In the Confirm Plan stage, review the upgrade objects, component changes, and impact scope.

    Use the upgrade objects listed on the page as the final scope. The page shows the execution order, upgrade requirements, nodes or targets, version changes, actions, and health status. ZCF executes the steps included in the Lifecycle Management plan. Infrastructure components such as ZStack Cloud, ZStack ZStone, ZStack Zaku, and ZStack ZNS are not upgraded separately in this plan.

    If the target version, upgrade scope, or component changes do not match expectations, return to the Package Management area on the Upgrade Management page and verify the Bundle.

  3. Click Run Backup to create a pre-upgrade backup.

    The backup provides recovery information if the upgrade fails. After backup completes, review the backup records on the page and confirm that the record ID, backup count, expiration time, and backup item status are normal. If the page shows backup not required, the component does not require a backup. It does not mean that backup failed or was missed. If backup fails, resolve the cause before continuing.

  4. After backup succeeds, click Run Precheck.

    The system runs precheck for the current upgrade plan. After precheck completes, handle issues according to the actual check items and results shown on the page. The precheck result determines whether the upgrade can proceed.

  5. Review the precheck result and handle issues as needed.

    After precheck completes, the page summarizes the result and lets you filter checks by status, such as All, Error, Warning, and Passed. Review the check result, status, description, and note for each item, then follow the page prompt.

    Figure 3. Precheck Result


    ResultMeaningAction
    ErrorA blocking issue prevents the upgrade.Resolve the issue as instructed on the page, then run precheck again.
    WarningA risk requires confirmation but may not block the upgrade.Assess the impact and confirm the risk for the current Precheck revision before executing the upgrade.
    PassedThe check item meets upgrade requirements.No action is required. Continue reviewing other check items.
    SkippedThe check item does not apply to the current upgrade plan or component.Review the note on the page to confirm the reason.
  6. If warnings exist, confirm the risks for the current Precheck revision.

    If the precheck result contains Warning items, review their risk descriptions and business impact, then confirm the risks for the current Precheck revision on the page. Risk confirmation applies only to the current precheck result. If you run precheck again and a new revision is generated, confirm the risks again. You can execute the upgrade only after the required risk confirmation is complete.

    If the precheck result contains errors or other blocking items, resolve them and run precheck again. Do not execute the upgrade directly.

After precheck passes and the required confirmations are complete, execute the upgrade.

Execute the Upgrade

The upgrade plan has been created. Backup and precheck are complete, and no blocking item remains.

After you start the upgrade, ZCF runs the plan and displays the current stage, step status, and events. Monitor the page during the upgrade, and avoid running other operations that may affect platform status.

  1. On the Upgrade Management page, confirm the current plan status.

    Make sure that the upgrade object, target version, backup status, and precheck result are as expected.

  2. Click Execute Upgrade.

    Before execution, confirm again that the maintenance window is still valid and that operations personnel can respond to upgrade exceptions.

  3. Track upgrade progress on the page.
    ItemDescription
    Plan statusCheck whether the plan is running, blocked, paused, failed, or completed.
    Current stepCheck the component and upgrade action currently being executed.
    EventsReview events such as upgrade start, backup, precheck, execution, failure, continuation, and completion.
    Failure detailsIf the upgrade fails or is blocked, check the failed component, failed step, error message, and recovery information.
  4. Wait until the upgrade plan is complete.

    Before the upgrade completes, do not delete the Bundle used by this upgrade, and do not manually clean up upgrade backups or records.

Handle Upgrade Exceptions

If an upgrade plan becomes blocked, paused, or failed, view failure details and events on the page before taking action. Do not delete the Bundle, clean up backups, or manually modify upgrade records.

  1. On the Upgrade Management page, check the current plan status.

    Pay attention to the failed step, failed component, error message, and recent events.

  2. Resolve the blocking or failure cause based on the page prompt.
    ExceptionAction
    Expired precheck resultRun precheck again and confirm that the result still meets upgrade requirements.
    Component health exceptionGo to Observability to locate the abnormal component. After the issue is fixed, click Recheck Component.
    Insufficient resourcesRelease or expand the related resources, then run precheck again.
    Conflicting taskWait for the conflicting task to finish, or handle the conflicting task based on business impact, then run precheck again.
    Step failureReview failure details and recovery information, then follow the page prompt to recheck components, abort the plan, or contact technical support.
  3. Use the available page action to continue handling the upgrade plan.

    Depending on the state, the page may provide actions such as Recheck Component or Abort Plan. Select an action based on failure details and business impact, and use the buttons that are actually available on the page.

    Abort Plan only stops the current upgrade plan from continuing. It does not roll back completed upgrade steps or automatically restore the environment. Before aborting the plan, keep the plan ID, failure details, backup information, and related logs, and assess the next recovery or manual handling steps.

  4. After handling the issue, continue tracking the upgrade plan status.

    If the page indicates that manual handling is required, keep the plan ID, target version, failed step, error message, backup information, and related logs, and contact technical support.

After the upgrade plan resumes, continue monitoring the upgrade page until the plan completes or enters another exception state.

Verify the Upgrade Result

After the upgrade plan is complete, verify the result from version, health, access, and history perspectives to make sure the platform can continue to support daily operations and service access.

  1. On the Upgrade Management page, confirm that the plan status is Completed.
  2. Confirm that the current version has been updated to the target version.

    If the version is not updated or the page displays unexpected information, refresh the page and check the upgrade history.

  3. Check platform health and key service status.

    Go to Operations > Monitoring Center > Platform Health to view key services, health domains, component details, and external dependency status.

  4. Confirm that administrators and regular users can log in and access authorized pages.

    Verify at least SSO login, the Global Management view, the region view, and the major pages involved in this upgrade.

  5. Confirm that infrastructure components can be accessed normally.

    If ZStack Cloud, ZStack ZStone, ZStack Zaku, or ZStack ZNS is connected, confirm the product-side upgrade record, version, and runtime status. In ZCF, confirm connection status, resource collection, observability data, and service entry points.

  6. View the upgrade history.

    On the Upgrade Management page, click View History and confirm that the upgrade record has been generated.

    ItemDescription
    Plan IDThe unique identifier of this upgrade plan, used to locate the upgrade record later.
    BundleThe ZCF Bundle used for this upgrade.
    Upgrade pathThe source version and target version of this upgrade.
    Current statusThe execution result or current status of the upgrade plan.
    Update timeThe latest update time of the upgrade record.

After the upgrade result is verified, close the maintenance window and archive the upgrade record according to your internal process.

PreviousInstallation and DeploymentNextLicense
Upgrade Guide | ZStack Cloud Foundation | ZStack Resource Center