Install HAMi Ascend Device Plugin

Install Alauda Build of HAMi Ascend Device Plugin when Ascend devices must be exposed through HAMi-managed whole-card allocation, hard slicing, or soft slicing. It is delivered as an Operator Bundle and managed through a HAMiAscendDevicePlugin custom resource. Do not substitute a standalone DaemonSet installation for this ACP-managed component.

WARNING

Review the v1.4.1 release notes, including the Ascend 310P-only validation scope and known hardware limitations, before use.

Before you begin

  • Install Alauda Build of HAMi and enable Enable Ascend in its cluster plugin form.
  • Install the supported Alauda Build of NPU Operator package and prepare the Ascend Driver, OCI Runtime, ascend RuntimeClass, and node health through the Ascend NPU vendor base documentation. Confirm the NPU Operator and Driver combination for the target ACP release before installation.
  • Confirm the supported HAMi and HAMi Ascend Device Plugin combination in Versions and Components.
  • Label each target node with ascend=on unless the installed product configuration uses a different value.
  • Complete Switch the Ascend Device Plugin Owner and confirm that the native Ascend Device Plugin has stopped before creating the HAMiAscendDevicePlugin instance. Do not edit the generated NPUClusterPolicy or DaemonSet.
  • Confirm that the ascend RuntimeClass exists. An admitted HAMi workload must have runtimeClassName: ascend; set it in the manifest unless the NPU Operator webhook or HAMi scheduler is configured to inject it. Use only one RuntimeClass injector.

Apply the default node label when it matches the installed product configuration:

kubectl label node <ascend-node> ascend=on --overwrite

NPU Operator remains installed for HAMi-managed Ascend allocation. Keep its Driver, OCI Runtime, ascend RuntimeClass, and any required Exporter components running; disable only its native Device Plugin through the owner-switch procedure.

Install the Operator Bundle

  1. Retrieve Alauda Build of HAMi Ascend Device Plugin from Customer Portal and upload the Operator Bundle to ACP.

  2. In ACP, open Administrator -> Marketplace -> OperatorHub, switch to the target cluster, and install Alauda Build of HAMi Ascend Device Plugin.

  3. Check the OLM resources. If the Subscription uses manual approval, review and approve the generated InstallPlan.

    kubectl get subscription,csv,installplan -A \
      | grep hami-ascend-device-plugin

    The ClusterServiceVersion must reach Succeeded before you continue.

  4. Create the HAMiAscendDevicePlugin instance from the product form. Complete Namespace and the other required settings described in Configure the instance before creating it. Then verify the instance in the selected namespace:

    kubectl -n <hami-namespace> get \
      hamiascenddeviceplugin.hami.io hami-ascend-device-plugin -o yaml

Configure the instance

Review the following settings before creating the instance. Keep the defaults only when they match the target nodes and existing platform-owned resources.

WARNING

Create the HAMiAscendDevicePlugin instance in kube-system, where the default HAMi installation creates hami-scheduler-device. The HAMi Operator and Hami custom resource normally use hami-system; do not use that namespace for the ADP instance or shared device ConfigMap.

FieldDefaultPurpose
Namespacekube-systemNamespace for the HAMiAscendDevicePlugin operand and the HAMi-owned hami-scheduler-device ConfigMap. The HAMi Operator and Hami custom resource normally use hami-system.
Existing Device ConfigMaphami-scheduler-deviceReuses the global device configuration created by Alauda Build of HAMi.
Ascend Node Label ValueonSelects nodes labeled ascend=<value>.
Create RuntimeClassfalsePrevents the operator from duplicating a RuntimeClass already managed by the platform or another product.
RuntimeClass NameascendRuntimeClass used by HAMi-managed Ascend workloads.
RuntimeClass HandlerascendContainer runtime handler used only when this operator creates the RuntimeClass.
Enable hami-vnpu-corefalseSets the global soft-slicing value only when this instance creates its own device ConfigMap. The v1.4.1 Alauda delivery normally reuses the HAMi-owned hami-scheduler-device ConfigMap, so changing this field alone does not change the effective node mode.
Ascend Driver Host Path/run/ascend/driverHost source path for the driver tree mounted at /usr/local/Ascend/driver inside the device-plugin container. Use the path prepared by the Ascend base product.
HAMi Shared Region Host Path/var/lib/hami/hami-shared-regionWritable host directory used by HAMi vNPU runtime coordination.
HAMi vNPU Core Host Path/var/lib/hami/hami-vnpu-coreWritable host directory used by hami-vnpu-core.
Node ConfigMap Namehami-device-node-configPer-node HAMi vNPU configuration managed by the operator.
Node ConfigurationEmptyOptional per-node settings for soft slicing, virtual-device count, and devices excluded from HAMi management.
Enable ServiceMonitortruePublishes the built-in soft-slice metrics to ACP monitoring when the ServiceMonitor API is available.

Set Ascend Driver Host Path according to the driver deployment:

  • Host Driver: /usr/local/Ascend/driver
  • Alauda OS Runtime Driver: /run/ascend/driver

Before creating the instance, decide whether each target node will serve whole-card workloads, hard slicing, or soft slicing. Whole-card requests do not depend on the partial-memory node mode. For hard or soft slicing in the v1.4.1 Alauda delivery, set the intended per-node value through the structured spec.nodeConfig object; do not rely on spec.hamiVnpuCore.enabled alone while the instance reuses the HAMi-owned ConfigMap.

Use Configure Ascend Slicing Mode for the complete mode mapping, YAML update, vDeviceCount guidance, rollout command, and result interpretation. Use the whole-card or hard- and soft-slice pages for workload requests.

Verify the installation

  1. Check the two namespaces separately. The default HAMi Operator and Hami resource are in hami-system; the scheduler, hami-scheduler-device, and HAMiAscendDevicePlugin operand are in kube-system. Replace <hami-namespace> with kube-system for the following checks:

    kubectl -n <hami-namespace> get configmap hami-scheduler-device
    kubectl -n <hami-namespace> get hamiadp hami-ascend-device-plugin -o yaml
  2. Check the operator and DaemonSet:

    kubectl get csv -A | grep hami-ascend-device-plugin
    kubectl -n <hami-namespace> get ds hami-ascend-device-plugin -o wide
    kubectl -n <hami-namespace> get pods -o wide | grep hami-ascend-device-plugin
  3. Confirm that only the selected device-plugin owner is Ready on the target nodes:

    kubectl get ds -A -o wide \
      | grep -E 'ascend-device-plugin|hami-ascend-device-plugin'
  4. Confirm the actual resource names exposed by the installed package:

    kubectl get node <ascend-node> -o jsonpath='{.status.allocatable}'

Continue only when the node reports the expected HAMi-managed Ascend resources.

For an installation intended for soft slicing, run the effective-mode and scheduler-configuration checks in Configure Ascend Slicing Mode. Continue only when the target node reports hami-vnpu-core=true and the installed configuration contains the model-specific count and memory mappings. Use an optional core key only when that model declares resourceCoreName.

  1. For each representative workload, verify the runtime and device access:

    kubectl -n <namespace> get pod <pod-name> \
      -o jsonpath='{.spec.runtimeClassName}{"\n"}'

    The RuntimeClass must be ascend. Run npu-smi info and a device-memory or inference workload to confirm that the Pod can use the assigned device. Use the whole-card manifest or hard- and soft-slice manifests for this check.

Next steps