Get Started with NPU Operator

Use this page when you want to install the Ascend NPU base and run a workload. It gives you the shortest supported path; detailed driver, runtime, and troubleshooting procedures remain in the linked pages.

1. Install NPU Operator

Start with Install NPU Operator. You need administrator access to the target workload cluster and the Node Feature Discovery component used by the cluster.

2. Choose how the driver is managed

Choose one driver scenario before creating the NPUOperatorCtl resource:

ScenarioWhat you need to provideUse when
Operator-managed physical hostA physical OS that can run the delivered driver installerThe host is mutable and the Operator should manage the host driver
Operator-managed immutable OSA matching precompiled Driver imageThe node uses an immutable OS or Alauda OS
Driver managed outside NPU OperatorA healthy Host Driver already installed on every selected nodeAnother system owns driver installation and upgrades

Use Driver and runtime prerequisites for the exact settings. For immutable OS, the Operator stages the Driver tree under /run/ascend/driver and the runtime uses that tree when preparing workloads.

3. Use the default NPU Operator configuration

The default direct-allocation path is designed for a workload that requests an NPU and starts running without adding driver paths or runtime details to its manifest:

  • Ascend Device Plugin is enabled;
  • Ascend runtime integration is enabled;
  • the ascend RuntimeClass is available;
  • the admission webhook adds runtimeClassName: ascend when a Pod requests an Ascend resource;
  • Volcano is disabled by default;
  • the workload image provides CANN and the application framework.

Do not add runtimeClassName, ASCEND_VISIBLE_DEVICES, or a driver hostPath to a normal direct-allocation manifest when the webhook and runtime integration are enabled.

4. Request one whole NPU

First check the resource key reported by the node:

kubectl get node <node-name> -o jsonpath='{.status.allocatable}{"\n"}'

Then request the exact key reported by the node. A common 310P example is:

resources:
  limits:
    huawei.com/Ascend310P: "1"

See Request NPU resources for the complete manifest. This is whole-card allocation. Use HAMi when you need HAMi scheduling, sharing, or slicing.

5. Verify that the workload is usable

After the Pod is admitted, check that:

  1. the Pod has runtimeClassName: ascend;
  2. the node device is visible and the runtime has prepared the Driver files;
  3. an ACL probe can initialize the device, allocate and free memory, reset the device, and finalize successfully;
  4. a small application operation runs on the NPU and returns the expected result;
  5. deleting the Pod releases the device for another workload.

Pod Running, a device node, or npu-smi info alone proves device access only. Follow Verify the installation for the complete check and Troubleshooting when a check fails.

6. Decide whether to use HAMi

Keep the direct NPU Operator path when workloads need exclusive whole-card access and do not need HAMi scheduling or sharing.

Use HAMi when workloads need HAMi scheduling, whole-card resource management, hard slicing, or soft slicing. Before installing the HAMi Ascend Device Plugin:

  • keep the NPU Operator Driver, runtime, and ascend RuntimeClass;
  • switch the Device Plugin owner so only one Device Plugin exposes the target devices;
  • choose one RuntimeClass injector. The NPU Operator webhook can inject ascend; HAMi can inject it only when its Ascend device configuration explicitly sets runtimeClassName: ascend. A default HAMi installation leaves that value empty. Do not rely on both injectors for the same workload;
  • verify the selected owner with a real ACL and application check.

Continue with HAMi on Ascend for HAMi installation, owner switching, whole-card allocation, and slicing.