Upgrade
This page describes how to upgrade the installed HAMi product-line components: Alauda Build of HAMi, the backend-specific Alauda Build of HAMi Ascend Device Plugin, and the optional Alauda AI Infrastructure Accelerator Virtualization Console.
Before upgrading, confirm the active backend path and the resource keys currently used by workloads. Use the current delivery package and version page as the source of truth for backend support after upgrade.
TOC
Before you upgradeUpgrade HAMiImportant Changes (v2.10)Important Changes (v2.9)Important Changes (v2.8)Important Changes (v2.5 -> v2.6)ProcedureUpgrade HAMi Ascend Device PluginImportant Changes (v1.4.1)Upgrade HAMi-WebUIBackend checks after upgradeRollback conditionsRelated referencesBefore you upgrade
-
Check the supported target combination in Versions and Components and the version-specific changes in Release Notes.
-
Make all target product packages available in ACP before changing the installed versions.
-
Record the current
Hamicustom resource values or legacy cluster-plugin form values, active backend, node labels, RuntimeClass, resource keys, and device-plugin owner. -
Back up HAMi ConfigMaps that contain node-specific configuration. This is required when dynamic MIG or other direct ConfigMap customization is used:
-
If the Ascend Device Plugin is installed, save its custom resource:
-
If HAMi-WebUI is installed, record its Prometheus address source and NodePort choice. Regenerate the authentication value from the current monitoring Secret instead of storing a decoded username or password.
Upgrade components in the order required by the target compatibility matrix. When a target HAMi version requires a specific HAMi-WebUI version, upgrade HAMi-WebUI before or together with HAMi. Upgrade the Ascend Device Plugin as a separate OperatorHub action.
Upgrade HAMi
Important Changes (v2.10)
For an existing v2.10 Operator installation, upgrade the Operator package through OperatorHub and approve the generated InstallPlan when required. Keep the Hami custom resource, compare its values with the target version, and verify the CSV, Operator, scheduler, device plugin, and a representative GPU workload after reconciliation.
Important Changes (v2.9)
Important Changes (v2.8)
Do not use release-branch installation pages as a source of truth for vendor driver, device plugin, or exporter ownership. Use the current NVIDIA GPU or Ascend NPU vendor base documentation for those components.
Important Changes (v2.5 -> v2.6)
Upgrading from v2.5 to v2.6 should not affect existing applications. Use rolling update for applications after the component upgrade to reduce unexpected runtime differences.
Procedure
- Upgrade ACP first if the target HAMi version requires a newer ACP version.
- Upload the target Operator package of
Alauda AI Infrastructure Accelerator Virtualizationto ACP. - Confirm that the selected backend remains supported by the target package, especially for Ascend NPU or Ascend vNPU paths.
- If the cluster still uses the legacy HAMi cluster plugin, follow the package-form migration above. Otherwise, go to
Administrator->Marketplace->OperatorHub, switch to the target cluster, and upgrade the HAMi Operator through its Subscription and InstallPlan. - Verify the CSV, Operator Deployment,
Hamicustom resource, component Pods, node allocatable resource keys, ACP quota metadata, and workload scheduling from Verification.
Reapply a backed-up node customization only after comparing it with the target version's generated configuration. Do not replace a new ConfigMap wholesale with an older schema.
Upgrade HAMi Ascend Device Plugin
Important Changes (v1.4.1)
- Confirm that the target Operator Bundle supports the target HAMi version and selected Ascend path.
- Upgrade
Alauda Build of HAMi Ascend Device Pluginthrough OperatorHub. If the Subscription uses manual approval, review and approve the generated InstallPlan. - Keep the existing
HAMiAscendDevicePlugincustom resource and its component namespace unless the release notes require a field change. - Verify that the CSV reaches
Succeeded, the custom resource reportsDeployed, and the DaemonSet becomes Ready on the selected nodes. - Confirm that the native Ascend Device Plugin remains stopped during the rollout.
Upgrade HAMi-WebUI
v1.3.0 changes HAMi-WebUI from the earlier Cluster Plugin to an Operator Bundle. There is no in-place upgrade path between these delivery forms.
- Record the existing Prometheus address, authentication source, NodePort choice, and any intended WebUI settings.
- Uninstall the old HAMi-WebUI Cluster Plugin through ACP.
- Confirm that its operator, WebUI workload, Service, configuration resources, and plugin installation objects are removed. Keep shared Prometheus resources and unrelated HAMi workloads.
- Install the v1.3.0
hami-webui-operatorpackage through a fresh Subscription and InstallPlan. - Wait for
hami-webui-operator.v1.3.0to reachSucceededand the operator Deployment to become Ready. - Create the
HamiWebUIcustom resource incpaas-system, restoring the recorded Prometheus and service settings. - Verify that the WebUI Pod becomes Ready and that the backend
instant-vectorquery returns HTTP 200 with a JSONdataarray. - Open the WebUI resource overview, node management, card management, and workload task views after the fresh installation.
Do not accept a page-only smoke test. A page that opens while its Prometheus request returns HTTP 523 has not passed the upgrade.
Backend checks after upgrade
After upgrade, verify:
- HAMi pods are running in the expected namespace;
- nodes selected for HAMi expose the expected HAMi resource keys;
- ACP quota metadata still matches the resource keys users request;
- the same devices are not also exposed by a conflicting vendor direct plugin path;
- monitoring uses the exporter path documented for the backend and version.
For Ascend NPU and Ascend vNPU, do not assume resource key names from earlier versions. Use the current delivery package and version page as the source of truth.
Rollback conditions
Rollback when the target component cannot reconcile, required resource keys disappear, the target runtime path fails, or representative workloads cannot allocate and release devices. Use the ACP or OLM owner to restore the previous component version and its compatible configuration. A package downgrade does not automatically make an older ConfigMap or custom resource schema safe; restore only fields supported by the rollback version and repeat Verification.