#安装 NPU Operator

#前提条件

• 目标业务集群已授予 Cluster administrator 访问权限，且将要在该集群中安装 Alauda Build of NPU Operator。
• ACP v4.0-v4.3。
• Ascend 910B 或 Ascend 310P worker 节点。
• 目标业务集群已安装 Alauda Build of Node Feature Discovery。
• 在创建 NPUOperatorCtl 实例之前，已选择 driver mode。
• 可访问 Customer Portal 中的 Alauda Build of NPU Operator 包。

有关受支持的组合，请参见 Versions and Components 和 Compatibility。

#准备 NPU 软件包

准备 Ascend NPU 产品线所需的软件包。

Alauda Build of Node Feature Discovery 是一个共享 cluster plugin。它会发布 NPU 组件在调度、组件放置和节点 profile 匹配期间使用的节点事实信息。请在目标业务集群上安装一次，然后再创建 NPUOperatorCtl 实例。

Alauda Build of NPU Operator 是一个 umbrella operator。安装该 operator 后，NPUOperatorCtl 实例将控制在所选节点上协调哪些 NPU 组件。

MindIO TFT 和 MindIO ACP 不是独立的 cluster plugin 包。启用后，Alauda Build of NPU Operator 会使用随包提供的 npu-node-provision 镜像部署 MindIO DaemonSets。在离线或受控网络环境中，请在启用这些组件之前，预先在每个目标节点上准备匹配的 MindIO SDK zip。

#选择 driver 生命周期模式

在创建 NPUOperatorCtl 实例之前，选择 driver 生命周期模式。

在预安装 driver mode 下，operator 不会创建 driver DaemonSet。必须先在每个选定的 NPU 节点上完成 Host driver 的安装并确保其健康运行，然后才能启用 device plugin、runtime 集成、exporter、HCCN 或其他依赖 driver 的组件。

#安装流程

#1. 根据所选 mode 准备 driver

如果你的 NPU 节点已经通过 out-of-band 方式安装了 Huawei .run driver，并且计划在 NPUOperatorCtl 实例中禁用 Driver 管理，则可以跳过 driver 镜像准备。在该 mode 下，请确认每个选定的 NPU 节点上都存在 /usr/local/Ascend/driver。

对于 operator 管理的不可变 OS / Alauda OS 预编译 mode，请导入与每个 (HDK, chip, kernel, OS) 节点 profile 匹配的 ARM64 Driver 镜像。NPU Operator 会在去除 architecture 后缀后，根据 HDK 版本、检测到的 chip 和完整 kernel release 生成 tag：

<HDK>-<chip>-<kernel-release-without-architecture>

对于已发布的 openEuler tag，旧版 tag 约定会将 kernel release 中的 .oe 分隔符重写为 -oe。其他 kernel release 保持不变。不要额外追加检测到的 kernel release 中不存在的独立 OS stem。

Driver 镜像是包外制品，不会随 NPU Operator 包一同导入。以下已发布镜像是指定节点 profile 的示例：

从 Docker Hub 拉取匹配的示例：

docker pull alaudadockerhub/ascend-driver:25.5.0-310p-6.6.0-0008.ctl4
docker pull alaudadockerhub/ascend-driver:25.5.0-910b-6.6.0-145.0.4.135-oe2403sp3

对于其他已发布的 Driver 镜像，请查看 Alauda Ascend Driver repository on Docker Hub 中的 tag。已发布的 tag 只是镜像清单条目，本身并不代表产品支持或验证声明。使用前，请确认 chip、kernel 和 operating system 与目标节点匹配，并且该组合适用于你的部署。

验证所选源镜像报告为 arm64，然后将其镜像到目标业务集群仓库。例如：

SOURCE_IMAGE=docker.io/alaudadockerhub/ascend-driver:25.5.0-310p-6.6.0-0008.ctl4
TARGET_IMAGE=<your-cluster-registry>/mlops/ascend-driver:25.5.0-310p-6.6.0-0008.ctl4

skopeo inspect --override-arch arm64 docker://$SOURCE_IMAGE
skopeo copy --override-arch arm64 \
  docker://$SOURCE_IMAGE \
  docker://$TARGET_IMAGE
skopeo inspect --override-arch arm64 docker://$TARGET_IMAGE

如果没有任何 tag 与你的节点 kernel 匹配，请将 uname -r 的输出和 chip model 提供给 Alauda Customer Support。

当 Driver tag 留空时，NPU Operator 会根据已配置的 Driver version、节点 chip 标签和完整 kernel release 标签来解析它。请为完整的源引用配置镜像映射，包括其解析后的 tag。Driver Pod 启动后，请同时验证已准入的 Pod image 和运行时的 imageID；仅有被重写的 Pod image 并不能证明已拉取到预期镜像。

对于 operator 管理的普通 OS 安装 mode，请使用随包提供的 driver 安装程序镜像，并禁用预编译 driver 交付。该安装流程会将 driver 安装到 /usr/local/Ascend/driver 下。

#2. 在 ImageWhiteList 中放行 driver 镜像

如果 ACP 强制执行镜像白名单策略，并且 operator 管理 driver，请将所需的每个 driver 镜像 tag 添加到目标业务集群中的 ImageWhiteList，即将安装 Alauda Build of NPU Operator 的集群。

如果是预安装 driver mode，则跳过此步骤，除非其他已启用的组件镜像被集群镜像策略阻止。

如果你通过 ACP 控制台配置白名单，请先切换到目标业务集群。下面的示例应用于目标业务集群，并使用该集群中的 cpaas-system namespace。

对于已验证的 310P profile，请匹配 NPU Operator 渲染出的完整源引用，并将其重写为已经导入到集群仓库中的镜像。下面的 build-harbor.alauda.cn 引用仅是 Operator 渲染后的匹配 key；源镜像应按上一步所示从 Docker Hub 获取。

apiVersion: app.alauda.io/v1alpha1
kind: ImageWhiteList
metadata:
  name: npu-operator-precompiled-driver
  namespace: cpaas-system
spec:
  repoList:
  - build-harbor.alauda.cn/mlops/ascend-driver:25.5.0-310p-6.6.0-0008.ctl4
  rewriteRules:
  - regexp: ^build-harbor\.alauda\.cn/mlops/ascend-driver:25\.5\.0-310p-6\.6\.0-0008\.ctl4$
    replacement: <your-cluster-registry>/mlops/ascend-driver:25.5.0-310p-6.6.0-0008.ctl4

你可以将规则添加到平台生成的 ImageWhiteList 或自行管理的对象中。如果更新现有对象，请保留无关条目。每个受支持的 Driver tag 应使用一条精确规则；不要用宽泛的通配符替换 tag。请在创建或更新 NPUOperatorCtl 实例之前应用该规则，并在产品升级后重新检查。

在实例创建托管策略后，确认渲染出的 repository 与该规则一致：

kubectl get npuclusterpolicy cluster \
  -o jsonpath='{.spec.driver.imageSpec.repository}{"\n"}'

然后验证已准入的 Pod 引用以及实际运行的镜像：

kubectl -n npu-operator get pods \
  -l app.kubernetes.io/component=npu-driver \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .spec.containers[*]}  {.name}{" image="}{.image}{"\n"}{end}{range .status.containerStatuses[*]}  {.name}{" imageID="}{.imageID}{"\n"}{end}{end}'

已准入的 image 必须指向 <your-cluster-registry>/mlops/ascend-driver:25.5.0-310p-6.6.0-0008.ctl4。其 imageID 必须解析为导入时记录的目标 digest。

#3. 上传软件包

从 Customer Portal 下载并上传以下软件包：

• Alauda Build of NPU Operator operator 包。
• Alauda Build of Node Feature Discovery cluster plugin 包。
• Volcano cluster plugin 包，仅在你计划启用 ClusterD 时需要。

有关软件包上传流程，请参见 Upload Packages。

#4. 安装 Node Feature Discovery

从 Administrator > Marketplace > Cluster Plugins 安装 Alauda Build of Node Feature Discovery。

NFD 是集群的共享节点发现层。它提供 NPU 安装所依赖的 OS、kernel、architecture 和 PCI 硬件标签。创建 NPUOperatorCtl 实例后，NPU Feature Discovery 会使用这些事实信息以及 Kubernetes node role 来维护 NPU 专用标签和组件放置标签。

#5. 安装 Alauda Build of NPU Operator

1. 转到 Administrator > Marketplace > OperatorHub。
2. 切换到目标业务集群并打开 Alauda Build of NPU Operator。
3. 单击 Install。
4. 除非你的部署计划要求使用其他 namespace，否则保留默认 namespace npu-operator。本指南中的命令使用默认值；如果你选择其他 namespace，请将其中的 npu-operator 替换为所选值。使用 Operator namespace 的 Driver、Runtime、HCCN Bootstrap、Rebooter 和 NPU Feature Discovery 资源都会遵循该选择。
5. 在生产环境中选择 Manual 升级策略。
6. 等待 operator subscription 成功且 controller pods 运行起来。

#6. 创建 NPUOperatorCtl 实例

1. 打开 Installed Operators > Alauda Build of NPU Operator。
2. 打开 NPUOperatorCtl 选项卡。
3. 单击 Create NPUOperatorCtl。
4. 配置应由 operator 管理的组件。

常见组件开关：

对于可选的 Ascend Operator、NodeD、ClusterD、Resilience Controller、MindIO TFT 和 MindIO ACP 组件，仅在工作负载或运维计划需要时启用它们。MindIO TFT 和 MindIO ACP 使用随包提供的 npu-node-provision 镜像链路；仅在离线或受控网络环境中才需要准备节点侧 SDK zip 文件。

#7. 验证节点放置标签

创建 spec.npu-feature-discovery.enabled=true 的 NPUOperatorCtl 实例会部署 npu-feature-discovery DaemonSet。它会根据 Kubernetes node roles 和 NPU discovery 派生节点放置标签。某些托管组件需要这些标签，但当所选节点上的 discovery 成功运行时，你无需手动添加它们。

检查 discovery DaemonSet 及其维护的标签：

kubectl -n npu-operator get daemonset npu-feature-discovery
kubectl -n npu-operator get pods -l app=npu-feature-discovery -o wide
kubectl get nodes \
  -L node-role.kubernetes.io/control-plane,masterselector,workerselector,openfuyao.com/npu.present

预期结果：

• 具有 node-role.kubernetes.io/control-plane 的节点在 NPU Feature Discovery 运行后会拥有 masterselector=dls-master-node。
• 非 control-plane 节点会拥有 workerselector=dls-worker-node。
• 同时承载 NPU 的 control-plane 节点在 NPU discovery 识别到该设备后，可以同时拥有这两个放置标签。

如果缺少必需的放置标签，首先确认 npu-feature-discovery Pod 能在该节点上运行，并且 control-plane 节点具有标准的 node-role.kubernetes.io/control-plane 标签。随包提供的 DaemonSet 不容忍标准 control-plane 的 NoSchedule taint，并且它不会仅将旧的 node-role.kubernetes.io/master 角色标签识别为 control-plane。任一条件都可能阻止自动 master 标记。

如果该节点是 control-plane 节点但只有旧的角色标签，请添加标准角色标签并让 NPU Feature Discovery 协调这些放置标签：

kubectl label node <control-plane-node-id> node-role.kubernetes.io/control-plane= --overwrite

仅当自动发现无法覆盖所选节点时，才将匹配的放置标签作为回退手动添加：

kubectl label node <control-plane-node-id> masterselector=dls-master-node --overwrite
kubectl label node <npu-worker-node-id> workerselector=dls-worker-node --overwrite

仅将这些标签应用到对应组件预期使用的节点上。在 NPU Feature Discovery 运行期间，它会持续协调这些标签，并可能替换或删除与检测到的节点角色不匹配的值。特别是，当 discovery 正在运行且节点仅有旧的 master label 时，手动设置的 masterselector 并不持久；应改为添加标准 control-plane role label。

#下一步

创建实例后，请继续阅读 Verification。