Prepare Driver Images and ImageWhiteList

Use this page only when the selected installation scenario requires detailed Driver image import or ImageWhiteList preparation. Most users can start from Install NPU Operator, choose a scenario, and return here only when the scenario asks for these steps.

Select the matching precompiled Driver image

For the immutable OS scenario, import the ARM64 Driver image that matches the complete (HDK, chip, kernel, OS) profile. NPU Operator derives the tag from the HDK version, detected chip, and complete kernel release after removing the architecture suffix:

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

For published openEuler tags, the legacy .oe separator in the kernel release becomes -oe. Do not add an OS suffix that is not present in the detected kernel release.

Example profiles:

Operating systemHardwareExact host kernelExample Driver image
CTyunOS-based Alauda OSAscend 310P6.6.0-0008.ctl4.aarch64alaudadockerhub/ascend-driver:25.5.0-310p-6.6.0-0008.ctl4
openEuler 24.03 LTS SP3Ascend 910B6.6.0-145.0.4.135.oe2403sp3.aarch64alaudadockerhub/ascend-driver:25.5.0-910b-6.6.0-145.0.4.135-oe2403sp3

Verify the source image architecture and mirror it to the target workload cluster registry:

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

If no published tag matches the node kernel, record uname -r and the chip model before contacting support.

Configure ImageWhiteList

If the target cluster enforces image whitelist policies, allow the exact Driver image reference rendered by NPU Operator and rewrite it to the image imported into the workload registry.

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

Apply the whitelist in the target workload cluster, preserve unrelated entries, and use one exact rule per supported Driver tag.

After creating the NPUOperatorCtl, verify the rendered reference and the image actually running:

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

The admitted image and its imageID must match the intended imported Driver artifact.

Physical host and external Driver scenarios

For an operator-managed physical host, use the delivered Driver installer and installMode: host, usePrecompiled: false. For an external Driver scenario, skip Driver image preparation and confirm that /usr/local/Ascend/driver is already healthy on every selected NPU node.