切换 Ascend Device Plugin 所有者

当需要在由 NPU Operator 管理的直接分配与 HAMi 管理的分配之间切换 Ascend 设备暴露方式时,请使用此操作步骤。该切换会更改由哪个 Device Plugin 注册并分配物理设备;它不会替换由 NPU Operator 提供的 Ascend Driver、OCI Runtime、ascend RuntimeClass 或可选的 NPU Exporter。

WARNING

请在维护窗口内执行此操作步骤。在更改 Device Plugin 之前,停止或迁移受影响所有权范围内的所有 Ascend 工作负载。即使某个 Device Plugin 退出,现有 Pod 仍可能保留旧分配,而重新启动的 Pod 无法安全复用该状态。

NPUOperatorCtl.spec.devicePlugin.enabled 设置控制由该 NPU Operator 实例选定节点上的原生 Ascend Device Plugin。请将此切换视为应用于完整所有权范围。除非已安装产品明确提供互不重叠的 Device Plugin 部署位置,否则不要在同一范围内同时混用 direct 和 HAMi 所有者。

开始之前

  • 使用 选择 HAMi 部署场景 确认工作负载需要由 HAMi 管理的分配方式。

  • 安装 Alauda Build of NPU Operator,并通过 Ascend NPU 厂商基础文档 验证 Driver、OCI Runtime 和 ascend RuntimeClass。

  • 安装 Alauda Build of HAMi 核心插件,并启用其 Ascend 调度集成。

  • 获取集群管理员访问权限,并识别 NPUOperatorCtl 的名称和 namespace。

  • 在切换之前记录当前的 custom resources 和节点可分配资源。

    kubectl get npuoperatorctl -A
    kubectl get hamiascenddeviceplugin.hami.io -A
    kubectl get daemonset -A -o wide \
      | grep -E 'ascend-device-plugin|hami-ascend-device-plugin'
    kubectl get node <ascend-node> -o jsonpath='{.status.allocatable}'

将当前所有者配置保存在安全的工作目录中,以便在切换失败时恢复:

kubectl -n <npu-operator-namespace> get npuoperatorctl <instance-name> -o yaml \
  > npuoperatorctl-before-owner-switch.yaml
kubectl -n <hami-namespace> get hamiascenddeviceplugin.hami.io \
  hami-ascend-device-plugin -o yaml --ignore-not-found \
  > hami-ascend-device-plugin-before-owner-switch.yaml

从 direct allocation 切换到 HAMi

1. 停止 Ascend 工作负载

停止、迁移或缩减受影响所有权范围内使用 Ascend 资源的每个工作负载。确认没有剩余 Pod 正在使用正在切换节点上的 NPU。

更改 Device Plugin 不会迁移正在运行的 Pod。只有在新的所有者处于 Ready 状态且节点再次报告其资源后,才能重新创建代表性工作负载。

2. 禁用 NPU Operator 原生 Device Plugin

更新面向用户的 NPUOperatorCtl 资源。保持 Driver、OCI Runtime、ascend RuntimeClass 和其他必需组件处于启用状态。

spec:
  devicePlugin:
    enabled: false

对于现有实例,应用等效的 merge patch:

kubectl -n <npu-operator-namespace> patch npuoperatorctl <instance-name> \
  --type merge \
  -p '{"spec":{"devicePlugin":{"enabled":false}}}'

不要编辑生成的 NPUClusterPolicy,不要缩放原生 DaemonSet,也不要只删除其 Pod。NPU Operator 拥有这些资源,并且可以恢复手动更改。

3. 验证原生所有者已停止

分别验证期望设置、生成的 policy 以及最终的工作负载:

kubectl -n <npu-operator-namespace> get npuoperatorctl <instance-name> \
  -o jsonpath='{.spec.devicePlugin.enabled}{"\n"}'
kubectl get npuclusterpolicy
kubectl get npuclusterpolicy cluster \
  -o jsonpath='{.spec.devicePlugin.managed}{"\n"}'
kubectl -n kube-system get daemonset ascend-device-plugin --ignore-not-found
kubectl get pods -A -o wide \
  | grep -E 'ascend-device-plugin|hami-ascend-device-plugin'

NPU Operator policy 名称为 cluster。仅当这两个配置值都为 false,且受影响范围内没有原生 ascend-device-plugin Pod 运行时,才可继续。DaemonSet 命令在 reconciliation 之后返回空结果是预期行为。

如果 NPUOperatorCtl 报告为 false,但生成的 policy 仍为 true,或者原生 DaemonSet 仍处于 Ready 状态,请停止切换。检查 NPU Operator custom-resource 状态和 controller 日志;如果 reconciliation 仍未收敛,请联系支持。不要在原生所有者仍处于活动状态时启动 HAMi Ascend Device Plugin。

4. 启动 HAMi Ascend Device Plugin

按照 安装 HAMi Ascend Device Plugin 安装 Operator Bundle,并创建或更新 HAMiAscendDevicePlugin 实例。确认其 node selector 正好覆盖预期的 Ascend 节点,并且 Driver host path 与 NPU Operator driver 模式匹配。

等待生成的 DaemonSet:

kubectl -n <hami-namespace> rollout status \
  daemonset/hami-ascend-device-plugin --timeout=5m
kubectl -n <hami-namespace> get daemonset hami-ascend-device-plugin -o wide
kubectl -n <hami-namespace> get pods -o wide \
  | grep hami-ascend-device-plugin

5. 验证新的所有者和资源

kubectl get daemonset -A -o wide \
  | grep -E 'ascend-device-plugin|hami-ascend-device-plugin'
kubectl get node <ascend-node> -o jsonpath='{.status.allocatable}'

对于受影响设备,应仅有 hami-ascend-device-plugin 处于 Ready。必须先确认节点报告由已安装包提供的、由 HAMi 管理的 Ascend 资源,然后才能重新创建工作负载。仅凭资源名称无法证明所有权,因为 direct 和 HAMi 路径可以使用相同的 huawei.com/Ascend* 命名空间。

运行 HAMi on Ascend NPU 或 HAMi on Ascend vNPU 中的一个工作负载。确认它进入 Running,使用 runtimeClassName: ascend,并且可以执行 npu-smi info 以及设备内存或推理检查。

从 HAMi 切换回 direct allocation

此操作步骤会将整个 NPU Operator Device Plugin 范围恢复为 direct allocation。

  1. 停止或迁移受影响范围内所有由 HAMi 管理的 Ascend 工作负载。

  2. 通过其所属 API 保存并删除 HAMiAscendDevicePlugin 实例:

    kubectl -n <hami-namespace> get hamiascenddeviceplugin.hami.io \
      hami-ascend-device-plugin -o yaml \
      > hami-ascend-device-plugin-before-direct-switch.yaml
    kubectl -n <hami-namespace> delete hamiascenddeviceplugin.hami.io \
      hami-ascend-device-plugin
  3. 等待 hami-ascend-device-plugin 从受影响节点中消失。在 HAMi Device Plugin Pod 仍暴露相同设备时,不要启用原生所有者。

  4. 通过 NPUOperatorCtl 恢复原生所有者:

    kubectl -n <npu-operator-namespace> patch npuoperatorctl <instance-name> \
      --type merge \
      -p '{"spec":{"devicePlugin":{"enabled":true}}}'
  5. 验证 NPUOperatorCtl.spec.devicePlugin.enabled 和 NPUClusterPolicy.spec.devicePlugin.managed 都为 true,原生 ascend-device-plugin DaemonSet 处于 Ready,并且节点报告 direct-allocation 资源。

  6. 按照 直接请求 Ascend NPU 资源 重新创建 direct-allocation 工作负载。

仅当另一个受支持的 HAMi Ascend 范围仍在使用时,才保留安装 Alauda Build of HAMi Ascend Device Plugin。否则,在 direct 路径通过验证后,按照 卸载 HAMi 组件 删除未使用的 Operator Bundle。

停止和回滚条件

当出现以下任一情况时,请停止更改并返回到上一个单一所有者状态:

  • 旧的 Device Plugin 未离开受影响节点;
  • 新的 Device Plugin DaemonSet 未变为 Ready;
  • 节点可分配资源未收敛到预期的软件包契约;
  • 代表性工作负载无法启动或无法访问已分配的 NPU。

在恢复之前的所有者之前,请通过其所属 custom resource 移除或停止新的所有者。切勿将两个所有者同时运行作为回滚捷径。