#安装 HAMi Ascend Device Plugin

当需要通过 HAMi 管理的整卡分配、硬切分或软切分暴露 Ascend 设备时，请安装 Alauda Build of HAMi Ascend Device Plugin。它以 Operator Bundle 形式交付，并通过 HAMiAscendDevicePlugin 自定义资源进行管理。不要用独立的 DaemonSet 安装替代这个由 ACP 管理的组件。

#准备开始

• 安装 Alauda Build of HAMi，并在其集群插件表单中启用 Enable Ascend。
• 安装 Alauda Build of NPU Operator v26.6.0，并通过 Ascend NPU 厂商基础文档 准备 Ascend driver、runtime、RuntimeClass 和节点健康检查。
• 在 Versions and Components 中确认受支持的 HAMi 与 HAMi Ascend Device Plugin 组合。
• 为每个目标节点添加 ascend=on 标签，除非已安装的产品配置使用其他值。
• 在创建 HAMiAscendDevicePlugin 实例之前，先完成 切换 Ascend Device Plugin 所有者，并确认原生 Ascend Device Plugin 已停止。不要编辑生成的 NPUClusterPolicy 或 DaemonSet。
• 确认 ascend RuntimeClass 已存在。所有由 HAMi 管理的 Ascend 工作负载都必须设置 runtimeClassName: ascend。

当默认节点标签与已安装的产品配置匹配时，请应用默认节点标签：

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

对于 HAMi 管理的 Ascend 分配，NPU Operator 仍需保持安装状态。请保留其 Driver、OCI Runtime、ascend RuntimeClass 以及任何必需的 Exporter 组件继续运行；仅通过所有者切换操作禁用其原生 Device Plugin。

#安装 Operator Bundle

1. 从 customer portal 获取 Alauda Build of HAMi Ascend Device Plugin，并将 Operator Bundle 上传到 ACP。

2. 在 ACP 中，打开 Administrator -> Marketplace -> OperatorHub，切换到目标集群，然后安装 Alauda Build of HAMi Ascend Device Plugin。

3. 检查 OLM 资源。如果 Subscription 使用手动批准，请查看并批准生成的 InstallPlan。

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

   继续之前，ClusterServiceVersion 必须达到 Succeeded。

4. 从产品表单创建 HAMiAscendDevicePlugin 实例。在创建之前，请完成 Namespace 以及 配置实例 中描述的其他必填设置。然后在所选 namespace 中验证该实例：

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

#配置实例

在创建实例之前，请检查以下设置。仅当默认值与目标节点以及现有的平台托管资源匹配时，才保留默认值。

请根据 driver 的部署方式设置 Ascend Driver Host Path：

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

在创建实例之前，请先决定每个目标节点将用于整卡工作负载、硬切分还是软切分。整卡请求不依赖于部分内存节点模式。对于 v1.4.0 的 Alauda 交付版本中的硬切分或软切分，请通过 spec.nodeConfig 为每个节点设置预期值；当实例复用 HAMi 所拥有的 ConfigMap 时，不要仅依赖 spec.hamiVnpuCore.enabled。

有关完整的模式映射、YAML 更新、vDeviceCount 指导、滚动命令和结果解读，请使用 配置 Ascend 切分模式。有关工作负载请求，请使用 整卡 或 硬切分和软切分 页面。

#验证安装

1. 检查 HAMi、设备配置和 HAMiAscendDevicePlugin 资源是否使用同一个 namespace。将 <hami-namespace> 替换为已配置的 namespace；默认值为 kube-system：

   kubectl -n <hami-namespace> get configmap hami-scheduler-device
   kubectl -n <hami-namespace> get hamiadp hami-ascend-device-plugin -o yaml

2. 检查 operator 和 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. 确认目标节点上仅所选的 device-plugin 所有者处于 Ready 状态：

   kubectl get ds -A -o wide \
     | grep -E 'ascend-device-plugin|hami-ascend-device-plugin'

4. 确认已安装软件包暴露的实际资源名称：

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

只有当节点报告了预期的、由 HAMi 管理的 Ascend 资源时，才能继续。

如果安装目标是软切分，请在 配置 Ascend 切分模式 中运行有效模式和 scheduler 配置检查。只有当目标节点报告 hami-vnpu-core=true，并且已安装配置包含型号相关的数量和内存映射时，才能继续。仅当该型号声明了 resourceCoreName 时，才使用可选的 core key。

5. 对于每个代表性工作负载，验证 runtime 和设备访问：

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

   RuntimeClass 必须为 ascend。运行 npu-smi info 以及设备内存或推理工作负载，以确认 Pod 可以使用已分配的设备。请使用 整卡 manifest 或 硬切分和软切分 manifest 进行检查。

#下一步

• 验证完整安装
• 配置 Ascend 切分模式
• 切换 Ascend Device Plugin 所有者
• HAMi on Ascend NPU
• HAMi on Ascend vNPU
• 故障排查