Alauda Build of HAMi

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 Build of HAMi-WebUI.

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.9)Important Changes (v2.8)Important Changes (v2.5 -> v2.6)ProcedureUpgrade HAMi Ascend Device PluginUpgrade HAMi-WebUIBackend checks after upgradeRollback conditionsRelated references

Before you upgrade

  1. Check the supported target combination in Versions and Components and the version-specific changes in Release Notes.

  2. Make all target product packages available in ACP before changing the installed versions.

  3. Record the current cluster-plugin form values, active backend, node labels, RuntimeClass, resource keys, and device-plugin owner.

  4. Back up HAMi ConfigMaps that contain node-specific configuration. This is required when dynamic MIG or other direct ConfigMap customization is used:

    kubectl -n <hami-namespace> get configmap hami-device-plugin \
  hami-scheduler-device -o yaml > hami-config-before-upgrade.yaml

  5. If the Ascend Device Plugin is installed, save its custom resource:

    kubectl -n <hami-namespace> get hamiadp hami-ascend-device-plugin \
  -o yaml > hami-adp-before-upgrade.yaml

  6. 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.9)

ChangeRequired Action
HAMi v2.9.x uses the new metric names supported by Alauda Build of HAMi-WebUI v1.10.3.Upgrade HAMi-WebUI to v1.10.3 before or together with HAMi v2.9.x. Do not use HAMi-WebUI v1.10.0 with HAMi v2.9.x.
The scheduler custom-image path is fully supported in the v2.9.0 delivery package.If the cluster requires an explicit scheduler image, configure scheduler.kubeScheduler.customImage; when it is empty, the image is generated from the target cluster Kubernetes version and configured registry.
The Alauda delivery package configures standard tolerations for HAMi scheduler and device-plugin workloads on tainted accelerator nodes.Keep node taints and tolerations aligned with the target cluster. After upgrade, confirm both workloads are scheduled and ready.
The formal plugin package keeps target-cluster scheduler images separate from HAMi-owned package images.Do not add the cluster's scheduler image to HAMi package-owned related images; verify the target cluster supplies its own scheduler image.

Important Changes (v2.8)

ChangeRequired Action
devicePlugin.nvidianodeSelector was renamed to devicePlugin.nvidiaNodeSelector.If you override Helm values directly, update the key name before upgrading.
Monitor resource configuration moved from devicePlugin.vgpuMonitor.resources to devicePlugin.monitor.resources.If you customized monitor resources, move the values to the new path.
Earlier Alauda Build of HAMi-WebUI v1.5.0 is not compatible with HAMi v2.8.Upgrade Alauda Build of HAMi-WebUI to a v1.10.x version delivered for the same product line.
Ascend support is controlled by the Enable Ascend plugin option.Enable Enable Ascend explicitly when the target HAMi deployment uses Ascend NPU or Ascend vNPU. The option is disabled by default.

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)

VersionParameter AvailabilityRequired Action After Upgrade
HAMi v2.5NVIDIA Runtime Class Name and Create NVIDIA Runtime Class are not included in the plugin form.N/A
HAMi v2.6These parameters must be configured when deploying a plugin instance on a new node.Update plugin deployment parameters:
- NVIDIA Runtime Class Name: hami-nvidia
- Create NVIDIA Runtime Class: true
NOTE

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

  1. Upgrade ACP first if the target HAMi version requires a newer ACP version.
  2. Upload the target package of Alauda Build of HAMi to ACP.
  3. Confirm that the selected backend remains supported by the target package, especially for Ascend NPU or Ascend vNPU paths.
  4. Go to Administrator -> Marketplace -> Cluster Plugins, switch to the target cluster, and upgrade Alauda Build of HAMi.
  5. Verify 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

  1. Confirm that the target Operator Bundle supports the target HAMi version and selected Ascend path.
  2. Upgrade Alauda Build of HAMi Ascend Device Plugin through OperatorHub. If the Subscription uses manual approval, review and approve the generated InstallPlan.
  3. Keep the existing HAMiAscendDevicePlugin custom resource unless the release notes require a field change.
  4. Verify that the CSV reaches Succeeded, the custom resource reconciles, and the DaemonSet becomes Ready.
  5. Confirm that the native Ascend Device Plugin remains stopped during the rollout.

Upgrade HAMi-WebUI

  1. Select the HAMi-WebUI version required by the target HAMi version.
  2. Regenerate and preflight the Prometheus settings by following Install HAMi-WebUI.
  3. Upgrade Alauda Build of HAMi-WebUI through the ACP cluster-plugin page while preserving the intended Prometheus address and NodePort configuration.
  4. Verify that the WebUI Pod becomes Ready and that the backend instant-vector query returns HTTP 200 with a JSON data array.
  5. On v1.10.3, verify the task-list search with a Pod name. The list is Pod-level and intentionally does not treat an internal container name as the task name.

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.