摩尔线程云原生套件 v2.0.0 安装指南

容器运行时套件

支持的平台

支持的 Linux 发行版

操作系统名称及版本	amd64 / x86_64	arm64 / aarch64
Ubuntu 20.04	Y	N/A
Kylin V10 SP1	N/A	Y
UnionTech OS Desktop 20 Pro	N/A	Y
Debian 12	Y	N/A

支持的容器运行时

容器运行时名称及版本	amd64 / x86_64	arm64 / aarch64
Docker 20.10	Y	Y
containerd 1.5	Y	Y

安装指南

先决条件

在开始之前，请确保已为您的 Linux 发行版安装了最新的摩尔线程显卡驱动。您可以通过以下命令来进行验证：

❯ mthreads-gmi
Fri May 16 10:41:32 2025
---------------------------------------------------------------
    mthreads-gmi:2.0.0           Driver Version:3.0.0
---------------------------------------------------------------
ID   Name           |PCIe                |%GPU  Mem
     Device Type    |Pcie Lane Width     |Temp  MPC Capable
                                         |      ECC Mode
+-------------------------------------------------------------+
0    MTT S80        |00000000:01:00.0    |0%    516MiB(16384MiB)
     Physical       |16x(16x)            |60C   YES
                                         |      N/A
---------------------------------------------------------------

---------------------------------------------------------------
Processes:
ID   PID       Process name                         GPU Memory
                                                         Usage
+-------------------------------------------------------------+
   No running processes found
---------------------------------------------------------------

安装 Docker CE

sudo apt install docker.io

更多安装信息请参考官方文档。

安装摩尔线程容器运行时套件

使用 dpkg 包管理工具进行安装：

sudo dpkg -i mtml_2.0.0.deb mt-container-toolkit_2.0.0.deb

绑定摩尔线程容器运行时到 Docker，设置默认的容器运行时为 mthreads 并重启 Docker daemon：

$ (cd /usr/bin/musa && sudo ./docker setup $PWD)

您可以通过如下命令验证上述步骤是否成功：

❯ docker run --rm --env MTHREADS_VISIBLE_DEVICES=all ubuntu:22.04 mthreads-gmi
Fri May 16 02:42:24 2025
---------------------------------------------------------------
    mthreads-gmi:2.0.0           Driver Version:3.0.0
---------------------------------------------------------------
ID   Name           |PCIe                |%GPU  Mem
     Device Type    |Pcie Lane Width     |Temp  MPC Capable
                                         |      ECC Mode
+-------------------------------------------------------------+
0    MTT S80        |00000000:01:00.0    |0%    516MiB(16384MiB)
     Physical       |16x(16x)            |60C   YES
                                         |      N/A
---------------------------------------------------------------

---------------------------------------------------------------
Processes:
ID   PID       Process name                         GPU Memory
                                                         Usage
+-------------------------------------------------------------+
   No running processes found
---------------------------------------------------------------

可以看到在容器内部已经能够获取到摩尔线程 GPU 设备。

卸载摩尔线程容器运行时套件

恢复 Docker 默认的容器运行时并重启 Docker daemon：

$ (cd /usr/bin/musa && sudo ./docker cleanup $PWD)

通过 dpkg 包管理工具卸载摩尔线程容器运行时套件：

$ sudo dpkg -r mt-container-toolkit mtml sgpu-dkms

# 完全卸载并清除配置文件
$ sudo dpkg -P mt-container-toolkit mtml sgpu-dkms

使用指南

摩尔线程容器运行时可以使用以下环境变量对容器中的 GPU 设备进行设置：

• MTHREADS_VISIBLE_DEVICES 设置挂载到容器中的摩尔线程 GPU 设备。
• MTHREADS_DRIVER_CAPABILITIES 设置容器中用户态驱动程序的能力。

GPU 枚举

通过设置 MTHREADS_VISIBLE_DEVICES 环境变量可以指定特定的 GPU 设备到容器中。

MTHREADS_VISIBLE_DEVICES 可以设置的值如下：

可设置的值	描述
0,1,2, 或者 438e3949-f6f2-f7b4-c904-8ffb9d6fa9d3	通过 GPU 的设备编号或者 GPU UUID 指定。
all	所有的 GPU 设备均可见。
void, empty 或者 unset	mthreads-container-runtime 的行为将和 runc[1] 保持一致。

示例:

使用全部 GPU：

❯ docker run --rm -e MTHREADS_VISIBLE_DEVICES=all ubuntu:20.04 mthreads-gmi
Mon Jul 17 07:49:07 2023
---------------------------------------------------------------
    mthreads-gmi:2.0.0           Driver Version:3.0.0
---------------------------------------------------------------
ID   Name           |PCIe                |%GPU  Mem
     Device Type    |Pcie Lane Width     |Temp  MPC Capable
+-------------------------------------------------------------+
0    MTT S2000      |00000000:03:00.0    |0%    4MiB(16384MiB)
     Physical       |8x(8x)              |51C   NO
+-------------------------------------------------------------+
1    MTT S2000      |00000000:04:00.0    |0%    4MiB(16384MiB)
     Physical       |8x(8x)              |50C   NO
---------------------------------------------------------------

---------------------------------------------------------------
Processes:
ID   PID       Process name                         GPU Memory
                                                         Usage
+-------------------------------------------------------------+
   No running processes found
---------------------------------------------------------------

使用设备号指定 GPU：

❯ docker run --rm -e MTHREADS_VISIBLE_DEVICES=1 ubuntu:20.04 mthreads-gmi
Mon Jul 17 07:49:36 2023
---------------------------------------------------------------
    mthreads-gmi:2.0.0           Driver Version:3.0.0
---------------------------------------------------------------
ID   Name           |PCIe                |%GPU  Mem
     Device Type    |Pcie Lane Width     |Temp  MPC Capable
+-------------------------------------------------------------+
0    MTT S2000      |00000000:04:00.0    |0%    4MiB(16384MiB)
     Physical       |8x(8x)              |50C   NO
---------------------------------------------------------------

---------------------------------------------------------------
Processes:
ID   PID       Process name                         GPU Memory
                                                         Usage
+-------------------------------------------------------------+
   No running processes found
---------------------------------------------------------------

使用 GPU UUID 指定 GPU：

❯ mthreads-gmi --query | grep UUID
    GPU UUID                                      :  7e8581f5-6722-035b-9b7f-07b8ed270fd0
    GPU UUID                                      :  2716ae75-44e4-231b-df26-f7c2c4abb678

❯ docker run --rm -e MTHREADS_VISIBLE_DEVICES=2716ae75-44e4-231b-df26-f7c2c4abb678 ubuntu:20.04 mthreads-gmi
Mon Jul 17 07:50:33 2023
---------------------------------------------------------------
    mthreads-gmi:2.0.0           Driver Version:3.0.0
---------------------------------------------------------------
ID   Name           |PCIe                |%GPU  Mem
     Device Type    |Pcie Lane Width     |Temp  MPC Capable
+-------------------------------------------------------------+
0    MTT S2000      |00000000:04:00.0    |0%    4MiB(16384MiB)
     Physical       |8x(8x)              |50C   NO
---------------------------------------------------------------

---------------------------------------------------------------
Processes:
ID   PID       Process name                         GPU Memory
                                                         Usage
+-------------------------------------------------------------+
   No running processes found
---------------------------------------------------------------

驱动能力

MTHREADS_DRIVER_CAPABILITIES 用于控制容器中用户态驱动程序的能力。

MTHREADS_DRIVER_CAPABILITIES 可以设置的值如下：

可设置的值	描述
compute,video 或者 graphics,utility	可以传入多个驱动能力，以 “,” 为分割符。
all	GPU 所有的能力。
empty 或者 unset	设置默认值: compute, utility。
void	不挂载任何驱动能力。

支持设置的驱动能力列表。

驱动能力	描述
compute	使用 MUSA 和 OpenCL 的应用。
graphics	使用 OpenGL 和 Vulkan 的应用。
utility	使用 mthreads-gmi 和 MTML。
video	使用编解码能力的应用。

示例：

❯ docker run --rm \
      -e MTHREADS_VISIBLE_DEVICES=all \
      -e MTHREADS_DRIVER_CAPABILITIES=compute,utility \
      ubuntu:20.04 mthreads-gmi
Mon Jul 17 07:55:29 2023
---------------------------------------------------------------
    mthreads-gmi:2.0.0           Driver Version:3.0.0
---------------------------------------------------------------
ID   Name           |PCIe                |%GPU  Mem
     Device Type    |Pcie Lane Width     |Temp  MPC Capable
+-------------------------------------------------------------+
0    MTT S2000      |00000000:03:00.0    |0%    4MiB(16384MiB)
     Physical       |8x(8x)              |51C   NO
+-------------------------------------------------------------+
1    MTT S2000      |00000000:04:00.0    |0%    4MiB(16384MiB)
     Physical       |8x(8x)              |50C   NO
---------------------------------------------------------------

---------------------------------------------------------------
Processes:
ID   PID       Process name                         GPU Memory
                                                         Usage
+-------------------------------------------------------------+
   No running processes found
---------------------------------------------------------------

Dockerfiles

构建容器镜像时在 Dockerfile 添加环境变量，运行容器时就无需再指定它们。

ENV MTHREADS_VISIBLE_DEVICES all
ENV MTHREADS_DRIVER_CAPABILITIES compute,utility

MT GPU Operator

先决条件

在安装 MT GPU Operator 前， 您应该确保 Kubernetes 集群满足一些先决条件：

1. 节点必须配置容器引擎，例如 Docker CE/EE、containerd 或 cri-o。安装 Docker 请参见安装 Docker Engine。

2. 节点功能发现 (NFD) 是每个节点上 GPU Operator 的依赖项。默认情况下，NFD master 和 worker 由 GPU Operator 自动部署。如果在部署 GPU Operator 之前，NFD 已在集群中运行，则可以将 GPU Operator 配置为不安装 NFD。

3. 要在 Kubernetes 1.13 和 1.14 中进行监控，请启用 kubelet KubeletPodResources ^[a] 功能门。从 Kubernetes 1.15 开始，默认启用KubeletPodResources。

4. 要在 Kubernetes 中收集 GPU 使用数据，必须在集群中部署 Prometheus。

   $ export VERSION=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases | grep tag_name | grep -v -- '-rc' | grep -v -- '-alpha' | sort -r | head -1 | awk -F': ' '{print $2}' | sed 's/,//' | xargs)
   $ echo $VERSION
   $ kubectl create -f https://github.com/prometheus-operator/prometheus-operator/releases/download/${VERSION}/bundle.yaml

5. 要自动安装 MT 驱动程序，必须在集群内的每个节点上手动安装以下软件包:

   • LightDM 是一个跨桌面显示管理器，可以使用以下命令进行安装：

     $ sudo apt install -y lightdm

   • libdrm2是内核直接渲染管理器 (DRM) 服务的用户空间接口，可以使用以下命令进行安装。

     $ sudo apt install -y libdrm2

     注意：所需的最低版本是 2.4.99。

6. GPU 调度器是基于 Scheduling Framework 构建的。如果要启用此功能，请确保 Kubernetes 的版本大于 1.19.

7. 为了确保 sGPU DEB 包的成功安装，需要首先在集群内的每个节点上安装所需的依赖包 dkms。

   • dkms 可以使用以下命令安装：

     $ sudo apt install -y dkms

     注意：所需的最低版本是1.95。

要启用 Kubelet Pod Resources 功能门，请运行以下命令：

echo -e "KUBELET_EXTRA_ARGS=--feature-gates=KubeletPodResources=true" | sudo tee /etc/default/kubelet

安装指南

先将部署包下载，然后解压：

$ unzip mt-gpu-operator-2.0.0.zip
$ rm mt-gpu-operator-2.0.0.zip
$ cd operator_2.0.0
$ tree
.
├── change_image_repo.sh
├── end-user-cn.md
├── mt-gpu-operator-2.0.0.tgz
├── mt-gpu-operator-custom-resources-2.0.0.tgz
├── mt-gpu-operator.yaml
├── mthreads_v1alpha4_clusterconfig.yaml
├── mthreads_v1beta2_clusterpolicy.yaml
└── sync_image.sh

0 directories, 8 files
$ tar -xvzf mt-gpu-operator-2.0.0.tgz
$ tar -xvzf mt-gpu-operator-custom-resources-2.0.0.tgz
$ tree
.
├── change_image_repo.sh
├── end-user-cn.md
├── mt-gpu-operator
│   ├── Chart.yaml
│   ├── crds
│   │   ├── biosconfigs.mthreads.com-crd.yaml
│   │   ├── clusterconfigs.mthreads.com-crd.yaml
│   │   ├── clusterpolicies.mthreads.com-crd.yaml
│   │   └── nodeconfigs.mthreads.com-crd.yaml
│   ├── templates
│   │   ├── _helpers.tpl
│   │   ├── mt-controller-manager-cm.yaml
│   │   ├── mt-controller-manager-deployment.yaml
│   │   ├── mt-controller-manager-metrics-service-svc.yaml
│   │   ├── mt-controller-manager-sa.yaml
│   │   ├── mt-gpu-operator-cleanup-crd-job.yaml
│   │   ├── mt-gpu-operator-namespace.yaml
│   │   ├── mt-gpu-operator-upgrade-crd-job.yaml
│   │   ├── mt-leader-election-rolebinding-rb.yaml
│   │   ├── mt-leader-election-role-role.yaml
│   │   ├── mt-manager-rolebinding-crb.yaml
│   │   ├── mt-manager-role-cr.yaml
│   │   ├── mt-metrics-reader-cr.yaml
│   │   ├── mt-mutating-webhook-configuration-mutatingwebhookconfiguration.yaml
│   │   ├── mt-proxy-rolebinding-crb.yaml
│   │   ├── mt-proxy-role-cr.yaml
│   │   ├── mt-published-device-cm.yaml
│   │   ├── mt-validating-webhook-configuration-validatingwebhookconfiguration.yaml
│   │   └── mt-webhook-service-svc.yaml
│   └── values.yaml
├── mt-gpu-operator-2.0.0.tgz
├── mt-gpu-operator-custom-resources
│   ├── Chart.yaml
│   ├── templates
│   │   ├── _helpers.tpl
│   │   ├── mt-gpu-cluster-config-clusterconfig.yaml
│   │   └── mt-gpu-cluster-policy-clusterpolicy.yaml
│   └── values.yaml
├── mt-gpu-operator-custom-resources-2.0.0.tgz
├── mt-gpu-operator.yaml
├── mthreads_v1alpha4_clusterconfig.yaml
├── mthreads_v1beta2_clusterpolicy.yaml
└── sync_image.sh

5 directories, 38 files

镜像使用

同步到用户镜像仓库

部署包中提供镜像同步脚本,用户可以将 registry.mthreads.com 上的镜像同步到自己的内网 harbor 中：

$ ./sync_image.sh registry.mthreads.com/mcconline <your.registry.com/repo>

部署包中提供了脚本 change_image_repo.sh 来为用户修改部署包下所有文件中的镜像仓库地址，使用方式如下：

$ ./change_image_repo.sh registry.mthreads.com/mcconline <your.registry.com/repo>

使用 Helm 安装

MT GPU Operator Helm charts 提供了多个可自定义的选项，可以根据您的环境进行配置。

Chart 自定义选项

使用 Helm chart 时可以使用以下选项。这些选项可以与 --set 一起使用。

• mt-gpu-operator

  参数	描述	默认值
  namespace	MT GPU Operator 部署在哪个命名空间下。	mt-gpu-operator

• mt-gpu-operator-custom-resources

  参数	描述	默认值
  mtGpuClusterPolicyClusterpolicy.nfd.enabled	将节点功能发现插件部署为 DaemonSet。 如果 NFD 已在集群中运行，请将此变量设置为 false。	true
  mtGpuClusterPolicyClusterpolicy.driverToolkit.enabled	默认情况下，GPU Operator 将 MT 驱动程序部署为系统上的容器。在预装 MT 驱动程序的系统上使用 GPU Operator 时，应将此值设置为 false。	true
  mtGpuClusterPolicyClusterpolicy.containerToolkit.enabled	默认情况下，GPU Operator 将 MT Container Toolkit 部署为系统上的容器。在预装 MT Container Toolkit 的系统上使用 GPU Operator 时，请将此值设置为 false。	true
  mtGpuClusterPolicyClusterpolicy.kured.enabled	将 kured 插件部署为 DaemonSet。如果 kured 已在集群中运行，则将此变量设置为 false。	true
  mtGpuClusterPolicyClusterpolicy.nodeProblemDetector.enabled	将节点问题检测器 (NPD) 插件部署为 DaemonSet。如果 NPD 已在集群中运行，请将此变量设置为 false。	true
  mtGpuClusterPolicyClusterpolicy.aiOps.enabled	默认情况下，GPU Operator 将 MT AIOps 部署为系统上的容器。如果不需要此组件，请将此值设置为 false。	true
  mtGpuClusterPolicyClusterpolicy.gpuScheduler.enabled	默认情况下，GPU Operator 不部署 GPU Scheduler。如果您想使用 sGPU，请将此变量设置为 true。	false
  mtGpuClusterPolicyClusterpolicy.gpuWebhook.enabled	默认情况下，GPU Operator 不部署 GPU Webhook。如果您想使用 sGPU，请将此变量设置为 true。	false
  mtGpuClusterPolicyClusterpolicy.kubevirt.enabled	默认情况下，GPU Operator 部署 KubeVirt 补丁以启用 vGPU 和 GPU 直通。如果要启用虚拟机工作负载，请将此值设置为 true。	false
  mtGpuClusterPolicyClusterpolicy.dcgm.enabled	默认情况下，GPU Operator 会部署 DCGM 组件，该组件是一套 GPU 管理和监控的核心组件。 如果不需要该功能，请将此值设置为 false。	true
  mtGpuClusterPolicyClusterpolicy.dcgmExporter.enabled	默认情况下，GPU Operator 会部署 DCGM Exporter 组件，该组件是基于 DCGM 的 Prometheus Exporter。 如果不需要该功能，请将此值设置为 false。	true

常见部署场景

本节介绍使用 Helm chart 安装 MT GPU Operator 时的一些常见部署方案。

1. 自定义驱动安装 自定义驱动程序工具包配置，用户最好将驱动下载到设备节点本地目录 /usr/data 下，然后参考如何指定驱动并配置和本地获取包然后修改 mt-gpu-operator-custom-resources/values.yaml。

$ helm install --wait mt-gpu-operator mt-gpu-operator
$ helm install --wait mt-gpu-operator-custom-resources mt-gpu-operator-custom-resources

1. 如果机器上预装了驱动程序和 MT 容器工具包

本示例节点上已预安装 MT 驱动程序和 MT Container Toolkit。

在安装 MT GPU Operator 之前，请确保集群中的容器运行时已配置良好。

Docker:

$ cat /etc/docker/daemon.json | grep default-runtime
    "default-runtime": "mthreads",

containerd:

$ cat /etc/containerd/config.toml | grep default_runtime_name
      default_runtime_name = "mthreads"

使用以下选项安装 MT GPU Operator。

$ helm install --wait mt-gpu-operator mt-gpu-operator
$ helm install --wait mt-gpu-operator-custom-resources mt-gpu-operator-custom-resources \
     --set mtGpuClusterPolicyClusterpolicy.driverToolkit.enabled=false \
  	 --set mtGpuClusterPolicyClusterpolicy.containerToolkit.enabled=false

3. 自定义 sGPU 配置

   默认情况下，sGPU 相关功能处于禁用状态。如果你想在 k8s 中使用 sGPU，你需要开启 GPU scheduler 组件和 GPU Webhook 组件，使用如下命令安装 mt-gpu-operator 和 mt-gpu-operator-custom-resources：

$ helm install --wait mt-gpu-operator mt-gpu-operator
$ helm install --wait mt-gpu-operator-custom-resources  mt-gpu-operator-custom-resources \
		 --set mtGpuClusterPolicyClusterpolicy.gpuScheduler.enabled=true \
   --set mtGpuClusterPolicyClusterpolicy.gpuWebhook.enabled=true

验证 GPU Operator 安装

安装 Helm Chart 后，检查 Pod 的状态以确保所有容器都在运行并且验证已完成。

$ kubectl get pods -n mt-gpu-operator
NAME                                       READY   STATUS    RESTARTS      AGE
kured-xzgk9                                1/1     Running   0             28m
mt-aiops-784789fd44-6cwdf                  1/1     Running   0             17m
mt-container-toolkit-daemonset-28466       1/1     Running   0             35s
mt-controller-manager-77674d7677-sgx99     2/2     Running   0             29m
mt-dcgm-8gwtd                              1/1     Running   0             32s
mt-dcgm-exporter-zbrb4                     1/1     Running   1             35s
mt-driver-toolkit-wxcsz                    1/1     Running   0             28m
mt-gpu-exporter-jsjwk                      1/1     Running   0             33s
mt-gpu-feature-discovery-zrlhn             1/1     Running   0             34s
mt-node-status-exporter-kdgb4              1/1     Running   0             33s
mt-operator-validator-qt4tg                1/1     Running   0             32s
mt-universal-gpu-device-controller-bx29w   1/1     Running   0             34s
nfd-master-8699f4456b-jszpc                1/1     Running   0             28m
nfd-worker-7k9g8                           1/1     Running   0             28m
nfd-worker-htsbc                           1/1     Running   0             28m
nfd-worker-szsjd                           1/1     Running   0             28m
node-problem-detector-26tgc                1/1     Running   0             28m
node-problem-detector-ntsx7                1/1     Running   0             28m
node-problem-detector-vsjnx                1/1     Running   0             28m

使用 YAML 部署 MT GPU Operator

以下是如何使用 yaml 文件安装 MT GPU Operator 当前官方版本的示例。

$ kubectl apply -f  mt-gpu-operator.yaml

等待 mt-controller-manager pod ready:

$ kubectl get po -n mt-gpu-operator
NAME                                       READY   STATUS    RESTARTS        AGE
mt-controller-manager-68fc5978f5-c2rpf     2/2     Running   0               24s

根据需要修改 mthreads_v1beta2_clusterpolicy 文件，然后创建该 CR:

$ kubectl apply -f  mthreads_v1beta2_clusterpolicy.yaml

修改 mthreads_v1alpha4_clusterconfig.yaml 文件，指定驱动等配置：

$ kubectl apply -f  mthreads_v1alpha4_clusterconfig.yaml

检查 MT GPU Operator 管理的组件的状态是否都是 Running:

$ kubectl get po -n mt-gpu-operator
NAME                                       READY   STATUS    RESTARTS      AGE
kured-xzgk9                                1/1     Running   0             28m
mt-aiops-784789fd44-6cwdf                  1/1     Running   0             17m
mt-container-toolkit-daemonset-28466       1/1     Running   0             35s
mt-controller-manager-77674d7677-sgx99     2/2     Running   0             29m
mt-dcgm-8gwtd                              1/1     Running   0             32s
mt-dcgm-exporter-zbrb4                     1/1     Running   0             35s
mt-driver-toolkit-wxcsz                    1/1     Running   0             28m
mt-gpu-exporter-jsjwk                      1/1     Running   0             33s
mt-gpu-feature-discovery-zrlhn             1/1     Running   0             34s
mt-node-status-exporter-kdgb4              1/1     Running   0             33s
mt-operator-validator-qt4tg                1/1     Running   0             32s
mt-universal-gpu-device-controller-bx29w   1/1     Running   0             34s
nfd-master-8699f4456b-jszpc                1/1     Running   0             28m
nfd-worker-7k9g8                           1/1     Running   0             28m
nfd-worker-htsbc                           1/1     Running   0             28m
nfd-worker-szsjd                           1/1     Running   0             28m
node-problem-detector-26tgc                1/1     Running   0             28m
node-problem-detector-ntsx7                1/1     Running   0             28m
node-problem-detector-vsjnx                1/1     Running   0             28m

通过 ClusterConfig 快速安装驱动

• 用户在安装完 mt-gpu-operator 和 mt-gpu-operator-custom-resources 两个 chart 后，需要手动配置为集群配置驱动。
• 用戶需要在每个 gpu 节点上的/usr/data目录(如该目录不存在，就创建出来)下放置 ddk 和 mtml 两个 deb 包。
• 修改 ClusterConfig CR 对象, ClusterConfig 对象用于控制集群哪些节点安装哪些驱动。

$ kubectl edit clusterconfig gpu-cluster-config

ClusterConfig 按如下配置：

apiVersion: mthreads.com/v1alpha4
kind: ClusterConfig
metadata:
  name: gpu-cluster-config
spec:
  upgradePolicy:
    autoUpgrade: true
    allocateStrategy: all
    drain:
      deleteEmptyDir: false
      enable: false
      force: false
      timeoutSeconds: 300
    maxParallelUpgrades: 1
    podDeletion:
      deleteEmptyDir: false
      force: false
      timeoutSeconds: 300
    waitForCompletion:
      timeoutSeconds: 0
      podSelector: ""
  nodes:
    - nodePoolName: node-pool-1
      drivers:
        - kind: musa
          local:
            filePath: /usr/data/musa.deb
        - kind: libmtml.so
          local:
            filePath: /usr/data/mtml.deb
      clusterGpuTargetRatio:
        gpu: 100%
      workspaceDir: /app/data
      sgpuSpec:
        "max_inst": "16"
        "policy": "0"
        "overcommit_ratio": "1.1"
        "time_slice": "1"
      selector:
        matchExpressions:
          - key: kubernetes.io/arch #这是节点上的label，用户根据需要配置label key
            operator: In
            values:
              - amd64

等待 NodeConfig 对象 InstallDone：

$ kubectl get nodeconfig
NAME       DRIVER UPGRADE STATE   NODE POOL    INSTALLATION TIMEOUT
worker-1   InstallDone            node-pool-1
worker-2   InstallDone            node-pool-1
worker-3   InstallDone            node-pool-1
worker-4   InstallDone            node-pool-1

InstallDone 的节点上可以看到 gpu 资源：

$ kubectl describe node worker-4
...
Capacity:
  mthreads.com/gpu:               8
...

运行示例 GPU 应用程序

使用普通 GPU

此示例运行一个简单的 CUDA 示例，它将两个向量相加：

$ cat << EOF | kubectl create -f -
apiVersion: v1
kind: Pod
metadata:
  name: opencl-test
spec:
  restartPolicy: OnFailure
  nodeSelector:
    kubernetes.io/arch: amd64
  containers:
  - name: opencl-test
    image: "ubuntu:20.04"
    imagePullPolicy: Always
    command: ["sleep"]
    args: ["3600"]
    resources:
      limits:
         mthreads.com/gpu:  1
EOF

进入 opencl-test 容器，安装 opencl 相关软件库，然后使用 clinfo 验证：

$ kubectl exec -ti opencl-test bash
root@opencl-test:/# apt-get update && apt-get -y upgrade   && apt-get install -y ocl-icd-libopencl1 opencl-headers clinfo
...
root@opencl-test:/# mthreads-gmi
Mon May 19 07:37:31 2025
---------------------------------------------------------------
    mthreads-gmi:2.0.0           Driver Version:3.0.0
---------------------------------------------------------------
ID   Name           |PCIe                |%GPU  Mem
     Device Type    |Pcie Lane Width     |Temp  MPC Capable
                                         |      ECC Mode
+-------------------------------------------------------------+
0    MTT S4000      |00000000:01:00.0    |0%    7MiB(49152MiB)
     Physical       |16x(16x)            |88C   YES
                                         |      N/A
---------------------------------------------------------------

---------------------------------------------------------------
Processes:
ID   PID       Process name                         GPU Memory
                                                         Usage
+-------------------------------------------------------------+
   No running processes found
---------------------------------------------------------------

使用 sGPU

要在 sGPU 上运行相同的工作负载，您可以将以下差异应用于 Pod 规范。

spec:
  containers:
    - name: mtpytorch
      image: ubuntu:20.04
      command:
        - "sleep"
      args:
        - "infinity"
      resources:
        limits:
-          mthreads.com/gpu: 1
+          mthreads.com/sgpu-core: 1
+          mthreads.com/sgpu-memory: 1

虚拟机使用 GPU

部署 KubeVirt

注意：目前测试过的版本是 V1.5.2, 其他版本需要自行测试。 KubeVirt 可以使用 KubeVirt Operator 进行安装，该 Operator 管理所有 KubeVirt 核心组件的生命周期。

• 使用 kubectl 部署 KubeVirt Operator：

  export VERSION=$(curl -s https://api.github.com/repos/kubevirt/kubevirt/releases | grep tag_name | grep -v -- '-rc' | grep -v -- '-alpha' | sort -r | head -1 | awk -F': ' '{print $2}' | sed 's/,//' | xargs)
  echo $VERSION
  kubectl apply -f https://github.com/kubevirt/kubevirt/releases/download/${VERSION}/kubevirt-operator.yaml

• 使用kubectl部署 KubeVirt 自定义资源定义：

  kubectl apply -f https://github.com/kubevirt/kubevirt/releases/download/${VERSION}/kubevirt-cr.yaml

验证 KubeVirt 组件

默认情况下，KubeVirt 部署 7 个 Pod、3 个服务、1 个守护进程集、3 个部署应用程序、3 个副本集。

• 检查部署情况：

  kubectl get kubevirt.kubevirt.io/kubevirt -n kubevirt -o=jsonpath="{.status.phase}"

• 检查组件：

  kubectl get all -n kubevirt

开启 kubevirt

在 clusterpolicy 对象中将 kuebevirt 开启：

apiVersion: mthreads.com/v1beta2
kind: ClusterPolicy
metadata:
  name: gpu-cluster-policy
spec:
  kubevirt:
    enabled: true

创建 VMIs

现在，您可以继续使用两种类型的 GPU 创建虚拟机实例 (VMI)：vGPU 和 GPU 直通。

创建具有摩尔线程 GPU 直通的 VMI

此示例运行具有摩尔线程 GPU 直通功能的 Ubuntu 20.04（focal）VMI。

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  name: focal
spec:
  domain:
    clock:
      timer:
        hpet:
          present: false
        hyperv: {}
        pit:
          tickPolicy: delay
        rtc:
          tickPolicy: catchup
      utc: {}
    cpu:
      cores: 8
      sockets: 2
      threads: 1
    features:
      acpi: {}
      apic: {}
      hyperv:
        relaxed: {}
        spinlocks:
          spinlocks: 8191
        vapic: {}
    machine:
      type: q35
    resources:
      requests:
        memory: 4G
    firmware:
      bootloader:
        efi:
          secureBoot: false
    devices:
      gpus:
        - deviceName: mthreads.com/MTT-S2000
          name: gpu1
          virtualGPUOptions:
            display:
              enabled: false
              ramFB:
                enabled: true
      disks:
        - name: vmdisk
          disk:
            bus: virtio
      inputs:
        - type: tablet
          bus: usb
          name: tablet
  volumes:
    - name: vmdisk
      containerDisk:
        image: sh-harbor.mthreads.com/cloud/vmdisks/focal
        imagePullPolicy: IfNotPresent

通过应用前面的 YAML 文件，您可以启动并运行 VMI：

kubectl apply -f focal.yaml
kubectl get vmi

在 Kubernetes 集群中预热 VM 镜像

kube-fledged 是一个 Kubernetes operator，用于直接在 Kubernetes 集群的工作节点上创建和管理容器镜像的缓存。为了快速启动 VMI，我们可以使用 kube-fledged 来预热 VM 镜像。

部署 kube-fledged

export KUBEFLEDGED_NAMESPACE=kube-fledged
kubectl create namespace ${KUBEFLEDGED_NAMESPACE}
helm repo add kubefledged-charts https://senthilrch.github.io/kubefledged-charts/
helm repo update
gpg --keyserver keyserver.ubuntu.com --recv-keys 92D793FA3A6460ED
gpg --export >~/.gnupg/pubring.gpg
helm install --verify kube-fledged kubefledged-charts/kube-fledged -n ${KUBEFLEDGED_NAMESPACE} --wait

通过应用以下 YAML 文件，您可以创建 VM 磁盘缓存：

apiVersion: kubefledged.io/v1alpha2
kind: ImageCache
metadata:
  name: vmdisks
  namespace: mt-gpu-operator
  labels:
    app: kubefledged
    kubefledged: imagecache
spec:
  cacheSpec:
    - images:
        - sh-harbor.mthreads.com/cloud/vmdisks/focal:latest
      nodeSelector:
        kubernetes.io/arch: amd64

卸载 MT GPU Operator

使用 Helm 卸载 MT GPU Operator

可以通过运行以下命令卸载 MT GPU Operator Custom resource 的 chart：

$ helm uninstall mt-gpu-operator-custom-resources

然后执行以下命令卸载 MT GPU Operator 的 chart：

$ helm uninstall mt-gpu-operator

运行 helm uninstall 不会删除 CRD。您可以使用以下命令删除 CRD：

$ kubectl delete --ignore-not-found=true crd clusterconfigs.mthreads.com clusterpolicies.mthreads.com nodeconfigs.mthreads.com

使用 YAML 卸载

$ kubectl delete -f mthreads_v1alpha4_clusterconfig.yaml
$ kubectl delete -f mthreads_v1beta2_clusterpolicy.yaml
$ kubectl delete -f mt-gpu-operator.yaml

如何指定驱动并配置

用户可以通过配置 mthreads_v1alpha4_clusterconfig 文件来指定下载的驱动，该文件中承载的是 clusterconfig CR，该 CR 的用途：

• 指定需要安装哪些驱动程序。
• 指定集群中 GPU 访问模式的比例。 GPU 访问模式包括 GPU、可扩展 GPU (sGPU)、虚拟 GPU (vGPU) 和直通 GPU。

基本配置

您可以直接使用以下配置，无需修改。以下 ClusterConfig 对象表示集群中的节点需要安装的 GPU 驱动和 sGPU 驱动。balanced-gpu 表示 sGPU、GPU、passthrough GPU 访问模式各占 33% 来配置集群中的 GPU 设备。

apiVersion: mthreads.com/v1alpha4
kind: ClusterConfig
metadata:
  name: gpu-cluster-config
spec:
  upgradePolicy:
    autoUpgrade: false
    allocateStrategy: all
    drain:
      deleteEmptyDir: false
      enable: false
      force: false
      timeoutSeconds: 300
    maxParallelUpgrades: 1
    podDeletion:
      deleteEmptyDir: false
      force: false
      timeoutSeconds: 300
    waitForCompletion:
      timeoutSeconds: 0
      podSelector: ""
  nodes:
    - nodePoolName: node-pool-1
      drivers:
        - kind: musa
          oss:
            endpoint: oss.mthreads.com
            id: string
            secret: string
            useSSL: false
            bucketName: product-release
            objectName: develop/20230607/musa_2023.06.07-D+4358+dkms+glvnd+Ubuntu_amd64.deb
            md5sum: string
        - kind: libmtml.so
          oss:
            endpoint: oss.mthreads.com
            id: string
            secret: string
            useSSL: false
            bucketName: release-ci
            objectName: mtml/release_1.5/a9d889431_mtml_1.5.0-linux-R_amd64.deb
            md5sum: string
        - kind: sgpu
          oss:
            endpoint: oss.mthreads.com
            id: string
            secret: string
            useSSL: false
            bucketName: release-ci
            objectName: cloud/sgpu/master/20230607/sgpu-dkms_1.1.1_amd64.deb
            md5sum: string
      clusterGpuTargetRatio:
        sgpu: 100%
      workspaceDir: /tmp
      sgpuSpec:
        "max_inst": "16"
        "policy": "0"
        "overcommit_ratio": "1.1"
        "time_slice": "1"

驱动升级策略

在 mt-driver-toolkit 升级驱动过程中，需要考虑到每次驱动容器重启时，都必须卸载驱动内核模块，然后再次加载。因此，升级驱动程序时需要执行具体操作，包括以下步骤：

• 如果 mtgpu 模块处于活动状态（/sys/module/mtgpu/refcnt 的值不为 0），则只能通过重新启动节点来卸载驱动程序。
• 如果 mtgpu 模块未使用，driver-toolkit 会卸载旧的 mtgpu 驱动程序内核模块，这将禁止所有客户端使用 GPU 驱动程序。
• 加载更新的 mtgpu 驱动程序内核模块。
• Container-toolkit 将设置节点容器运行时。
• 启用 GPU 驱动程序的客户端。

驱动升级配置选项

ClusterConfig 中的以下字段可用于配置 clusterconfig 控制器：

• autoUpgrade 负责启用或禁用驱动程序升级策略。默认值为 false。当设置为 false 时，将忽略所有其他选项，并且即使更新了 ClusterConfig 对象中的drivers、clusterGpuTargetRatio或selector字段，也不会启动升级过程。
• maxParallelUpgrades 是可以并行升级的节点数。 0 表示无限。默认值为 1。
• allocateStrategy 指定哪个操作会触发为节点重新分配 GPU 角色，这个重新分配操作也会导致节点上的驱动重新安装。
  • all：指示当字段（clusterGpuTargetRatio 或drivers或selector或sgpuSpec 或vgpuMedvWeight）更改时将采取的重新分配操作。
  • onClusterGpuTargetRatioUpdate表示只有clusterGpuTargetRatio字段发生变化时才会触发重新分配。
  • onDriverUpdate表示只有当drivers字段下的内容发生变化时才会触发重新分配。
  • onSelectorUpdate表示只有当selector字段发生变化时才会触发重新分配。
  • onSgpuSpecUpdate表示只有当sgpuSpec字段发生变化时才会触发重新分配。
  • onVgpuMdevWeightUpdated表示只有当vgpuMdevWeight字段发生变化时才会触发重新分配。
• drain提供了用于驱逐节点的选项（类似于 kubectl drain）。驱逐仅在启用时使用，并且podDeletion无法删除所有正在使用GPU的 pod。
  • enable负责在升级过程中启用和禁用节点耗尽。默认值为 false。
  • force用于强制删除 pod，即使它们不受控制器（例如 ReplicationController、ReplicaSet、Job、DaemonSet 和 StatefulSet）管理。默认值为false。
  • timeoutSeconds指定驱逐的最大等待时长。0 表示无穷大。当超时时，GPU Pod 将被强制删除。默认值为 300。
  • podSelector用于过滤节点上的 pod。如果未设置，操作员将清空所有 Pod。
  • deleteEmptyDir用于指定是否删除使用emptyDir卷的 pod。当deleteEmptyDir设置为 true 时，存储在emptyDir卷中的任何本地数据都将与 pod 一起删除。默认值为 false。
• podDeletion提供用于驱逐分配了 GPU 的 pod。
  • force用于强制删除 pod，即使它们不受控制器（例如 ReplicationController、ReplicaSet、Job、DaemonSet 和 StatefulSet）管理。默认值为false。
  • timeoutSeconds指定驱逐的最大等待时长。0 表示无穷大。当超时时，GPU Pod 将被强制删除。默认值为 300。
  • podSelector用于过滤节点上的 pod。如果未设置，操作员将清空所有 Pod。
  • deleteEmptyDir用于指定是否删除使用emptyDir卷的 pod。当deleteEmptyDir设置为 true 时，存储在emptyDir卷中的任何本地数据都将与 pod 一起删除。默认值为 false。
• waitForCompletion提供用于在升级节点上的驱动程序之前等待用户定义的 pod 组完成的选项。
  • timeoutSeconds指定驱逐的最大等待时长。0 表示无穷大。当超时时，GPU Pod 将被强制删除。默认值为 300。
  • podSelector指定 选择器选中 pod 如果是 running 的话，就等待timeoutSeconds时间，超时后进入 podDeletion 阶段。

常用配置如下：

upgradePolicy:
  autoUpgrade: false
  maxParallelUpgrades: 1
  allocateStrategy: all
  drain:
    enable: false
    force: false
    timeoutSeconds: 300
    podSelector: ""
    deleteEmptyDir: false
  podDeletion:
    force: false
    timeoutSeconds: 300
    deleteEmptyDir: false
  waitForCompletion:
    timeoutSeconds: 300
    podSelector: ""

暂停驱动程序升级

如果要暂停集群中的自动驱动程序升级，请在 clusterconfig CR 中将 spec.upgradePolicy.autoUpgrade 设置为 false。通过这样做，整个调谐器将暂停升级。当然，也可以通过设置spec.upgradePolicy.autoUpgrade为true来恢复驱动升级。

跳过驱动程序升级

如果要跳过节点驱动升级，请使用 mthreads.com/driver-upgrade.skip=true 来标记 NodeConfig 对象（与节点同名）。

停止节点上的驱动程序安装

如果在驱动安装过程中节点出现环境问题，即使已经开始安装也可能无法成功。驱动程序安装过程包括以下步骤：

• 验证节点上的驱动程序和 GPU 访问模式。
• 清除节点的 GPU 访问模式。
• 卸载所有旧驱动程序。
• 下载新的驱动程序包。
• 安装新驱动程序。
• 执行 GPU 访问模式的 post install 步骤。

要在节点上检测到问题时暂时停止安装过程，您可以通过 mthreads.com/driver-install.stop=true来标记 NodeConfig 对象(与节点同名)。问题解决后，您可以删除此标签，安装过程将自动恢复。

升级驱动相关的指标和事件

GPU Operator 生成多个指标，Prometheus 在升级过程中可以抓取这些指标。这些指标包括：

• gpu_operator_driver_auto_upgrade_enabled: 是否启用驱动程序自动升级。如果启用则值为 1，如果未启用则值为 0。
• gpu_operator_nodes_upgrades_in_progress: 当前正在升级的节点总数。
• gpu_operator_nodes_upgrades_done: 已成功完成节点驱动程序升级的节点总数。
• gpu_operator_nodes_upgrades_failed: 升级失败的节点总数。
• gpu_operator_nodes_upgrades_available: 当前满足升级条件的节点总数。
• gpu_operator_nodes_upgrades_pending: 待升级的节点总数。

在升级过程中，MT GPU Operator 将产生各种事件来报告状态或故障。以下示例是为升级单个 NodeConfig 对象而生成的一组事件。

$ kubectl describe nodeconfig yuzhou-system-product-name
...
Events:
  Type     Reason         Age                    From             Message
  ----     ------         ----                   ----             -------
  Normal   DriverUpgrade  4m30s                  mt-gpu-operator  Successfully updated nodeconfig state label to ValidateNode
  Normal   DriverUpgrade  3m30s (x2 over 3m30s)  mt-gpu-operator  Successfully updated nodeconfig state label to CordonRequired
  Normal   DriverUpgrade  3m28s                  mt-gpu-operator  Successfully updated nodeconfig state label to WaitForJobsRequired
  Normal   DriverUpgrade  3m28s                  mt-gpu-operator  Successfully updated nodeconfig state label to OperatorPodDisableRequired
  Normal   DriverUpgrade  3m27s                  mt-gpu-operator  disable mt-gpu-operator deploy label successfully, node: yuzhou-system-product-name
  Normal   DriverUpgrade  3m26s                  mt-gpu-operator  Successfully updated nodeconfig state label to DrainNodeRequired
  Normal   DriverUpgrade  2m49s (x3 over 2m49s)  mt-gpu-operator  Successfully drained the node
  Normal   DriverUpgrade  2m49s (x3 over 2m49s)  mt-gpu-operator  Successfully updated nodeconfig state label to UninstallRequired
  Warning  DriverUpgrade  2m39s                  mt-gpu-operator  Failed to update nodeconfig state label to UploadDevicesRequired err: timed out waiting for the condition
  Normal   DriverUpgrade  2m29s (x2 over 2m49s)  mt-gpu-operator  Successfully updated nodeconfig state label to ClearRoleRequired
  Normal   DriverUpgrade  89s (x2 over 2m8s)     mt-gpu-operator  (combined from similar events): Successfully updated nodeconfig state label to TryInstallRequired
  Normal   DriverUpgrade  23s                    mt-gpu-operator  Successfully updated nodeconfig annotation to [mthreads.com/driver-upgrade-wait-for-pod-completion-start-time null]=%!s(MISSING)
  Normal   DriverUpgrade  23s                    mt-gpu-operator  Successfully updated nodeconfig state label to InstallRequired
  Normal   DriverUpgrade  22s                    mt-gpu-operator  Successfully updated nodeconfig state label to ValidateNode
  Warning  DriverUpgrade  13s                    mt-gpu-operator  Failed to update nodeconfig state label to UpgradeFailed err: timed out waiting for the condition

指定驱动

在 ClusterConfig CR 中，spec.nodes[0].drivers是一个数组，用于配置节点上的驱动程序。以下 ClusterConfig 对象表示将在每个节点上安装 DEB 包和 sGPU 模块。

apiVersion: mthreads.com/v1alpha4
kind: ClusterConfig
metadata:
  name: gpu-cluster-config
  namespace: mt-gpu-operator
spec:
  upgradePolicy:
    ...
  nodes:
  - nodePoolName: node-pool-1
    specification: balanced-gpu
    workspaceDir: /tmp
    drivers:
    - kind: musa
      oss:
        endpoint: oss.mthreads.com
        id: string
        secret: string
        useSSL: false
        bucketName: product-release
        objectPrefix: develop/20221208
    - kind: sgpu
      oss:
        endpoint: oss.mthreads.com
        id: string
        secret: string
        useSSL: false
        bucketName: release-ci
        objectPrefix: cloud/sgpu/latest

驱动器种类

每个软件都有一个 kind 属性，kind 的值包括 musa,sgpu, libmtml.so, mthreads-gmi、umd、kmd、umd+kmd 和 mt_peermem。支持的封装类型说明如下：

• musa: 您可以指定 musa DEB 包，例如 musa_2022.08.22-M643.Ubuntu_amd64.deb
• sgpu：您可以指定一个包，例如 sgpu_km.ko 或 sgpu-dkms_1.1.1_amd64.deb。
• libmtml.so：您可以指定 libmtml.so 或 a9d889431_mtml_1.5.0-linux-R_amd64.deb 等软件包。
• mthreads-gmi：可以指定 mthreads-gmi 等包。
• umd：您可以指定一个包，例如 B1043_mtgpu_linux-x86-xorg-hw-relWithInfo-umd_8ee3170.tar.gz。
• kmd：您可以指定一个包，例如 B1261_mtgpu_linux-x86-xorg-hw-release-kmd_e8aac23.tar.gz。
• umd+kmd：可以指定 B1331_mtgpu_linux-x86-nulldrmws-hw-debug-AGP-umd_e858cbd-kmd_6cc1e50.tar.gz 等包。
• mt_peermem: 您可以指定 mt_peermem.ko 等文件。

驱动源

驱动源包括 OSS 服务器、HTTP 服务器、本地目录。以下各节分别介绍如何从这些来源获取包。

从 OSS 获取包

使用以下结构指定 OSS 上的包。

oss:
  endpoint: oss.mthreads.com # oss domain or ip
  id: string # oss user name
  secret: string # oss password
  useSSL: false #  need ssl authentication or not
  bucketName: product-release # bucket on oss
  objectPrefix: master/20220810 # prefix under bucket
  objectName: master/20220810/musa_2022.08.10-M397.Kylin_arm64.deb # objectName under bucket
  md5sum: string # used to verify file

以下配置从 OSS 上的 product-release 存储桶中获取 master/20220810 前缀目录下的 DEB 包。

drivers:
- kind: musa
  oss:
    endpoint: oss.mthreads.com
    id: string
    secret: string
    useSSL: false
    bucketName: product-release
    objectPrefix: master/20220810

上述配置没有指定 DEB 包。前缀文件夹（在本示例中为 master/20220810）可能包含不同体系结构和格式的多个 DEB 包，如下例所示。

$ mc ls oss/product-release/master/20220810
[2022-08-10 23:29:21 CST]   119B STANDARD musa_2022.08.10-M-B397_info.txt
[2022-08-10 23:29:22 CST]  32MiB STANDARD musa_2022.08.10-M397.Kylin_arm64.deb
[2022-08-10 23:29:23 CST]  34MiB STANDARD musa_2022.08.10-M397.Ubuntu_amd64.deb
[2022-08-10 23:29:23 CST]  34MiB STANDARD musa_2022.08.10-M397.Ubuntu_amd64.rpm
[2022-08-10 23:29:23 CST] 122MiB STANDARD musa_2022.08.10-M397.uos_arm64.deb

driver-toolkit 会根据所在节点的 Linux 发行版（Ubuntu 或 UOS）和架构来下载对应的 DEB 包。 或者，您也可以直接使用 objectName 指定要从 OSS 下载的 DEB 包。以下示例下载 master/20220810/musa_2022.08.10-M397.Ubuntu_amd64.deb。

drivers:
- kind: musa
  oss:
    bucketName: product-release
    endpoint: oss.mthreads.com
    id: string
    secret: string
    objectName: master/20220810/musa_2022.08.10-M397.Ubuntu_amd64.deb
    useSSL: false
    md5sum: string

如果要指定安装包的安装脚本，可以使用 installConfig 字段。在本例中，workspaceDir 为 /tmp，/tmp/umd+kmd/ 为下载文件解压后的文件夹:

workspaceDir: /tmp
drivers:
- kind: umd+kmd
  oss:
    id: string
    secret: string
    useSSL: false
    bucketName: release-rc
    objectPrefix: release_pkg/master
    objectName: release_pkg/master/B1261_mtgpu_linux-x86-xorg-hw-release-kmd_e8aac23.tar.gz
    md5sum: string
    installConfig:
      installCmd: /tmp/umd+kmd/mt_umd/x86_64-mtgpu_linux-xorg-release/install.sh
      uninstallCmd: /tmp/umd+kmd/mt_umd/x86_64-mtgpu_linux-xorg-release/install.sh -u

从 HTTP 服务器获取包

以下配置从 HTTP 服务器下载 DEB 包。

drivers:
- kind: musa:
  http:
    url: http://oss.mthreads.com/product-release/master/20220711/musa_2022.07.11-M215.Ubuntu_amd64.deb
    md5sum: string

本地获取包

用户需要将该文件放在主机上的 /usr/data 目录下，然后配置 clusterconfig 对象，以下配置从本地的 /usr/data/mtgpu_linux-xorg-hw-20220707.tar.gz 获取包文件。

drivers:
- kind: umd+kmd:
  local:
    filePath: /usr/data/mtgpu_linux-xorg-hw-20220707.tar.gz
    md5sum: string

Selector 配置

Selector用来指定需要安装驱动程序的节点。以下配置在标签为kubernetes.io/hostname键值为k8s-master和user-ubuntu的节点上安装drivers字段中指定的驱动程序。

apiVersion: mthreads.com/v1alpha4
kind: ClusterConfig
metadata:
  name: clustergpuconfig-sample
  namespace: mt-gpu-operator
spec:
  upgradePolicy:
    ...
  nodes:
  - nodePoolName: test
    clusterGpuTargetRatio:
      gpu: 80%
      passthrough: 20%
    workspaceDir: /tmp
    drivers:
    - kind: musa
      oss:
        endpoint: oss.mthreads.com
        id: string
        secret: string
        useSSL: false
        bucketName: product-release
        objectPrefix: master/20220910
    selector:
      matchExpressions:
      - key: kubernetes.io/hostname
        operator: In
        values:
        - k8s-master
        - user-ubuntu

selector字段是可选的。没有设置selector的 ClusterConfig 对象可能如下所示：

apiVersion: mthreads.com/v1alpha4
kind: ClusterConfig
metadata:
  name: clustergpuconfig-sample
  namespace: mt-gpu-operator
spec:
  nodes:
    - clusterGpuTargetRatio:
        gpu: 80%
        passthrough: 20%
      workspaceDir: /tmp
      drivers:
        - kind: musa
          oss:
            endpoint: oss.mthreads.com
            id: string
            secret: string
            useSSL: false
            bucketName: product-release
            objectPrefix: master/20220910

以上示例表示所有节点都可以安装在 product-release 存储桶的 master/20220910 前缀文件夹下的 musa 包。

节点打上用户指定的标签

在驱动安装完成后，用户可以使用 nodeDriverLabels 字段给节点打上指定标签。

apiVersion: mthreads.com/v1alpha4
kind: ClusterConfig
metadata:
  name: clustergpuconfig-sample
  namespace: mt-gpu-operator
spec:
  nodes:
  - clusterGpuTargetRatio:
    ...
    nodeDriverLabels:
      "musa-driver-version": "2.0.1"
      "sGPU-version": "1.2.1"

分配 GPU 核心

分配 GPU 核心的意思是节点可能有多张卡，每张卡可能有 1-2 个核心，每个核心可以配置成普通 GPU 或 sGPU 或 vGPU 或 passthrough 设备，而 clusterconfig 对象中有字段可以控制集群中这些设备角色的比例。

方法一：指定 clusterGpuTargetRatio

您可以使用 clusterGpuTargetRatio 字段指定如何在集群中分配 GPU 核心。

apiVersion: mthreads.com/v1alpha4
kind: ClusterConfig
metadata:
  name: clustergpuconfig-sample
  namespace: mt-gpu-operator
spec:
  upgradePolicy: ...
  nodes:
    - nodePoolName: node-pool-1
      clusterGpuTargetRatio:
        gpu: 80%
        passthrough: 20%
      workspaceDir: /tmp
      drivers:
        - kind: musa
          oss:
            endpoint: oss.mthreads.com
            id: string
            secret: string
            useSSL: false
            bucketName: product-release
            objectPrefix: master/20220910

上述 ClusterConfig 对象表示 80% 的 GPU 核心分配给 普通 GPU 容器，20% 分配为直通供虚拟机使用。

clusterGpuTargetRatio结构如下:

clusterGpuTargetRatio:
  gpu: string
  passthrough: string
  sgpu: string

注意：

• 比例的格式必须满足 ^(100|[1-9]?\d(.)?)%$|0$/ 正则表达式。另外，比率之和必须等于 100%。

• 在当前版本的 mt-gpu-operator 中，clusterGpuTargetRatio.passthrough 只能设置为低于 100% 的值。

• clusterGPUTargetRatio 表示预期值。实际值取决于集群节点的状态。

• 要将 GPU 核心分配为直通设备供虚拟机使用，您需要在 BIOS 中启用虚拟化扩展和 I/O 内存管理单元 (IOMMU) 扩展。 对于 Intel，引导计算机并将 intel_iommu=on 附加到 grub 配置文件中 GRUB_CMDLINE_LINUX 行的末尾。

  # vi /etc/default/grub
  ...
  GRUB_CMDLINE_LINUX="nofb splash=quiet console=tty0 ... intel_iommu=on
  ...
  # grub-mkconfig -o /boot/grub/grub.cfg
  
  # reboot

  对于 AMD，引导计算机，并将 amd_iommu=on 附加到 grub 配置文件中 GRUB_CMDLINE_LINUX 行的末尾。

  # vi /etc/default/grub
  ---
  GRUB_CMDLINE_LINUX="nofb splash=quiet console=tty0 ... amd_iommu=on
  ---
  # grub-mkconfig -o /boot/grub/grub.cfg
  
  # reboot

方法二：指定规格

为了便于配置比例，您可以指定 specifications 而不是 clusterGpuTargetRatio，如下所示。

apiVersion: mthreads.com/v1alpha4
kind: ClusterConfig
metadata:
  name: gpu-cluster-config
  namespace: mt-gpu-operator
spec:
  upgradePolicy: ...
  nodes:
    - nodePoolName: node-pool-1
      drivers:
        - kind: musa
          oss:
            bucketName: product-release
            endpoint: oss.mthreads.com
            id: string
            objectPrefix: develop/20221208
            secret: string
            useSSL: false
        - kind: sgpu
          oss:
            bucketName: release-ci
            endpoint: oss.mthreads.com
            id: string
            objectPrefix: cloud/sgpu/latest
            secret: string
            useSSL: false
      specification: balanced-gpu
      workspaceDir: /tmp

上例中 specification 设置为 balanced-gpu，与下面的配置效果相同。

clusterGpuTargetRatio:
  gpu: "33%"
  sgpu: "33%"
  passthrough: "34%"

specification 的有效值包括 gpu-only、sgpu-only、vgpu-only、passthrough-only、balanced-gpu 和 balanced-vgpu。这些 specification 值对应的 clusterGpuTargetRatio 配置如下：

gpu-only:

clusterGpuTargetRatio:
  gpu: "100%"

sgpu-only:

clusterGpuTargetRatio:
  sgpu: "100%"

passthrough-only:

clusterGpuTargetRatio:
  passthrough: "100%"

指定 sgpuSpec

sgpuSpec 定义节点 sGPU 配置的 sGPU 参数。sGPU 有这些参数可以配置：max_inst、policy、time_slice、overcommit_ratio。有关更多信息，请参阅 sGPU 文档。

sgpuSpec:
  "max_inst": "16"
  "policy": "0"
  "overcommit_ratio": "1.1"
  "time_slice": "1"

常见场景

ClusterConfig 对象主要用于以下场景：

• 在所有节点上安装相同的驱动程序。
• 在不同节点上安装不同的驱动程序。
• 按比例分配 GPU 核心。

在所有节点上安装相同的驱动程序

Helm chart 中有一个 values.yaml 文件，用于安装 GPU 驱动。gpu-cluster-config 在mtGpuClusterConfigClusterconfig.spec 中配置如下。

nodes:
  - nodePoolName: test
    drivers:
      - kind: musa
        oss:
          bucketName: product-release
          endpoint: oss.mthreads.com
          id: string
          objectPrefix: develop/20221208
          secret: string
          useSSL: false
      - kind: sgpu
        oss:
          bucketName: release-ci
          endpoint: oss.mthreads.com
          id: string
          objectPrefix: cloud/sgpu/latest
          secret: string
          useSSL: false
    specification: balanced-gpu
    workspaceDir: /tmp

在不同的节点上安装不用的驱动

使用 selector 选择应安装驱动程序的节点：

upgradePolicy:
  allocateStrategy: all
  autoUpgrade: false
  drain:
    deleteEmptyDir: false
    enable: false
    force: false
    timeoutSeconds: 300
  maxParallelUpgrades: 1
  podDeletion:
    deleteEmptyDir: false
    force: false
    timeoutSeconds: 300
  waitForCompletion:
    timeoutSeconds: 300
nodes:
  - nodePoolName: node-pool-1
    clusterGpuTargetRatio:
      sgpu: 50%
      passthrough: 50%
    workspaceDir: /tmp
    drivers:
      - kind: musa
        oss:
          endpoint: oss.mthreads.com
          id: string
          secret: string
          useSSL: false
          bucketName: product-release
          objectPrefix: master/20221101
      - kind: sgpu
        oss:
          endpoint: oss.mthreads.com
          id: string
          secret: string
          useSSL: false
          bucketName: release-ci
          objectPrefix: cloud/sgpu/latest
    selector:
      matchExpressions:
        - key: kubernetes.io/hostname
          operator: In
          values:
            - nodename_1
            - nodename_2
  - nodePoolName: node-pool-2
    clusterGpuTargetRatio:
      gpu: 100%
    workspaceDir: /tmp
    drivers:
      - kind: musa
        oss:
          endpoint: oss.mthreads.com
          id: string
          secret: string
          useSSL: false
          bucketName: product-release
          objectPrefix: master/20221101
    selector:
      matchExpressions:
        - key: kubernetes.io/hostname
          operator: In
          values:
            - nodename_3
            - nodename_4

驱动安装基本运维

查询基本状态

如果驱动安装/升级失败，你可以通过以下命令查看驱动当前安装的状态：

$ kubectl get nodeconfig
NAME           DRIVER UPGRADE STATE   NODE POOL    INSTALLATION TIMEOUT
node-1         InstallDone            default
node-2         InstallDone            default
node-3         InstallDone            default

当驱动安装失败后，可以查看驱动升级的相关事件：

$ kubectl get events --sort-by='.lastTimestamp' | grep DriverUpgrade
...
5m28s       Normal    DriverUpgrade              nodeconfig/node-1                             (combined from similar events): Successfully updated nodeconfig state label to ValidateNode
5m19s       Warning   DriverUpgrade              nodeconfig/node-1                               Failed to update nodeconfig state label to UpgradeFailed err: timed out waiting for the condition
4m28s       Normal    DriverUpgrade              nodeconfig/node-1                                  Successfully updated nodeconfig state label to WaitForJobsRequired
79s         Normal    DriverUpgrade              nodeconfig/node-1                                 Successfully updated nodeconfig state label to InstallDone
29s         Normal    DriverUpgrade              nodeconfig/node-2                                                  Successfully updated nodeconfig state label to InstallDone
...

你也可以单独查看某一个节点上驱动安装事件：

$ kubectl describe nodeconfig <node-name>
...
Events:
  Type     Reason         Age   From             Message
  ----     ------         ----  ----             -------
  Warning  DriverUpgrade  12s   mt-gpu-operator  2024-01-19 03:29:06: failed reason: timed out waiting for the condition
  Normal   DriverUpgrade  12s   mt-gpu-operator  2024-01-19 03:29:06: disable mt-gpu-operator deploy label successfully, node: yuzhou-system-product-name
  Normal   DriverUpgrade  12s   mt-gpu-operator  2024-01-19 03:29:06: Successfully drained the node
  Normal   DriverInstall  12s   mt-gpu-operator  2024-01-19 03:29:06: Success to clear gpu

升级失败

用户可以通过查看 mt-controller-manager 日志来定位问题：

km logs mt-controller-manager-xxx-xxx | grep controllers.NodeConfig

节点卡在 RebootNodeRequired 状态

如果节点长时间卡在 RebootNodeRequired 状态：

$ kubectl get nodeconfig
node-1      RebootNodeRequired

可能是由 Kured 导致的问题。在重启节点之前，Kured 会尝试驱逐节点上的负载，但这一步骤可能会失败。用户可以通过查看节点上的注解和标签来确定 Kured 是否卡在驱逐阶段：

$ kubectl describe node <node-name> | grep reboot
                    mthreads.com/node-need-reboot=true
                    weave.works/kured-most-recent-reboot-needed: 2024-01-18T04:58:47Z
                    weave.works/kured-reboot-in-progress: 2024-01-18T04:58:47Z

这些标签和注解是由 Kured 创建的：

• mthreads.com/node-need-reboot=true：表示节点需要重启。
• weave.works/kured-most-recent-reboot-needed: 2024-01-18T04:58:47Z：表示上一次由 Kured 触发节点重启的时间。
• weave.works/kured-reboot-in-progress: 2024-01-18T04:58:47Z：表示当前 Kured 正在处理节点，可能正在驱逐节点上的负载。

若希望在 Kured 驱逐失败时强制重启节点，在 ClusterPolicy 中添加 Kured 强制重启的参数：

  kured:
    enabled: true
    args:
    ...
    - --force-reboot=true