# 墨芯 Kubernetes 设备插件使用说明

## 概述

墨芯提供了 Kubernetes 设备插件 moffett-device-plugin，通过该插件，您可以实现以下功能：

- 自动将集群中每个节点上的墨芯 AI 加速卡设备数量暴露给 Kubernetes，实现设备资源的透明化管理和动态调度。
- 实时监控墨芯 AI 加速卡设备的健康状态，确保设备稳定运行，及时发现并处理潜在问题。
- 允许在 Kubernetes 集群中无缝运行依赖墨芯 AI 加速卡的容器，提升容器化应用的性能与效率。

部署 moffett-device-plugin 后，在创建 Pod 时 Kubernetes 集群会自动申请使用设备，并跟踪墨芯设备的健康状况。

## 前提条件

- 已安装墨芯 AI 计算卡，且能被系统正确识别。

- 在宿主机上安装 SOLA ToolKit，且安装的 SOLA ToolKit 的版本>= 3.5.0。

- 已安装 Kubernetes，且 Kubernetes 的版本不低于 Kubernetes V1.10。如需查看Kubernetes版本，可执行如下命令：

   ```Bash
    $ kubectl version 
   ```

## 部署设备插件

下文示例使用 SOLA ToolKit 3.9.1 和 Docker（≥18.09）的环境进行演示。您可以在自己的环境中部署好 Kubernetes 集群，并根据需要选择容器引擎 （Container Engine） 和 SOLA ToolKit。

### 步骤一：获取 device plugin 镜像

 plugin 镜像分为在线版和离线版，获取方式如下：

- 获取在线版本 device plugin 镜像：

  ```Bash
  $ docker pull moffett/k8s-device-plugin:v0.2.0
  $ docker images | grep k8s-device-plugin
  ```

- 获取离线版本 device plugin 镜像：

  ```Bash
  $ wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/CloudNative/moffett-k8s-device-plugin-v0.2.0.tar
  $ docker load -i moffett-k8s-device-plugin-v0.2.0.tar
  $ docker images | grep k8s-device-plugin
  ```

### 步骤二：创建用于启动 plugin 的 YAML 配置文件

- 创建名为 moffett-device-plugin 的 YAML 文件，用于启动 plugin，内容示例如下：

   **注意**：

    - *plugin 目前需要以特权模式运行。*
    - *对墨芯 AI 加速卡的修改操作，例如 reboot，请直接在宿主机上执行，并在完成后重启 plugin。*
   - *plugin 及 SOLA 容器运行过程中，卸载或升级宿主机上的 SOLA ToolKit 会失败，请删除或暂停相关容器后再对宿主机的 SOLA 环境进行变更。*
   
  ```Bash
  #moffett-device-plugin.yml 
  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
        # Mark this pod as a critical add-on; when enabled, the critical add-on
        # scheduler reserves resources for critical add-on pods so that they can
        # be rescheduled after a failure.
        # See https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/
        priorityClassName: "system-node-critical"
        containers:
        - image: moffett/k8s-device-plugin:v0.2.0
          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
  ```

### 步骤三：部署 device plugin 

执行以下命令，启动 plugin。

```Bash
$ kubectl create -f moffett-device-plugin.yml 
```

### 步骤四：查看 plugin 是否部署成功

执行以下命令，查看 plugin 是否启动成功 。

```Bash
# plugin 状态为 running 表示启动成功
$ kubectl get pods -l name=moffett-device-plugin-ds -n kube-system
NAME                                    READY   STATUS    RESTARTS   AGE
moffett-device-plugin-daemonset-qthvk   1/1     Running   0          25s
```

## 创建 Pod 使用 moffett.ai/spu 设备

### 步骤一：获取 SOLA 基础镜像

**注意**：*镜像的 SOLA 版本需和宿主机上安装的 SOLA 版本对应。*

```Bash
$ wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/images/macs/macs-base-sola-3.9.1.tar
$ docker load -i macs-base-sola-3.9.1.tar
$ docker images |grep macs 
```

更多获取方式请参见 [MACS 容器化示例](https://docs.moffettai.com/moffett_docs/macs-1.5.1/AI-Native/macs-docker.html)。

### 步骤二：创建用于启动 Pod 的 YAML 配置文件

创建名为 moffett-qual-list 的 YAML 文件，用于启动 qual-list-pod。该 Pod 启动后会自动执行 `mx-qual list` 命令。内容示例如下：

**注意**：

- *对于 v0.2.0 plugin，使用 moffett.ai/spu 设备的 Pod 不推荐使用特权模式 （privileged），以更好地控制容器中的设备可见性。若必须使用特权模式，请确保 Pod 指定的 moffett.ai/spu 设备资源于宿主机上的数量一致，保证设备可见性在 kubelet 控制下，避免预期外的设备节点访问问题。*
- *如果您需要在宿主机中获取正在运行的程序的 PID 和进程名，请在配置文件 spec 中添加配置 `hostPID: true`。*

```Bash
#moffett-qual-list.yml 
apiVersion: v1
kind: Pod
metadata:
  name: qual-list-pod
spec:
  restartPolicy: Never
  containers:
  - name: sola-container
    image:  moffett/macs-base:sola-3.9.1
    args: ['mx-qual', 'list'] #pod里面自动运行的命令，可以根据需要替换
    resources:
      limits:
        moffett.ai/spu: 2 #指定2个device
  tolerations:
  - key: moffett.ai/spu
    operator: Exists
    effect: NoSchedule
# 这个 pod 需要两个 moffett.ai/spu 设备
# 而且只能够调度到满足需求的节点上
# 如果该节点中有 2 个以上的设备可用，其余的可供其他 Pod 使用
```

### 步骤三：将Pod部署到Kubernetes集群中

执行以下命令，启动 qual-list-pod。

```Bash
$ kubectl create -f moffett-qual-list.yml 
```

### 步骤四：查看 Pod 是否部署成功

执行以下命令，查看 qual-list-pod 是否启动成功 。

```Bash
# qual-list-pod 状态为 completed 表示任务已执行完毕
$ kubectl get pod qual-list-pod
NAME            READY   STATUS      RESTARTS   AGE
qual-list-pod   0/1     Completed   0          6s
```

### 步骤五：查看执行日志

Pod 部署成功后，您可以执行以下命令，查看 qual-list-pod 的执行日志。

```bash
$ kubectl logs qual-list-pod
Device 0: "00S30-00A"
  Serial number:      2024223080134
  PCI Bus ID:         0000:16:00.0
  Runtime version:    3.9.0
  Driver version:     3.9.1
  Firmware version:   1.0.15

Device 1: "00S30-00A"
  Serial number:      2024193080076
  PCI Bus ID:         0000:2e:00.0
  Runtime version:    3.9.0
  Driver version:     3.9.1
  Firmware version:   1.0.15
```

## 清理环境

### 删除 Pod

```Bash
#请以您实际的pod名为准，本文示例的pod名为qual-list-pod
$ kubectl delete pod qual-list-pod
```

### 删除 device plugin

```Bash
# moffett-device-plugin-daemonset 和 kube-system 分别为 metadata 字段下的 name 和 namespace 字段的值
$ kubectl delete daemonset moffett-device-plugin-daemonset -n kube-system
```