# MOFFETT Device Plugin 用户手册

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

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

## 前提条件

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

## 部署

1. 选择以下任意一种方式获取镜像：

   - 在线拉取

        ```Bash
        docker pull moffett/k8s-device-plugin:v0.3.0
        ```

   - 离线导入

        ```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. 验证 MOFFETT Device Plugin 是否部署成功。

   - 查看部署的 DaemonSet。

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

   - 查看 DaemonSet 的 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
    ```

## 卸载

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

    ```Bash
    kubectl get pods -A -o json | grep "moffett.ai/spu"
    ```
2. 选择以下任意一种方式卸载：

   - 通过资源名称卸载

      ```Bash
      kubectl delete daemonset moffett-device-plugin-daemonset -n kube-system
      ```
   - 通过部署文件卸载

      ```Bash
      kubectl delete -f moffett-device-plugin.yml
      kubectl get daemonset -n kube-system | grep moffett
      ```
```{admonition} 须知
:class: note

如需更新主机的 SOLA ToolKit 版本, 请先为设备节点打 Taint/label 或卸载 `moffett-device-plugin`，避免设备占用导致 SOLA ToolKit 更新失败，具体请参见[常见问题](../faq.md)。
```