# MOFFETT Device Plugin 用户手册

MOFFETT Device Plugin 基于 Kubernetes 设备插件框架实现，用于将墨芯 SPU 设备资源注册到 Kubelet。该组件以 DaemonSet 的形式部署，可以在 Kubernetes 集群的各个节点注册墨芯 SPU 设备，跟踪 SPU 设备状态，并运行支持 SPU 设备的容器。

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

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

## 部署 Device Plugin

### 前提条件

- 安装 SOLA Toolkit，具体请参见 [SOLA Toolkit 安装指南](../installation/sola-toolkit-installation-guide.md)。
- 部署可用的 Kubernetes 集群 ≥ 1.10，具体请参见 <a href="https://kubernetes.io/zh-cn/docs/setup/production-environment/tools/" target="_blank">使用部署工具安装 Kubernetes</a>。如需使用 CDI 功能，Kubernetes 集群 ≥ 1.28。
- 安装 Kubernetes 命令行工具 `kubectl`，具体请参见 <a href="https://kubernetes.io/zh-cn/docs/tasks/tools/#kubectl" target="_blank">安装工具 - kubectl</a>。
- 安装容器运行时，具体请参见<a href="https://kubernetes.io/zh-cn/docs/setup/production-environment/container-runtimes/" target="_blank">容器运行时</a>。

### 操作步骤

1. 选择以下任一方式获取 Device Plugin 容器镜像。

   - 在线拉取

      ````{tabs}

      ```{tab} S4/S30/S40/S40AC
      ```bash
      docker pull moffett/k8s-device-plugin:v0.3.0
      ```

      ```{tab} S40Lite
      ```bash
      docker pull moffett/k8s-device-plugin:v0.3.0-lite
      ```
      
      ````

   - 离线导入

      ````{tabs}

      ```{tab} S4/S30/S40/S40AC
      ```bash
      wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.11/device-plugin/moffett-k8s-device-plugin-v0.3.0.tar
      docker load -i moffett-k8s-device-plugin-v0.3.0.tar
      ```

      ```{tab} S40Lite
      ```bash
      wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.11/device-plugin/moffett-k8s-device-plugin_v0.3.0-lite.tar
      docker load -i moffett-k8s-device-plugin-v0.3.0-lite.tar
      ```
      ````

2. 创建 `moffett-device-plugin.yaml` 部署文件。

   ```{admonition} 须知
   :class: note
   以下配置适用于 S4/S30/S40/S40AC 计算卡。使用 S40Lite 计算卡时，请使用容器镜像 `moffett/k8s-device-plugin:v0.3.0-lite`。
   ```

   ```yaml
   apiVersion: apps/v1
   kind: DaemonSet
   metadata:
   name: moffett-device-plugin-daemonset
   namespace: kube-system
   spec:
   selector:
      matchLabels:
         name: moffett-device-plugin-ds
   updateStrategy:
      type: RollingUpdate
   template:
      metadata:
         labels:
         name: moffett-device-plugin-ds
      spec:
         tolerations:
         - key: moffett.ai/spu
         operator: Exists
         effect: NoSchedule
         priorityClassName: "system-node-critical"
         containers:
         - image: moffett/k8s-device-plugin:v0.3.0 # 使用 S40Lite 计算卡时，请使用：moffett/k8s-device-plugin:v0.3.0-lite
         name: moffett-device-plugin-ctr
         securityContext:
            privileged: true
         volumeMounts:
         - name: device-plugin
            mountPath: /var/lib/kubelet/device-plugins
         volumes:
         - name: device-plugin
         hostPath:
            path: /var/lib/kubelet/device-plugins
   ```

3. 部署 Device Plugin。

   ```bash
   kubectl create -f moffett-device-plugin.yml
   ```

4. 查看 Device Plugin 部署状态。

   ```bash
   kubectl get pod -n kube-system -l name=moffett-device-plugin-ds # STATUS = running（READY = 1/1）表示 Pod 正常启动
   ```

### 运行示例

以下示例基于 Docker 容器运行时。

1. 创建 Pod 配置文件 `mx-qual-list.yml`，定义请求 2 个 SPU 设备并执行 `mx-qual list` 命令的 Pod。

   ```yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: qual-list-pod
   spec:
     restartPolicy: Never
     containers:
     - name: sola-container
       image: moffett/macs-base:sola-3.12.0 # 自定义镜像，包含 SOLA Toolkit 3.12.0 版本
       args: ['mx-qual', 'list'] # 容器启动参数，即运行 mx-qual list 命令
       resources:
         requests:
           moffett.ai/spu: 2 # 申请使用 2 个 device
         limits:
           moffett.ai/spu: 2 # 限制最多使用 2 个 device
     tolerations:
     - key: moffett.ai/spu
       operator: Exists
       effect: NoSchedule
   ```

2. 创建并运行 Pod。

   ```bash
   kubectl create -f mx-qual-list.yml
   ```

3. 查看 Pod 状态。

   ```bash
   kubectl get pod qual-list-pod
   ```

   ```bash
   # STATUS = Completed 表示任务已完成
   NAME            READY   STATUS      RESTARTS   AGE
   qual-list-pod   0/1     Completed   0          11m
   ```

4. 查看 Pod 日志中 `mx-qual list` 命令运行的结果。

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

5. 删除 Pod。

   ```bash
   kubectl delete pod qual-list-pod
   ```

## 卸载 Device Plugin

````{tabs}

```{tab} 通过部署文件卸载
```bash
kubectl delete -f moffett-device-plugin.yml
```

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

````

## 更新 SOLA Toolkit 时停用节点上的 Device Plugin

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

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

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

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

   ```bash
   kubectl taint nodes <node_name> NeedFix=true:NoSchedule   # 为指定节点添加 Taint，标记为不可调度
   kubectl describe node <node_name> | grep Taints           # 验证节点 Taint 是否生效
   kubectl get pod -n kube-system -o wide                    # 查看指定节点上的 Pod 信息
   kubectl delete pod <pod_name> -n kube-system              # 删除指定节点上 Device Plugin 的 Pod
   ```

3. 当 SOLA Toolkit 更新完成后，如需 Kubernetes 重新调度 Device Plugin 的 Pod，移除 Taint。

   ```bash
   kubectl taint nodes <node_name> NeedFix=true:NoSchedule-
   ```