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

概述

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

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

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

前提条件

已安装墨芯 AI 计算卡，且能被系统正确识别。
在宿主机上安装 SOLA ToolKit，且安装的 SOLA ToolKit 的版本>= 3.11.0。
已安装 Kubernetes，且 Kubernetes 的版本不低于 Kubernetes V1.10。如需查看Kubernetes版本，可执行如下命令：
```
 $ kubectl version 
```

部署设备插件

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

步骤一：获取 device plugin 镜像

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

获取在线版本 device plugin 镜像：

$ docker pull moffett/k8s-device-plugin:v0.3.0
$ docker images | grep k8s-device-plugin

获取离线版本 device plugin 镜像：

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

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

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

注意：

plugin 目前需要以特权模式运行。
对墨芯 AI 加速卡的修改操作，例如 reboot，请直接在宿主机上执行，并在完成后重启 plugin。
plugin 及 SOLA 容器运行过程中，卸载或升级宿主机上的 SOLA ToolKit 会失败，请删除或暂停相关容器后再对宿主机的 SOLA 环境进行变更。

#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.3.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。

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

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

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

# 设备插件本质上是一个 DaemonSet，运行 kubectl get daemonset 命令查看其是否启动成功
$ kubectl get daemonset -n kube-system
# plugin pod 状态为 running 表示启动成功

$ kubectl get pods -l name=moffett-device-plugin-ds -n kube-system
NAME                                    READY   STATUS    RESTARTS   AGE
moffett-device-plugin-daemonset-***   1/1     Running   0          25s
# 日志中输出" Registered device plugin for 'moffett.ai/spu' with Kubelet " 表示 moffett 设备插件已经安装成功。

$ kubectl logs moffett-device-plugin-daemonset-*** -n kube-system

# 查看设备节点算力资源情况
$ kubectl describe node idc-node-100 |grep Capacity -A7
Capacity:
moffett.ai/spu:     24

Allocatable:
moffett.ai/spu:     24
Allocated resources:
moffett.ai/spu     0

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

注意：当 plugin version ≥ 0.3.0 时，已支持 kubernetes 使用完全限定的 CDI 设备名来申请 pod 所需的 spu 设备资源。如需启用此功能，您需预先安装 Moffett Container Toolkit，并确保 Kubernetes 的容器引擎已配置为支持 CDI 特性。同时，请使用 Kubernetes 1.28 及以上版本，并参见 DevicePluginCDIDevices 开启门控特性。**

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

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

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

更多获取方式请参见 MACS 容器化示例。

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

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

注意：

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

#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.11.0
    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。

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

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

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

# 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 的执行日志。

$ kubectl logs qual-list-pod
Device 0: "00S30-00A"
  Serial number:      2024223080134
  PCI Bus ID:         0000:16:00.0
  Runtime version:    3.11.0
  Driver version:     3.11.0
  Firmware version:   1.0.17

Device 1: "00S30-00A"
  Serial number:      2024193080076
  PCI Bus ID:         0000:2e:00.0
  Runtime version:    3.11.0
  Driver version:     3.11.0
  Firmware version:   1.0.17

清理环境

删除 Pod

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

删除 device plugin

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