#安装

#前提条件

#通用要求

1. ACP 版本：v4.0 或更高版本。
2. 目标 ACP 集群的集群管理员访问权限。
3. 受支持的 NPU 硬件。NPU worker 节点必须搭载以下之一：
   • Ascend 910B
   • Ascend 310P
4. 必须安装 Alauda Build of Node Feature Discovery 集群插件。operator 会从 NFD 中读取 NPU 是否存在以及 kernel/OS 标签，以决定在每个节点上拉取哪个 driver image。

#MindIO SDK（可选）

如果你计划启用 MindIO TFT 或 MindIO ACP，请在每个 NPU 节点上于 /opt/openFuyao/mindio/ 下单独预置匹配的 MindIO SDK package。否则请跳过此步骤。

#操作步骤

#步骤 1：同步 driver images 并配置 ImageWhiteList

kubectl -n npu-operator rollout restart ds/ascend-runtime-containerd

#1.1 从 Docker Hub 拉取 driver images

driver image 独立发布在 Docker Hub 的 docker.io/alaudadockerhub/ascend-driver 上——不包含在 operator bundle 中——因为 driver 的 .ko binaries 依赖于 kernel，而且 kernel 列表会随着时间增长。每个 tag 都遵循 <HDK>-<chip>-<kernel>-<os-stem> 的格式，例如 25.5.0-910b-6.6.0-145.0.4.135-oe2403sp3。请选择与节点 uname -r 和 chip 匹配的 tag。

列出可用的 tag：

curl -s 'https://hub.docker.com/v2/repositories/alaudadockerhub/ascend-driver/tags/?page_size=100' \
  | jq -r '.results[].name'

在一台可访问互联网的机器上，将每个选定的 tag 镜像同步到你的集群 registry：

TAG=25.5.0-<chip>-<kernel>-<os-stem>

skopeo copy --all \
  docker://docker.io/alaudadockerhub/ascend-driver:$TAG \
  docker://<your-cluster-registry>/mlops/ascend-driver:$TAG

operator 配置会将 spec.driver.image.repository 默认设为 mlops/ascend-driver；如果你的 registry 使用了不同的 namespace，请在部署表单中覆盖该值。

#1.2 在 ImageWhiteList 中放行 driver image

ACP 会限制 pod 允许拉取的 image。DaemonSet 可能拉取的每个 driver-image tag 都必须显式列入 ImageWhiteList。

创建一个新的 ImageWhiteList（或者扩展 cpaas-system 中现有的 ascend-driver ImageWhiteList）：

apiVersion: app.alauda.io/v1alpha1
kind: ImageWhiteList
metadata:
  name: ascend-driver
  namespace: cpaas-system
spec:
  repoList:
  # one entry per tag you mirrored in step 1.1 — full image reference, not bare repo path
  - <your-cluster-registry>/mlops/ascend-driver:25.5.0-910b-<kernel>-<os-stem>
  - <your-cluster-registry>/mlops/ascend-driver:25.5.0-310p-<kernel>-<os-stem>

为你镜像同步的每个 <chip, kernel> tag 添加一条 repoList 记录。每条记录都必须是包含 tag 的完整 image 引用（API 不接受仅仓库路径）。如果你之后覆盖了 spec.driver.image.repository，则需要改为列出新的路径。

#1.3 验证

在每个 NPU 节点上，kubelet 应该能够拉取 driver image（请使用与该节点 kernel 匹配的 tag）：

crictl pull <your-cluster-registry>/mlops/ascend-driver:$TAG

如果这一步成功，则说明步骤 1 已完成。后续 driver DaemonSet 出现 ImagePullBackOff，通常意味着 registry 中缺少对应 tag、registry 凭证有问题，或者 ImageWhiteList 中缺少 repoList 记录。

#步骤 2：下载 package

#步骤 3：上传 package

平台提供了 violet 命令行工具，用于上传从 Customer Portal Marketplace 下载的 operator package 和 cluster plugin package。

详情请参见 上传 Package。

#步骤 4：安装 Node Feature Discovery 集群插件

Alauda Build of Node Feature Discovery 是一个 cluster plugin，不是 operator。请先安装它，因为 NPU Operator 依赖其节点标记。

1. 进入 Administrator > Marketplace > Cluster Plugins。
2. 切换到目标集群。
3. 找到 Alauda Build of Node Feature Discovery，然后点击 Install。

#步骤 5：安装 Alauda Build of NPU Operator

Alauda Build of NPU Operator 以 operator（OLM bundle）的形式交付。在平台 UI 中，安装分为两个不同的子步骤：

1. 安装 operator —— OperatorHub 流程只会启动 operator 的 controller pods（npu-operator-controller-manager + npu-operator）。它不会部署任何 driver、device plugin 或其他 NPU components。
2. 创建 NPUOperatorCtl 实例 —— 只有在这一步你才会填写部署表单，并且只有在实例创建之后，controller pods 才会开始进行 reconcile，并将 NPU components 滚动部署到各个节点上。

#5.1 给节点打标签

将标签 masterselector=dls-master-node 应用于所有主节点，将标签 workerselector=dls-worker-node 应用于需要承载 NPU components 的 worker 节点：

kubectl label nodes <master-node-id> masterselector=dls-master-node
kubectl label nodes <worker-node-id> workerselector=dls-worker-node

#5.2 安装 operator

1. 进入 Administrator > Marketplace > OperatorHub，切换到目标集群，并找到 Alauda Build of NPU Operator 条目。如果状态为 Absent，请确认已在 步骤 3 中使用 violet 上传了 operator package。

2. 点击该 operator 打开详情页，然后点击 Install。

3. 在安装页面中，保持 Channel 不变，确认 Version，将 Installation Location 保持为 npu-operator（默认值；下一子步骤创建的所有 NPU components 都会部署在此处），并将 Upgrade Strategy 选择为 Manual。点击 Install。

4. 等待 subscription 进入 Succeeded。Alauda Build of NPU Operator 磁贴应从 Installing 变为 Installed，并且 kubectl -n npu-operator get pod 会显示两个 controller pods（npu-operator 和 npu-operator-controller-manager）处于 Running 状态。

#5.3 创建 NPUOperatorCtl 实例

部署表单是在创建实例时打开的，而不是在上面安装 operator 时打开的。

1. 在 Installed Operators 页面中，点击 Alauda Build of NPU Operator 磁贴，然后点击 Create Instance（或者打开 NPUOperatorCtl 选项卡并点击 Create NPUOperatorCtl）。

2. 填写表单（见下表），然后点击 Create。

3. operator 会立即进行 reconcile：driver / device plugin / runtime sidecar / exporter / rebooter DaemonSets 会部署到每个 NPU 节点上，并且在所有组件启动完成后，controller 会将 NPUOperatorCtl 的 status.conditions 更新为 Deployed=True / UpgradeSuccessful。

部署表单参数说明：

#验证

1. 确认 NPUOperatorCtl 实例正在正常 reconcile：

   kubectl -n npu-operator get npuoperatorctl

   Deployed condition 应为 True，原因为 UpgradeSuccessful。（如果你在安装时选择的 namespace 不是 npu-operator，请在下面以及后续命令中将其替换为你选择的 namespace。）

2. 等待 npu-driver pod 变为 Running。首次安装时，driver image 的拉取以及模块插入主机 kernel 需要几分钟：

   kubectl -n npu-operator get pod -w | grep npu-driver

3. 检查 NPU 节点现在是否报告了可分配的 Ascend devices：

   kubectl get node ${nodeName} -o jsonpath='{.status.allocatable}'
   # Example output includes:
   #   "huawei.com/Ascend910":"8"   (910B nodes; specific value depends on card count)
   #   "huawei.com/Ascend310P":"1"  (310P nodes)

4. （可选）在主机上运行 npu-smi info。operator 不会将 npu-smi 软链接到主机的 PATH（Alauda OS 中 /usr 是只读的），因此请在加载其 library 后直接调用二进制文件：

   LD_LIBRARY_PATH=/var/lib/Ascend/driver/lib64/driver:/var/lib/Ascend/driver/lib64/common \
     /var/lib/Ascend/driver/tools/npu-smi info

   每块卡都应报告 Health: OK，并且具有非零的 Bus-Id。

5. 使用一个示例 NPU workload 进行端到端验证。v1.2.4 已不再要求 runtimeClassName: ascend——仅资源请求本身就会触发 CDI device injection。在 air-gapped 或启用了 image-whitelist 强制检查的集群中，请先将示例 image 镜像同步到你的集群 registry，或者将其替换为一个等效的内部测试 image，该 image 包含 npu-smi。

   cat <<EOF | kubectl apply -f -
   apiVersion: v1
   kind: Pod
   metadata:
     name: npu-smoke
   spec:
     restartPolicy: Never
     containers:
     - name: probe
       image: ascendai/pytorch:ubuntu-python3.8-cann8.0.rc1.beta1-pytorch2.1.0
       command: ["bash", "-c"]
       args:
         - |
           ls /dev/davinci*
           npu-smi info
           sleep 3600
       resources:
         limits:
           huawei.com/Ascend910: 1   # Change to huawei.com/Ascend310P on a 310P node
   EOF
   
   kubectl logs npu-smoke

   pod 应该达到 Running。ls /dev/davinci* 应显示 /dev/davinci_manager 以及每块卡对应的 device node（例如 /dev/davinci0），而 npu-smi info 应打印该卡的状态。这两者都表明 CDI 已将 device 注入到容器中。

#步骤 6：验证监控

如果在安装 Alauda Build of NPU Operator 时部署了 NPU Exporter component，operator 会自动在 operator namespace 中部署一个名为 npu-exporter-servicemonitor 的 ServiceMonitor，并将其连接到 npu-exporter Service。无需手动创建 ServiceMonitor。你可以使用以下命令进行验证：

kubectl -n npu-operator get servicemonitor npu-exporter-servicemonitor

要获取 Grafana dashboard，请按照 导入 Dashboard 的说明导入 JSON 文件。

该 JSON 文件可在 ascend-npu-dashboard 中获取。

{
  "tags": [
    "ascend",
    "昇腾"
  ]
}

{
  "tags": [
    "ascend"
  ]
}

#后续步骤

• Driver 升级与自愈 —— 如何向前升级 driver 版本，以及芯片自愈路径的工作原理。

#常见问题

#主机上的 npu-smi 安装在哪里？

在 v1.2.4 中，driver pod 会将 Huawei tools tree 预置到 /var/lib/Ascend/driver/，因此二进制文件位于 /var/lib/Ascend/driver/tools/npu-smi。不会创建主机 PATH 软链接（Alauda OS 会将 /usr 保持为只读）。请结合匹配的 LD_LIBRARY_PATH 调用它：

LD_LIBRARY_PATH=/var/lib/Ascend/driver/lib64/driver:/var/lib/Ascend/driver/lib64/common \
  /var/lib/Ascend/driver/tools/npu-smi info

如果你希望使用一个可通过 PATH 直接访问的命令，可以在可写位置（例如 /opt/bin/npu-smi）编写一个小型 wrapper，用于导出 LD_LIBRARY_PATH 并执行真实的二进制文件。

#工作负载 pod 还需要 runtimeClassName: ascend 吗？

不需要。v1.2.4 使用 CDI 进行 device injection：只需请求 huawei.com/Ascend910（或 Ascend310P）即可。现有清单如果仍然设置了 runtimeClassName: ascend 也可以继续工作——保留该 RuntimeClass 是为了向后兼容——但新的清单不再需要它。

#卸载 Alauda Build of NPU Operator 时需要注意什么？

卸载 operator 会移除 driver DaemonSet，但已经加载到主机 kernel 中的 driver modules 会保持加载状态——执行 rmmod 可能会使芯片处于无法恢复的状态。若要从主机上彻底移除 driver，请在卸载 operator 后重启节点；由于 DaemonSet 已被移除，modules 不会自动重新加载。

如有需要，可以手动清理已预置到主机的文件：

rm -rf /var/lib/Ascend /var/lib/ascend /home/bios/driver /etc/ascend_install.info /run/ascend

请仅在 operator 及其 driver pod 已被移除、并且节点已经重启之后再执行这些操作（如果你本来就计划重启，则可在重启前执行）。