Install NPU Operator

Use this page to install the NPU Operator and create the NPUOperatorCtl resource. Choose one scenario, prepare only its prerequisites, apply the matching CR, and then verify the resulting NPU stack.

Installation path

Follow the steps in order:

  1. Read Prerequisites and choose a Driver scenario.
  2. Upload the NPU Operator package and required shared packages.
  3. Install Node Feature Discovery and NPU Operator.
  4. Apply the minimum CR for the selected scenario below.
  5. Continue with Verify the installation.

1. Upload and install packages

Upload Alauda Build of NPU Operator from Customer Portal. Install Alauda Build of Node Feature Discovery on the target workload cluster before creating the NPUOperatorCtl resource. Install Volcano only when you have a separate plan to enable ClusterD.

For package upload, use Upload Packages. For NFD installation, use the shared NFD documentation.

Install the NPU Operator from Administrator > Marketplace > OperatorHub, switch to the target workload cluster, and wait for its Subscription and CSV to become ready. Installing the Operator starts the controller; it does not yet deploy the Driver, runtime, or Device Plugin.

2. Choose a scenario and create the CR

The examples below use only fields supported by the Alauda v26.6.0 CRD. They use the automatic runtime path: Device Plugin enabled, Ascend runtime enabled, ascend RuntimeClass, and webhook enabled. The workload image still provides CANN and the application framework.

Operator-managed physical host

Use this when the physical OS can run the delivered Host Driver installer. Prepare the host according to Prerequisites, then apply:

apiVersion: npu-operator.alauda.io/v1
kind: NPUOperatorCtl
metadata:
  name: npuoperatorctl
spec:
  npu-feature-discovery:
    enabled: true
  driver:
    enabled: true
    installMode: host
    usePrecompiled: false
  devicePlugin:
    enabled: true
    env:
      - name: ASCEND_DOCKER_RUNTIME
        value: "True"
  ociRuntime:
    enabled: true
  operator:
    runtimeClass: ascend
  webhook:
    enabled: true

Operator-managed immutable OS

Use this when the node uses an immutable OS and a matching precompiled Driver image. Complete Driver image preparation before applying:

apiVersion: npu-operator.alauda.io/v1
kind: NPUOperatorCtl
metadata:
  name: npuoperatorctl
spec:
  npu-feature-discovery:
    enabled: true
  driver:
    enabled: true
    installMode: containerized
    usePrecompiled: true
    driverInstallDir: /run/ascend/driver
  devicePlugin:
    enabled: true
    env:
      - name: ASCEND_DOCKER_RUNTIME
        value: "True"
  ociRuntime:
    enabled: true
  operator:
    runtimeClass: ascend
  webhook:
    enabled: true

Driver managed outside NPU Operator

Use this when another system installs and upgrades a healthy Host Driver on every selected node:

apiVersion: npu-operator.alauda.io/v1
kind: NPUOperatorCtl
metadata:
  name: npuoperatorctl
spec:
  npu-feature-discovery:
    enabled: true
  driver:
    enabled: false
    installMode: host
    usePrecompiled: false
  devicePlugin:
    enabled: true
    env:
      - name: ASCEND_DOCKER_RUNTIME
        value: "True"
  ociRuntime:
    enabled: true
  operator:
    runtimeClass: ascend
  webhook:
    enabled: true

Apply the selected file:

kubectl apply -f npuoperatorctl.yaml
kubectl get npuoperatorctl -A

Do not switch an existing installation between host and containerized by editing only driver.installMode. Follow Driver mode change is refused for an approved migration.

NPU Operator with HAMi

Keep the Driver, OCI Runtime, ascend RuntimeClass, and webhook enabled. After the NPU Operator base is ready, disable the NPU Operator Device Plugin for the complete ownership scope and follow Choose an Ascend NPU Allocation Mode to install HAMi's Ascend Device Plugin. Use one RuntimeClass injector for each workload: the NPU Operator webhook is the recommended default; a default HAMi install does not inject ascend unless its Ascend device configuration explicitly sets it.

3. Verify the installation

Continue with Verify the installation. Do not accept the installation based only on Pod Running, a device node, or npu-smi info; complete the ACL and application checks on that page.