摩尔线程云原生套件 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 集群满足一些先决条件：
-
节点必须配置容器引擎，例如 Docker CE/EE、containerd 或 cri-o。安装 Docker 请参见安装 Docker Engine。
-
节点功能发现 (NFD) 是每个节点上 GPU Operator 的依赖项。默认情况下，NFD master 和 worker 由 GPU Operator 自动部署。如果在部署 GPU Operator 之前，NFD 已在集群中运行，则可以将 GPU Operator 配置为不安装 NFD。
-
要在 Kubernetes 1.13 和 1.14 中进行监控，请启用 kubelet
KubeletPodResources[a] 功能门。从 Kubernetes 1.15 开始，默认启用KubeletPodResources。 -
要在 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 -
要自动安装 MT 驱动程序，必须在集群内的每个节点上手动安装以下软件包:
-
LightDM 是一个跨桌面显示管理器，可以使用以下命令进行安装：
$ sudo apt install -y lightdm -
libdrm2是内核直接渲染管理器 (DRM) 服务的用户空间接口，可以使用以下命令进行安装。$ sudo apt install -y libdrm2注意：所需的最低版本是
2.4.99。
-
-
GPU 调度器是基于 Scheduling Framework 构建的。如果要启用此功能，请确保 Kubernetes 的版本大于
1.19. -
为了确保 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
参数 描述 默认值 namespaceMT GPU Operator 部署在哪个命名空间下。 mt-gpu-operator -
mt-gpu-operator-custom-resources
参数 描述 默认值 mtGpuClusterPolicyClusterpolicy.nfd.enabled将节点功能发现插件部署为 DaemonSet。 如果 NFD 已在集群中运行，请将此变量设置为 false。truemtGpuClusterPolicyClusterpolicy.driverToolkit.enabled默认情况下，GPU Operator 将 MT 驱动程序部署为系统上的容器。在预装 MT 驱动程序的系统上使用 GPU Operator 时，应将此值设置为 false。truemtGpuClusterPolicyClusterpolicy.containerToolkit.enabled默认情况下，GPU Operator 将 MT Container Toolkit 部署为系统上的容器。在预装 MT Container Toolkit 的系统上使用 GPU Operator 时，请将此值设置为 false。truemtGpuClusterPolicyClusterpolicy.kured.enabled将 kured 插件部署为 DaemonSet。如果 kured 已在集群中运行，则将此变量设置为 false。truemtGpuClusterPolicyClusterpolicy.nodeProblemDetector.enabled将节点问题检测器 (NPD) 插件部署为 DaemonSet。如果 NPD 已在集群中运行，请将此变量设置为 false。truemtGpuClusterPolicyClusterpolicy.aiOps.enabled默认情况下，GPU Operator 将 MT AIOps 部署为系统上的容器。如果不需要此组件，请将此值设置为 false。truemtGpuClusterPolicyClusterpolicy.gpuScheduler.enabled默认情况下，GPU Operator 不部署 GPU Scheduler。如果您想使用 sGPU，请将此变量设置为 true。falsemtGpuClusterPolicyClusterpolicy.gpuWebhook.enabled默认情况下，GPU Operator 不部署 GPU Webhook。如果您想使用 sGPU，请将此变量设置为 true。falsemtGpuClusterPolicyClusterpolicy.kubevirt.enabled默认情况下，GPU Operator 部署 KubeVirt 补丁以启用 vGPU 和 GPU 直通。如果要启用虚拟机工作负载，请将此值设置为 true。falsemtGpuClusterPolicyClusterpolicy.dcgm.enabled默认情况下，GPU Operator 会部署 DCGM 组件，该组件是一套 GPU 管理和监控的核心组件。 如果不需要该功能，请将此值设置为 false。truemtGpuClusterPolicyClusterpolicy.dcgmExporter.enabled默认情况下，GPU Operator 会部署 DCGM Exporter 组件，该组件是基于 DCGM 的 Prometheus Exporter。 如果不需要该功能，请将此值设置为 false。true
常见部署场景
本节介绍使用 Helm chart 安装 MT GPU Operator 时的一些常见部署方案。
- 自定义驱动安装
自定义驱动程序工具包配置，用户最好将驱动下载到设备节点本地目录
/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
- 如果机器上预装了驱动程序和 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
-
自定义 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 $VERSIONkubectl 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
