# MOFFETT Device Plugin 用户手册

MOFFETT Device Plugin 是基于 Kubernetes 的 DaemonSet，用于在 Kubernetes 集群中识别并启用墨芯计算卡。通过该工具，可实现以下功能：

- 在集群中注册每个节点的墨芯设备数量。
- 实时监控墨芯设备的健康状态。
- 在集群中运行支持墨芯设备的容器。

```{admonition} 须知
:class: note

Device Plugin 可单独部署或通过 SPU Operator 统一部署，任选一种方式以避免冲突。通过 SPU Operator 部署的详细操作，请参见 [MOFFETT SPU Operator 用户手册](./k8s-spu-operator.md)。
```

## 部署 Device Plugin

### 前提条件

- 安装 MOFFETT Container Toolkit，具体请参见 [MOFFETT Container Toolkit 用户手册](./mct.md)。
- 部署 Kubernetes 集群且版本 ≥ 1.10；如启用 CDI 特性，Kubernetes 版本需 ≥ 1.28。
- 安装容器运行时（如 Docker、containerd 等）；如启用 CDI 特性，容器运行时需支持 CDI（如：containerd 版本 ≥ v1.7.0）。

### 操作步骤

1. 获取 Device Plugin 容器镜像。

   ````{tabs}

   ```{tab} 在线拉取
   ```Bash
   docker pull moffett/k8s-device-plugin:v0.3.0
   ```

   ```{tab} 离线导入
   ```Bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/CloudNative/k8s-device-plugin/moffett-k8s-device-plugin-v0.3.0.tar
   docker load -i moffett-k8s-device-plugin-v0.3.0.tar
   ```
   ````

2. 在设备节点创建 DaemonSet。

    ```Bash
    wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/CloudNative/k8s-device-plugin/moffett-device-plugin.yml
    kubectl create -f moffett-device-plugin.yml
    ```

3. 验证 Device Plugin 是否部署成功。

   - 查看部署的 Device Plugin 信息。

     ```Bash
     kubectl get daemonset -n kube-system | grep plugin
     ```

   - 查看 Device Plugin 的 Pod 所在节点。

     ```Bash
     kubectl get pods -A -o wide -l name=moffett-device-plugin-ds
     ```

   - 查看 Pod 的运行日志。

     ```Bash
     kubectl logs moffett-device-plugin-daemonset-<hash> -n kube-system # 将<hash>替换成实际的 Pod 名称后缀哈希值
     ```

     如果命令回显：Registered device plugin for 'moffett.ai/spu' with Kubelet，表示 `moffett-device-plugin` 部署成功。

   - 查看设备节点的状态及资源情况。

     ```Bash
     kubectl describe node <node_name> | grep Capacity -A7  # 将<node_name>替换成实际的节点名称
     ```

## 运行示例

1. 创建 `mx-qual` 的 Pod，Pod 启动后自动执行 `mx-qual list` 命令。

   ```Bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/CloudNative/k8s-device-plugin/moffett-qual-list.yml
   kubectl create -f moffett-qual-list.yml 
   ```

2. 查看 Pod 状态。

   ```Bash
   kubectl get pod qual-list-pod
   ```

   如果 `STATUS` 为 `Completed`，表示任务已执行完成。

3. 查看 Pod 日志。

   ```bash
   kubectl logs qual-list-pod
   ```

4. 删除 Pod。

   ```Bash
   kubectl delete pod qual-list-pod
   ```

## 停用 Device Plugin

当更新 SOLA Toolkit 时，Device Plugin 服务会影响 SOLA Toolkit 卸载，需通过以下步骤在指定节点停用 Device Plugin：

1. 查询集群中部署的 Device Plugin 所有 Pod 的详细信息。

   ```
   kubectl get pods -l name=moffett-device-plugin-ds -n kube-system -o wide
   ```

2. 为集群的指定节点添加污点（Taint）并删除该节点上 Device Plugin 相关 Pod。

   ```
   kubectl taint nodes <node_name> NeedFix=true:NoSchedule                                                        # 为指定节点添加 Taint，标记为不可调度
   kubectl describe node <node_name> | grep Taints                                                                # 验证节点 Taint 是否生效
   kubectl delete pod -l name=moffett-device-plugin-ds -n kube-system --field-selector spec.nodeName=<node_name>  # 删除指定节点上的特定 Pod
   kubectl get pod -n kube-system -o wide                                                                         # 验证 Pod 状态
   ```

   如需 Kubernetes 重新调度 Device Plugin 的 Pod，移除 Taint。
       
   ```
   kubectl taint nodes <node_name> NeedFix=true:NoSchedule-
   ```

## 卸载 Device Plugin

1. 确认无运行中的 Pod 使用墨芯设备资源。

   ```Bash
   kubectl get pods -A -o json | grep "moffett.ai/spu"
   ```

2. 选择以下任意一种方式卸载。

   ````{tabs}

   ```{tab} 通过资源名称卸载
   ```Bash
   kubectl delete daemonset moffett-device-plugin-daemonset -n kube-system
   ```

   ```{tab} 通过部署文件卸载
   ```Bash
   kubectl delete -f moffett-device-plugin.yml
   kubectl get daemonset -n kube-system | grep moffett
   ```
   ````