GPU Operator
重要
在Kubernetes集群上配置 GPU Operator 前，应确认环境满足如下条件：
Kubernetes版本及CRI支持范围：
Kubernetes
CRI
Version
= 1.23
docker
≥ 18.09.3
containerd
≥ 1.5.0
≥ 1.24
containerd
≥ 1.5.0
管理节点以及工作节点应允许创建特权容器 [1] 。
Host应使用如下操作系统或其衍生版本，并选择有MetaX内核驱动支持的内核版本：
Host OS
Ubuntu
18.04 / 20.04 / 22.04
CentOS
8.x / 9.x
OpenEuler
20.03 / 22.03
无需且不推荐在工作节点预安装 MXMACA® 内核态驱动，若已安装也无需卸载。
关于 GPU Operator
GPU Operator 是更加云原生化的方案，除了具备 GPU Extensions 方案的全部功能之外，针对于 MXMACA® 软件栈在Kubernetes集群上的部署及应用，进行了多处优化：
用户容器镜像优化
在使用 GPU Extensions 方案时，用户的应用容器镜像需要基于 MXMACA® 基础镜像构建。 而使用 GPU Operator 方案后，用户可选择制作不包含 MXMACA® SDK的应用容器镜像。如此，可带来两项好处：
镜像尺寸减小
MXMACA® 版本升级时无需重新构建应用镜像
MXMACA® 由 GPU Operator 统一管理并部署在每个工作节点上，用户的作业运行时将使用节点上已部署的 MXMACA® SDK。 此过程在操作层面对用户透明，尽管用户能够感知到容器在运行时自动安装了 MXMACA® SDK这一变化，但无需为此做任何额外操作。
驱动自动部署
使用 GPU Extensions 方案时，系统管理员需预先在每个工作节点上安装内核态驱动（包含虚拟化驱动的配置及安装）。
GPU Operator 方案提供了自动部署驱动及配置GPU虚拟化规格的能力。管理员可配置
driver.deployPolicy选取不同部署策略或关闭内核态驱动的自动部署功能。GPU Operator 提供名为
driver-config的ConfigMap，管理员可通过此文件指定工作节点的GPU虚拟化规格（vfnum），配置文件的更新将在几分钟内在相关节点上生效。虚拟机方案支持
为满足Kubernetes集群中引入的KubeVirt虚拟化能力，GPU Operator 方案提供了绑定KubeVirt所依赖的底层驱动vfio-pci的能力。 用户可在不停机状态下通过配置文件选择要绑定到vfio-pci的GPU设备，从而允许虚拟机直接访问物理GPU设备。
GPU Operator 提供名为
metax-vfio-config的ConfigMap，管理员可通过此文件指定要绑定到vfio-pci驱动的沐曦GPU，驱动变更会在几分钟内完成。内核态驱动灰度发布
GPU Operator 方案提供了内核态驱动灰度发布功能，管理员可配置
driver.enableRollout开启灰度发布功能。灰度发布功能支持分批次自动化驱动升级，支持管理员手动确定每批次升级结果。在升级的过程中，管理员可以暂停或者回滚本次升级。
方案自动化部署
GPU Operator 方案提供的云原生能力由多个软件组件协作完成，组件部署时存在参数配合，部署时序也有严格的要求，安装这些组件是一件极其复杂的事情。
因此，正如 GPU Operator 字面所传达出来的信息，此方案基于 Operator Framework [2] 实现，组件部署及同步全部由代码控制、自动化地进行。管理员通过一条
helm install命令即可完成部署，而无需关注背后的细节。轻量化模式支持
GPU Operator 在
0.11.0版本中支持了轻量化（Minimal Mode）模式，将原有Extensions方案的核心逻辑与组件收编至Operator，形成统一的控制平面，带来更高效更便利的使用体验。
部署参考
安装 GPU Operator
在Kubernetes管理节点执行如下命令，即可完成 GPU Operator 的安装：
helm install oci://DOMAIN/PROJECT/metax-operator \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=DOMAIN/PROJECT
设置Chart选项
GPU Operator Chart支持 GPU Extensions Chart全部选项。额外支持的选项，参见下方表格。
选项 |
类型 |
描述 |
|---|---|---|
minimalMode |
bool |
轻量化模式开关，默认为 |
gpuDevice |
struct |
gpu-device组件选项，参见 |
gpuLabel |
struct |
gpu-label组件选项，参见 |
driver |
struct |
driver-manager组件内核态驱动控制选项，参见 |
maca |
struct |
driver-manager组件 MXMACA® 控制选项, 参见 |
runtime |
struct |
container-runtime组件选项，参见 |
data-exporter |
struct |
data-exporter组件选项，参见 |
topo-discovery |
struct |
topo-discovery组件选项，参见 |
gpu-scheduler |
struct |
gpu-scheduler组件选项，参见 |
podTemplateSpec |
struct |
全局工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。目前仅支持 |
vfio-manager（已弃用） |
struct |
vfio-manager组件选项，参见 |
选项 |
类型 |
描述 |
|---|---|---|
healthyInterval |
integer |
GPU健康检查间隔的秒数，＞0 时启用功能，＝0 时禁用功能，默认值为5 |
deploy |
bool |
是否启用组件，默认为 |
log |
struct |
日志选项，参见 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
选项 |
类型 |
描述 |
|---|---|---|
deploy |
bool |
是否启用组件，默认为 |
log |
struct |
日志选项，参见 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
选项 |
类型 |
描述 |
|---|---|---|
deployPolicy |
enum |
资源部署策略，默认为 |
payload |
struct |
内核驱动控制资源包选项，参见 |
fwUpgradePolicy |
enum |
固件升级策略，默认为 |
fwEnableVirt |
bool |
是否使用虚拟化固件，默认为 |
deploy |
bool |
是否启用组件，默认为 |
log |
struct |
日志选项，参见 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
选项 |
描述 |
|---|---|
PreferCloud |
使用payload镜像中的内核驱动 |
PreferHost |
优先使用主机上的内核驱动，如果不存在，则使用payload镜像中的内核驱动 |
PreferNewer |
如果主机上的内核驱动版本高于payload镜像中的驱动版本，使用主机上的内核驱动，否则使用payload镜像中的内核驱动 |
选项 |
类型 |
描述 |
|---|---|---|
vfioConfig |
struct |
选择要绑定到vfio-pci的GPU设备列表，参考 |
deploy |
bool |
是否启用组件，默认为 |
log |
struct |
日志选项，参考 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
选项 |
类型 |
描述 |
|---|---|---|
nodeName |
string |
目标节点名，支持正则匹配 |
gpus |
string list |
绑定到vfio驱动的GPU序号，支持逗号分隔字符串和 |
选项 |
类型 |
描述 |
|---|---|---|
payload |
struct |
MXMACA® 控制资源包选项，参见 |
deploy |
bool |
是否启用组件，默认为 |
log |
struct |
日志选项，参见 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
选项 |
类型 |
描述 |
|---|---|---|
deploy |
bool |
是否启用组件，默认为 |
log |
struct |
日志选项，参见 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
选项 |
类型 |
描述 |
|---|---|---|
name |
string |
payload镜像名，默认值为 |
version |
string |
payload镜像版本，若 |
registry |
string |
payload镜像地址，默认使用全局选项 |
选项 |
类型 |
描述 |
|---|---|---|
enableRollout |
bool |
是否开启内核态驱动灰度发布升级，默认为 |
upgradeSteps[].replicas |
integer or percentage |
该升级批次完成后Pod为新版本的副本数量 |
upgradeSteps[].pauseDuration |
time |
定义升级完成后暂停阶段的行为。默认为空，系统自动暂停。管理员手动设置 |
upgradeSteps[].toleration |
integer or percentage |
当前升级批次允许失败节点个数，默认为 |
pause |
bool |
是否暂停灰度发布升级，默认为 |
maxParallel |
integer or percentage |
最大并行升级节点数量，默认为 |
maxUnavailable |
integer or percentage |
本次灰度发布结束时允许节点不可用（升级失败）的数量，默认为 |
maxFailureThreshold |
integer |
每批次最大错误重试次数，默认为 |
fallback |
string |
每批次升级遇到操作异常或者升级失败节点超过 |
选项 |
类型 |
描述 |
|---|---|---|
images |
string list |
payload镜像列表， 格式为 |
registry |
string |
payload镜像地址，默认使用全局选项 |
选项 |
类型 |
描述 |
|---|---|---|
deploy |
bool |
是否启用data-exporter组件，默认 |
service |
struct |
服务启动配置，参见 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
选项 |
类型 |
描述 |
|---|---|---|
type |
enum |
服务类型，默认为 |
port |
integer |
服务端口号，仅在 |
选项 |
类型 |
描述 |
|---|---|---|
deploy |
bool |
是否启用拓扑组件，默认 |
mode |
string |
拓扑组件的运行模式，默认为 |
dragonfly |
struct |
dragonfly模式选项，参见 |
switchbox |
struct |
switchbox模式选项，参见 |
rpcServerPort |
integer |
rpc服务端口号 |
master |
struct |
topo-master选项配置，参见 |
worker |
struct |
topo-worker选项配置，参见 |
选项 |
类型 |
描述 |
|---|---|---|
image |
struct |
镜像选项，参考Kubernetes 原生镜像结构体定义 |
log |
struct |
日志选项，参见 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
Env |
struct |
环境选项，参考Kubernetes 原生环境结构体定义 |
ServerPort |
integer |
Topo-Master 服务端口 |
选项 |
类型 |
描述 |
|---|---|---|
image |
struct |
镜像选项，参考Kubernetes 原生镜像结构体定义 |
log |
struct |
日志选项，参见 |
podTemplateSpec |
struct |
组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 |
MetricsPort |
integer |
Metrics 服务端口 |
选项 |
类型 |
描述 |
|---|---|---|
deploy |
bool |
是否启用组件，默认为 |
kubeScheduler |
struct |
kubernetes scheduler配置，参见 |
gpuAware |
struct |
gpu aware配置，参见 |
选项 |
类型 |
描述 |
|---|---|---|
image |
struct |
镜像选项，参考 Kubernetes 结构体定义。如果为空，会默认使用当前集群的调度器镜像 |
选项 |
类型 |
描述 |
|---|---|---|
image |
struct |
镜像选项，参考 Kubernetes 结构体定义 |
选项 |
类型 |
描述 |
|---|---|---|
spec.nodeSelector |
struct |
指定 Pod 调度所需的节点标签匹配规则 |
spec.affinity |
struct |
配置 Pod 与节点的亲和性/反亲和性调度策略 |
spec.tolerations |
struct |
定义 Pod 对节点污点的容忍规则，允许调度到特定节点 |
运行时组件依赖
GPU Operator 各组件具备独立的部署开关，同时系统通过预置逻辑自动管理组件间的运行依赖。部署时需确保开启相关组件的开关，底层依赖关系将自动完成协调。若未正确启用前置组件，可能导致依赖项初始化失败或功能异常。
组件名称 |
前置组件 |
|---|---|
gpuLabel |
无 |
runtime |
gpuLabel |
driver |
gpuLabel、runtime |
maca |
gpuLabel、runtime |
gpuDevice |
gpuLabel、runtime、maca |
data-exporter |
gpuLabel、driver |
vfio-manager (已弃用) |
gpuLabel |
轻量化模式
轻量化模式下，用户需要提前在节点上安装内核驱动和 MXMACA® 软件栈。
开启轻量化模式
该模式仅允许在安装时进行配置，用户可以配置 minimalMode 为 true 开启，在Kubernetes管理节点执行如下命令，即可完成 GPU Operator 的安装：
helm install oci://DOMAIN/PROJECT/metax-operator \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=DOMAIN/PROJECT
--set minimalMode=true
组件支持
轻量化模式下，系统支持运行以下组件：
gpuLabel
gpuDevice
dataExporter
topoDiscovery
gpuScheduler
其中 dataExporter、 topoDiscovery 和 gpuScheduler 为可选安装。
组件的运行依赖如下表所示：
组件名称 |
前置组件 |
|---|---|
gpuLabel |
无 |
gpuDevice |
gpuLabel |
dataExporter |
gpuLabel |
topoDiscovery |
gpuLabel |
gpuScheduler |
无 |
（弃用） 配置全局toleration
该功能已标记为弃用，并在 0.11.0 版本中移除。建议迁移至新版方案，详情参见 custom-pod-template-spec-config 工作负载 Pod 参数配置规范。
配置全局toleration，使 GPU Operator 能够部署在具有 taint 的节点上。
所有组件的toleration始终和全局toleration保持一致，单独对组件配置的toleration将会失效。
配置全局toleration的方式如下：
在安装时，传入全局toleration配置文件，初始化配置。
在安装后，修改自定义资源clusteroperator的配置信息，更新配置。
安装时，初始化全局toleration配置
安装前创建全局toleration配置文件。
全局toleration配置文件格式与Kubernetes Tolerations配置格式保持一致，示例如下：
1tolerations: 2 - key: "key1" 3 operator: "Equal" 4 value: "value1" 5 effect: "NoSchedule" 6 - key: "key2" 7 operator: "Equal" 8 value: "value1" 9 effect: "NoExecute"
安装 GPU Operator 时，接收全局toleration配置文件，设置全局toleration。
安装时，通过
--set-file tolerations=<全局toleration配置文件>，传入全局toleration配置文件。检查全局toleration是否配置成功。
kubectl get ds -n metax-operator -o jsonpath='{range .items[*]}{.spec.template.spec.tolerations}{"\n"}'
用户可通过上述命令获取所有组件当前的toleration配置。
比较全局toleration配置文件和各个组件当前的toleration配置是否相同，相同代表全局toleration配置初始化成功。
安装后，修改自定义资源，更新全局toleration配置
GPU Operator 部署时，会生成一个名为 cluster-operator 的 clusteroperator。编辑 cluster-operator 中toleration配置，会更新全局toleration。
编辑
cluster-operator，更新全局toleration。使用
kubectl edit clusteroperator cluster-operator进入编辑模式，依据以下高亮所示，添加全局tolerations。1spec: 2 tolerations: 3 - key: "key1" 4 operator: "Equal" 5 value: "value1" 6 effect: "NoSchedule" 7 - key: "key2" 8 operator: "Equal" 9 value: "value1" 10 effect: "NoExecute
全局toleration配置格式与Kubernetes Tolerations配置格式保持一致。用户依照实际情况，更新具体toleration 配置，例如[line 3-10]所示内容。
cluster-operator中没有toleration字段时，用户需要在spec下添加tolerations字段，再更新toleration配置。检查全局toleration是否更新成功。
kubectl get ds -n metax-operator -o jsonpath='{range .items[*]}{.spec.template.spec.tolerations}{"\n"}'
用户可通过上述命令获取所有组件当前的toleration配置。
比较更新后的toleration配置和各个组件当前的toleration配置是否相同，相同代表全局toleration配置更新成功。
工作负载 Pod 参数配置规范
注意
当前版本支持 全局级 与 组件级 双维度配置，可管理字段如下：
spec：
nodeSelector、affinity、tolerations
配置优先级规则
组件级 > 全局级
若组件定义了
podTemplateSpec，则完全忽略全局配置，仅采用组件的 PodTemplateSpec。字段级覆盖规则
当同时存在
tolerations与podTemplateSpec.spec.tolerations时，后者优先级更高。配置合并策略
基础类型：直接替换原值
Map类型：合并键值对，存在相同键时覆盖，否则新增
数组类型：执行追加操作
配置操作指南（以 tolerations 为例）
默认模板配置（Helm Values）
以下是 maca 和 driver 组件的默认模板配置：
1# maca 默认模板 2maca-daemonset.yaml 3spec: 4 tolerations: 5 - key: "node-role" 6 operator: "Equal" 7 value: "maca" 8 effect: "NoSchedule" 9 10# driver 默认模板 11driver-daemonset.yaml 12spec: 13 tolerations: 14 - key: "node-role" 15 operator: "Equal" 16 value: "driver" 17 effect: "NoExecute"
初始化配置（Helm Values）
定义全局与组件级参数，组件级配置会覆盖全局同名称字段：
1# 全局配置 2podTemplateSpec: 3 spec: 4 tolerations: 5 - key: "node-type" 6 operator: "Equal" 7 value: "general" 8 effect: "NoSchedule" 9 10# 组件级配置（maca） 11maca: 12 podTemplateSpec: 13 spec: 14 tolerations: 15 - key: "node-type" 16 operator: "Equal" 17 value: "gpu" 18 effect: "NoSchedule"
运行时动态调整
通过控制台或 API 更新配置（需满足字段约束）：
1# 编辑集群 Operator CR 2kubectl edit clusteroperators.gpu.metax-tech.com cluster-operator 3 4# 修改后保存生效（需确保yaml格式正确）
配置验证流程
查看 maca 组件 DaemonSet
预期结果：合并默认模板与自定义配置，tolerations 包含
node-role=maca和node-type=gpu。1kubectl get ds -n $namespace metax-maca -o jsonpath='{.spec.template.spec.tolerations}' 2# 输出示例： 3# - key: "node-role" 4# operator: "Equal" 5# value: "maca" 6# effect: "NoSchedule" 7# - key: "node-type" 8# operator: "Equal" 9# value: "gpu" #来自组件配置 10# effect: "NoSchedule"
查看 driver 组件 DaemonSet
预期结果：仅继承全局配置，tolerations 包含
node-role=driver和node-type=general。1kubectl get ds -n $namespace metax-driver -o jsonpath='{.spec.template.spec.tolerations}' 2# 输出示例： 3# - key: "node-role" 4# operator: "Equal" 5# value: "driver" 6# effect: "NoExecute" 7# - key: "node-type" 8# operator: "Equal" 9# value: "general" #来自全局配置 10# effect: "NoSchedule"
内核驱动配置v1
配置虚拟化
GPU Operator 在将所有软件组件部署到集群上后，会生成一个名为 driver-config 的 ConfigMap。
1{ 2 "node-vfnums": "nodes: 3 sample-node: 4 vfnum: 4 5 sample-node2: 6 vfnum: 2 7 foo: 8 vfnum: 2 9 " 10}
用户可通过修改其内容控制集群上节点的虚拟化设置，如新增 [line 7-8] 所示内容，将foo节点上的每张显卡分为2个VF实例。
根据 ConfigMap 传递到工作节点所需的时间不同，管理员可在几分钟内观测到foo节点上 metax-tech.com/gpu 资源总数变为 \(N_\mathrm(gpu) \times M_\mathrm(vfnum)\) 。
期间，foo节点上以 metax-gpu-device 开头命名的 pod 被自动销毁重建属于预期行为。
配置绑定 vfio-pci 驱动
用户可配置 values.yaml 的 driver.vfioConfig 选项来选择要绑定到 vfio-pci 驱动的沐曦GPU设备。
备注
0.11.0 版本起， vfio-manager 组件已被弃用。 0.11.0 版本之前属于 vfioManager.vfioConfig 的配置项，现迁移至 driver.vfioConfig 。
配置示例：
1driver: 2 vfioConfig: 3 - nodeName: worknode1 4 gpus: "0,1,2" 5 - nodeName: worknode\d+ 6 gpus: "0,1,2"
该配置会在
metax-vfio-config中生成对应的参数并生效。配置项说明
nodeName: 节点名。支持正则匹配。gpus: GPU序号列表。支持逗号分隔数组，及all选项。更新配置
GPU Operator 部署完成后，集群会生成名为
metax-vfio-config的ConfigMap，用于配置 GPU 绑定vfio-pci驱动。 可通过kubectl edit cm metax-vfio-config更新配置。 未被选中绑定到vfio-pci驱动的沐曦GPU会自动绑定到原生驱动上。
配置内核驱动参数
GPU Operator 在将所有软件组件部署到集群上后，会生成一个名为 driver-config 的 ConfigMap。
用户可以通过修改其内容控制集群节点上的内核驱动参数。内核驱动参数分为集群级别（ module-params ）和节点级别（ node-module-params ）。
节点级别的配置优先级更高，即同时存在集群级别和节点级别的配置，最终生效的是节点的配置。如果节点配置不存在，会使用集群配置。如果上述配置都不存在，将会使用默认配置。
1{ 2 "module-params": " 3 xcore_page_size: 10 4 ", 5 "node-module-params": " 6 sample-node1: 7 xcore_page_size: 12 8 ", 9 "node-vfnums": "nodes: 10 sample-node: 11 vfnum: 4 12 sample-node2: 13 vfnum: 2 14 " 15}
以上示例中 [line 2-4] 所示内容为集群级别配置，将集群上所有节点的 metax 驱动的 xcore_page_size 设置为 10。
以上示例中 [line 5-8] 所示内容为节点级别配置，将集群上 sample-node1 节点的metax驱动的 xcore_page_size 设置为 12。
根据 ConfigMap 传递到工作节点所需的时间不同，管理员可在几分钟内观测到 sample-node1 节点上 /sys/module/metax/parameters/xcore_page_size 参数值为 12。其余节点为上的值 10。
备注
内核的参数实际生效结果以内核的具体行为为准。具体参数配置可以从驱动参数中获取。
目前 driver-config 支持 xcore_page_size 、gpu_model 参数的配置。
内核驱动配置v2
driver_config_v1 内核驱动配置v1 仅支持节点级别的虚拟化配置，无法控制单颗GPU粒度是否开启虚拟化，并且仅支持通过GPU序号选择GPU。
为支持对单颗GPU粒度的虚拟化及驱动绑定选择，推荐用户通过 v2 版本驱动配置进行指定。
配置项说明
用户可参考如下示例准备v2版本驱动配置文件：
1module-params: 2 gpu_model: 1 3nodes-config: 4 - nodeName: workerNode-1 5 vfNum: 2 6 moduleParams: 7 gpu_model: 1 8 - nodeName: workerNode-2 9 vfNum: 2 10 virtGPUs: "0000:01:00.0" 11 vfioGPUs: "0000:02:00.0"
[line 3-7] :为节点
workerNode-1的每个GPU虚拟化为2个实例，并配置gpu_model参数。[line 8-11] :为节点
workerNode-2的0000:01:00.0GPU虚拟为2个实例，并将0000:02:00.0绑定至vfio-pci驱动。
内核驱动配置v2参数介绍，参见下表。
Driver Config v2 选项
类型
描述
module-params
map
集群级别内核参数，v2版本配置仅支持
gpu_model项nodes-config
list
节点配置列表
nodes-config[].nodeName
string
节点名，逗号分隔列表。支持正则表达式
nodes-config[].vfNum
integer
虚拟化数量
nodes-config[].virtGPUs
string
开启虚拟化的GPU列表。逗号分隔，支持GPU序号、BDF号、
all选项。nodes-config[].vfioGPUs
string
绑定至vfio-pci驱动的GPU列表。逗号分隔，支持GPU序号、BDF号、
all选项。nodes-config[].moduleParams
map
节点级别内核参数列表
备注
virtGPUs仅在开启虚拟化时生效。GPU序号排列从0开始，按BDF字典序从小到大排序。支持
"-"指定序号范围。nodes-config.moduleParams会覆盖module-params集群默认参数。无效的配置（nodeName不存在/GPU序号超出范围/BDF号非法等）会被忽略。
初始化集群
在初始化集群时，可通过
--set-file和 直接修改 values.yaml 两种方式初始化v2版本配置。 当且仅当内核驱动配置v1的全部配置项都未指定时，内核驱动配置v2才会生效。使用
--set-file假设 operator chart 同级目录下，存在如下所示名为
driver_config_v2.yaml的v2版本配置文件:nodesConfig: - nodeName: ubuntu-node-1 vfNum: 2 vfioGPUs: "all" moduleParams: gpu_model: 1
可通过如下命令运行带有
v2版本driver配置的operator:helm install <metax-operator-chart> --generate-name \ --set-file driver.driverConfigFile=driver_config_v2.yaml
直接修改
values.yaml在operator chart中的
values.yaml配置driver.driverConfig选项：driver: driverConfig: nodesConfig: - nodeName: ubuntu-node-1 vfNum: 2 vfioGPUs: "all" moduleParams: gpu_model: 1
当同时存在两种方式配置时，
--set-file的优先级更高。
配置修改
如需在运行时修改配置，可通过
kubectl edit cm driver-config命令启动编辑模式，对driver-config配置项进行修改并应用：data: module-params: | gpu_model: 1 node-module-params: "" node-vfnums: "" nodes-config: | - nodeName: ubuntu-node-1 moduleParams: gpu_model: 1 vfNum: 2 vfioGPUs: "all" version: v2
v1到v2配置的切换
集群初始化时
仅仅当
v1内核驱动配置未指定时，v2版本配置才会生效。 可通过--set强制将v1内核驱动配置指定为空：helm install <metax-operator-chart> --generate-name \ --set driver.vfnumsConfig=null \ --set driver.vfioConfig=null \ --set driver.moduleParams=null \ --set driver.nodeModuleParams=null \ --set-file driver.driverConfigFile=driver_config_v2.yaml
配置修改时
用户在应用
v1版本内核驱动配置时，可看到driver-config的data.version字段为v1。 如需切换到v2版本配置，需显式切换data.version字段为v2并手动配置data.nodes-config项。 若data.version字段和配置项冲突（例如version设为v2，但仅仅配置了v1版本的配置），则修改无效。 由v2切换回v1同理。
配置内核驱动灰度发布
GPU Operator 提供内核驱动灰度发布方案，管理员可按照如下示例学习如何配置驱动灰度发布：
配置灰度发布。
配置
enableRollout为true，设置每批次升级参数。upgradeSteps用于设置每批次升级参数。replicas表示该升级批次完成后Pod为新版本的副本数量，在使用百分号时，系统会确保至少有一个Pod会被升级。假定集群有10个工作节点，系统按照如下配置驱动灰度发布：
第一次升级副本数量为2，最大并行升级参数为50%，实际最大并行升级节点数量为
1=max(1,ROUNDUP(50%*2))，系统将会经历两次循环，每次升级一个节点，升级完成后系统进入暂停状态，管理员需要手动触发下一批次升级。第二次和第三次升级副本数量均为3，最大并行升级参数为50%，实际最大并行升级节点数量为
2=max(1,ROUNDUP(50%*3))，系统将会经历两次循环，第一次会升级两个节点，第二次升级一个节点，升级完成后系统会自动超时等待10s，在此期间管理员可以检查升级情况，可以设置升级暂停，若没有任何操作，系统将会在10s后自行进入下一批次升级。第四次升级
replicas设置为 100%，确保所有的Pod均升级到新版本，实际升级的副本数量为2，升级完成后系统进入暂停状态，管理员需要手动确认本次升级完成。
# 编辑cr kubectl edit clusteroperators.gpu.metax-tech.com cluster-operator # 编辑灰度发布策略 driver: upgradePolicy: enableRollout: true upgradeSteps: - replicas: 2 pause: - replicas: 5 pauseDuration: 10000 - replicas: 8 pauseDuration: 10000 - replicas: 100% pause: pause: false maxParallel: 50% maxUnavailable: 0 maxFailureThreshold: 3 fallback: pause
升级过程中调整参数。
仅支持修改“灰度发布策略开关”和“暂停状态”：
# 强制回滚 kubectl patch clusteroperators.gpu.metax-tech.com clusteroperator type=json -p '[{"op": "replace","path":"/driver/upgradePolicy/enableRollout","value": "false"}]' # 暂停升级 kubectl patch clusteroperators.gpu.metax-tech.com clusteroperator type=json -p '[{"op": "replace", "path": "/driver/upgradePolicy/pause","value": "false"}]' # 恢复升级 kubectl patch clusteroperators.gpu.metax-tech.com clusteroperator type=json -p '[{"op": "replace","path": "/driver/upgradePolicy/pause","value": "true"}]'
查看执行状态。
kubectl get clusteroperators.gpu.metax-tech.com cluster-operator -o jsonpath={.status.upgradeStatus}
status: upgradeStatus: lastAppliedSpec: lastCoDriverSpec: upgrading: condition: - type: status: lastTransitionTime: reason: message: phase: message: status: lastPodSpecRevision: upgradingPodSpecRevision: currentStepIndex: currentUpgradeReplicas: currentUpgradeReadyReplicas: currentFailureRetry: currentStepState: totalUpgradeReplicas: totalUpgradeReadyReplicas: lastUpdateTime: message: recheckTime:
灰度升级状态参数介绍，参见下表。
Driver Upgrade Status 选项
类型
描述
lastAppliedSpec
string
升级前
metax-driverDaemonSet配置lastCoDriverSpec
string
升级前
metax-driverClusterOperator中的spec.driver配置upgrading
bool
标识KMD灰度升级是否运行
condition[].type
enum
升级状况的类型，可选值
Progressing，Succeed，Failed，Terminatingcondition[].status
string
升级状况是否适用，可选值
True，False，Unknowncondition[].lastTransitionTime
time
灰度发布上次从一种状态切换到另一种状态的时间戳
condition[].reason
string
机器可读的，驼峰编码的（UpperCamelCase）的文字，表述上次状况变化的原因
condition[].message
string
人类可读的消息，给出上次状态（包括灰度发布升级阶段和批次升级）转换的详细信息
phase
enum
灰度发布升级阶段，可选值
Idling，Progressing，Terminating，Disabled，Disablingmessage
string
人类可读的消息，给出上次灰度发布升级状态转换的详细信息
status.lastPodSpecRevision
string
升级前Pod的Spec版本号
status.upgradingPodSpecRevision
string
升级后Pod的Spec版本号
status.currentStepIndex
integer
当前批次升级索引，表明当前为第几次升级
status.currentUpgradeReplicas
integer
当前批次升级副本数量
status.currentUpgradeReadyReplicas
integer
当前批次升级成功的副本数量
status.currentFailureRetry
integer
当前批次升级失败次数
status.currentStepState
enum
当前批次状态，，可选值
StepUpgradeInit，StepUpgrade，StepPaused，StepReady，Completedstatus.message
string
人类可读的消息，给出升级批次转换的详细信息
status.totalUpgradeReplicas
integer
本次升级总副本数量
status.totalUpgradeReadyReplicas
integer
本次升级成功的副本数量
status.lastUpdateTime
time
状态更新的时间戳
status.recheckTime
time
系统自动进入下一升级阶段的时间戳
升级完成。
提交灰度升级策略并且开启
enableRollout时，系统会通过validating-admission-webhook校验参数，参数异常时会返回失败。执行灰度升级时，集群必须处于离线状态，无运行中的任务。
固件升级
用户可以通过配置固件升级参数来升级GPU设备上的固件。
配置固件升级
管理员可配置
driver.fwUpgradePolicy为PreferCloud以使用payload镜像中的固件来升级。目前支持以下参数配置：
等待固件生效
固件升级成功后，driver-manager组件会在对应节点上报
NodeNeedReboot事件。观察到该事件说明固件升级已经完成，固件会在主机重启后生效。示例如下：$ kubectl get event LAST SEEN TYPE reason OBJECT message 9s Normal NodeNeedReboot node/sample-node1 firmware upgrade done, need reboot machine to take effect
如果需要立即生效，可以手动重启服务器，重启服务器前请确认相关的业务已经正常停止。
检查固件版本
主机重启后，可以使用
mx-smi工具检查当前的固件版本是否符合预期。关闭固件升级
管理员可配置
driver.fwUpgradePolicy为Never来关闭固件升级功能。
备注
固件升级功能只支持在物理机环境上运行，且只支持PF的固件升级。
使用固件升级功能要求当前服务器上所有GPU设备的VBIOS版本不跨1.12.0.0版本，即都小于1.12.0.0版本或者都大于等于1.12.0.0版本。建议当前所有GPU设备版本不小于1.12.0.0版本。
不支持在固件升级过程中修改固件升级参数。
目前固件升级不支持多机互联场景。
目前不支持从非虚拟化版本固件升级到虚拟化版本固件，原因是虚拟化版本固件对服务器有较高要求，需要用户手动确认当前服务器型号能否支持虚拟化固件。
配置sGPU
当gpu-device以sGPU模式运行时，会将沐曦GPU注册为 metax-tech.com/sgpu 资源。用户可通过以下步骤使用该资源。 注意配置模式前，需要确保节点上没有业务运行。
设置gpu-device以sGPU模式运行
通过给指定节点增加特定标签的方式，使节点上的gpu-device组件以sGPU模式运行。
kubectl label node sample-node1 metax-tech.com/gpu-device.mode=sgpu
设置后观察节点的可用资源。
kubectl get node sample-node1 -o json | jq '.status.allocatable | with_entries(select(.key | startswith("metax-tech.com/sgpu")))'
示例输出：
{ "metax-tech.com/sgpu": "16" }
如果需要恢复传统的native模式，可以通过以下命令恢复。
kubectl label node sample-node1 metax-tech.com/gpu-device.mode=native --overwrite
设置后观察节点的可用资源。
kubectl get node sample-node1 -o json | jq '.status.allocatable | with_entries(select(.key | startswith("metax-tech.com/gpu")))'
示例输出：
{ "metax-tech.com/gpu": "1" }
配置sGPU调度策略（可选）
通过给指定节点增加特定标签的方式，动态设置sGPU的调度策略。
kubectl label node sample-node1 metax-tech.com/gpu-device.qos-policy=best-effort --overwrite
目前支持的调度策略选项如下：
gpu-device QOS Policy Options 选项
描述
best-effort
各个sGPU不限制算力，默认配置
fixed-share
各个sGPU有固定的算力配额，且无法超过固定配额使用
burst-share
各个sGPU有固定的算力配额，若GPU卡还有空闲算力，就可以被sGPU使用
备注
该功能需要依赖container-runtime组件，请确认安装时已部署相应组件。
该功能需要配合HAMi调度器使用，请确认使用前已安装HAMi。
配置 gpu-scheduler 调度器
gpu-scheduler 组件为 Kubernetes 集群提供 GPU 资源调度能力，包含以下核心组件：
kube-scheduler：Kubernetes 原生调度器（默认保持与集群相同版本）
gpu-aware 插件：Extender 模式实现的 GPU 资源调度插件
部署说明
Helm 配置
仅允许通过 Helm 修改以下参数：
kube-scheduler.imagegpu-aware.image
其他配置需直接修改 Helm Chart 中的
gpu-scheduler模板
组件特性
提供标准 Extender 接口（默认服务端口：8080）
支持被其他调度器集成
详细功能参见
gpu-awaregpu-aware
重要
权限要求：该组件需要集群 Admin 权限（Operator 由于权限不足，无法管理此组件）。
卸载方式：卸载 GPU Operator。
部署示例
在安装 GPU Operator 时部署gpu-scheduler组件。
helm install oci://DOMAIN/PROJECT/metax-operator \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=DOMAIN/PROJECT
--set gpuScheduler.deploy=true
参数配置
ConfigMap 配置
以下是 gpu-scheduler 的 ConfigMap 参数介绍：
选项 |
描述 |
|---|---|
gpu-scheduler-config |
调度器主配置，参考Kubernetes官方KubeSchedulerConfiguration配置 |
weight.score |
通信分数权重，该数值越大，任务调度倾向于通信效率高的节点 |
weight.loss |
损失分数权重，该数值越大，任务调度倾向于对集群造成GPU资源碎片化更小的节点 |
配置示例
apiVersion: v1
kind: ConfigMap
metadata:
name: metax-gpu-scheduler-config
namespace: {f .Release.Namespace
data:
gpu-scheduler-config:
apiVersion: kubescheduler.config.k8s.io/v1beta2
kind: KubeSchedulerConfiguration
leaderElection:
leaderElect: false
profiles:
- schedulerName: metax-gpu-scheduler
extenders:
- urlPrefix:: "https://127.0.0.1:8080"
filterVerb:"filter"
prioritizeVerb:"prioritize"
nodeCacheCapable: false
weight: 500
enableHTTPS: true
ignorable: false
tlsConfig:insecure: true
managedResources:
- name: metax-tech.com/gpu
weight:
score: "1.0"
loss:"0.5"
安装时修改参数
找到 Helm Charts 里 templates/gpu-scheduler/configmap.yaml，根据需求完成配置变更后，安装 GPU Operator。
运行时修改参数
GPU Operator 提供名为 metax-gpu-scheduler-config 的 ConfigMap，管理员可通过修改此资源完成对gpu-scheduler配置更新，配置文件的更新将在几分钟内在相关节点上生效。
验证部署
GPU Operator 引入了更多的软件组件，并且具有更为复杂的组件间依赖关系，但验证部署的方式和 GPU Extensions 方案保持一致。
无论使用何种部署方案，均需要在所有组件正常工作的前提下，节点上才有可分配的 metax-tech.com/gpu 资源，以此保证用户作业的安全。
详细信息，参见 GPU Extensions 的 verification 验证部署章节。
卸载 GPU Operator
若需卸载 GPU Operator，可先通过 helm list -n metax-operator 命令查询已安装的Chart，再执行 helm uninstall <CHART> -n metax-operator --wait 命令进行卸载。
备注
-n 指定的参数为 namespace，应与安装时所指定的值保持一致。
也可直接运行以下脚本自动检查已安装的 GPU Operator 并进行卸载。
chart=$(helm list -q -f "metax" -n metax-operator)
if [[ -n $chart ]]; then
helm uninstall $chart -n metax-operator --wait
fi
备注
为确保 GPU Operator 部署的资源能够被正确清理， --wait 参数为必选项，不可省略。
提交作业
制作容器镜像
加载基础镜像
首先需准备镜像，加载镜像的操作步骤参见
macaimageMXMACA® 容器镜像。准备Dockerfile
在 GPU Operator 方案部署的集群中，应用容器镜像无需携带 MXMACA® 软件栈，因此尺寸更加小巧，同时在有必要升级 MXMACA® 版本时，应用容器镜像也无需重建。 尽管应用容器镜像可以不包含 MXMACA® 的文件，但容器构建过程中仍然需要 MXMACA® 的基础镜像作为构建环境。 推荐在 Dockerfile 使用 multi-stage build 功能。
以下为 Dockerfile 示例：
1FROM cr.metax-tech.com/library/maca-c500:2.18.0.3-ubuntu18.04-amd64 as builder 2 3RUN apt-get update && apt-get install -y \ 4 autoconf \ 5 build-essential \ 6 libtool \ 7 patchelf \ 8 pkg-config \ 9 ... 10 11ENV VAR1=VALUE1 12ENV VAR2=VALUE2 13... 14 15WORKDIR /workspace 16COPY . /workspace 17RUN make OUTPUT=/app 18 19FROM ubuntu:18.04 20 21RUN apt-get update && apt-get install -y \ 22 libelf1 \ 23 libltdl7 \ 24 libnuma1 \ 25 ... \ 26&& rm -rf /var/lib/apt/lists/* 27 28COPY --from=builder /app /app
用户基于此示例编写适用于实际工程的 Dockerfile 时，需注意以下细节：
[line 1] 使用 MXMACA® 基础镜像作为
builder镜像，提供必要的 MXMACA® 软件栈工具及库文件。[line 9] 此处增加构建用户应用所必须的工具和开发依赖库。
[line 13] 此处设置构建过程所需的环境变量。
[line 19] 基于
ubuntu:18.04镜像而非 MXMACA® 基础镜像。[line 25] 修改此处以安装用户应用运行时依赖库，
libelf1、libltdl7和libnuma1为 MXMACA® SDK运行时依赖。[line 28] 从
builder容器中拷贝构建好的应用至基础容器。
使用此过程构建应用容器可避免因开发工具、开发依赖库以及构建过程临时文件造成的存储浪费。
构建镜像
假设用户工作目录有如下结构， Project 为应用项目根目录， Dockerfile 放置于同级目录。
workspace ├── Dockerfile └── Project ├── Makefile └── src用户可在 workspace 目录运行如下命令完成镜像的构建：
docker build -f Dockerfile -t DOMAIN/PROJECT/application:1.0 ./Project
准备作业yaml文件
用户可参考如下示例编写作业yaml文件：
1apiVersion: v1 2kind: Pod 3metadata: 4 name: application 5 labels: 6 app: application 7spec: 8 nodeSelector: 9 metax-tech.com/gpu.vfnum: "0" 10 metax-tech.com/gpu.product: "C500" 11 containers: 12 - image: DOMAIN/PROJECT/application:1.0 13 name: application-container 14 command: ["/bin/bash", "-c", "--"] 15 args: ["/app/bin/xxx --option=val; sleep infinity"] 16 resources: 17 limits: 18 metax-tech.com/gpu: 2
加载指定版本 MXMACA®
在作业yaml的配置中设置环境值 METAX_MACA_VERSION，系统会自动查找该版本 MXMACA®，如未发现，会返回错误。
用户可参考如下示例编写作业yaml文件：
1apiVersion: v1 2kind: Pod 3... 4spec: 5 containers: 6 env: 7 - name: METAX_MACA_VERSION 8 value: "maca-2.18.0.3" 9 resources: 10 limits: 11 metax-tech.com/gpu: 2
查找说明：
该功能仅在申请了沐曦GPU的作业上生效。
按照前缀匹配，例如，配置值可设置为
maca-2，maca-2.18，maca-2.18.0或maca-2.18.0.3。传入
maca和maca-会拒绝匹配，返回错误。对符合要求的列表按照版本号从新到旧（降序）排序，选择最新版本的 MXMACA® 资源。
提交作业
执行 kubectl create -f sample.yaml 命令提交作业。
KubeVirt添加GPU
KubeVirt旨在将虚拟机作为第一类资源集成到 Kubernetes 中。使用KubeVirt可以在 Kubernetes 集群上以类似于管理容器的方式来管理和编排虚拟机。
KubeVirt提供了一种将主机设备分配给虚拟机的机制。以下示例展示了如何将集群中的沐曦GPU设备分配给KubeVirt虚拟机。
准备PCI设备直通
为了将主机上的PCI设备（沐曦GPU）直通到虚拟机，需要以下准备步骤：
开启IOMMU
主机设备直通要求启用IOMMU扩展。 要启用IOMMU，根据CPU类型，主机应通过附加的内核参数启动。 x86平台参见
x86_iommu；Arm平台参见arm_iommu。x86 Linux内核IOMMU配置参数 参数格式
说明
intel_iommu=on
启用Intel IOMMU
amd_iommu=on
启用AMD IOMMU
iommu=pt 或 iommu.passthrough=1
仅在PCI设备透传时使用IOMMU
Arm Linux内核IOMMU配置参数 参数格式
说明
iommu.passthrough=1
仅在PCI设备透传时使用IOMMU
以下示例为运行在Intel CPU的Ubuntu操作系统中，启动IOMMU扩展：
#使用root用户 $ sudo su #编辑 GRUB 配置文件 $ vim /etc/default/grub ... GRUB_CMDLINE_LINUX="... intel_iommu=on" ... #更新配置文件 $ update-grub #使用最新的内核参数启动 $ reboot #检查iommu是否开启 $ dmesg | grep -i iommu
加载vfio-pci驱动模块
通过
modprobe vfio-pci命令将vfio-pci驱动模块加载至主机，并通过ls /sys/bus/pci/drivers/ | grep vfio-pci检查是否加载成功。将沐曦GPU绑定到指定vfio-pci驱动
KubeVirt仅支持透传绑定到
vfio-pci驱动的主机设备。 GPU Operator 方案为沐曦GPU提供了单卡粒度的vfio-pci驱动绑定功能。 可参考配置绑定 vfio-pci 驱动配置绑定 vfio-pci 驱动，通过配置metax-vfio-config项为沐曦GPU绑定vfio-pci驱动。
获取集群中可用的沐曦GPU
在将需要直通给KubeVirt虚拟机的主机设备绑定至
vfio-pci驱动后，gpu-device组件会将对应的沐曦GPU上报给Kubernetes集群。 可以通过以下命令获取Kubernetes集群中是否存在可用于KubeVirt的沐曦GPU设备：kubectl get node worknode1 -o json | jq '.status.allocatable | with_entries(select(.key | startswith("metax-tech.com/vfio-gpu"))) | with_entries(select(.value != "0"))'
输出示例：
{ "metax-tech.com/vfio-gpu": "1" }
以上输出示例表示集群中可被占用的
"metax-tech.com/vfio-gpu"资源的数量为1。 需记录下沐曦GPU资源名称，以便后续在创建KubeVirt资源时将沐曦GPU加入可用设备列表。查看GPU设备型号
为获取需要透传给KubeVirt虚拟机的GPU设备型号，可在工作节点上通过
lspci -nnk -d 9999:命令查看沐曦GPU设备信息。输出示例：
109:00.0 Display controller [0380]: Device [9999:4001] 2 Subsystem: Red Hat, Inc. Device [1af4:1100] 3 Kernel driver in use: vfio-pci 4 Kernel modules: metax 50a:00.0 Display controller [0380]: Device [9999:4001] 6 Subsystem: Red Hat, Inc. Device [1af4:1100] 7 Kernel driver in use: METAX 8 Kernel modules: metax 9... ...
以上示例中[line 3]显示该设备为绑定到
vfio-pci驱动的沐曦GPU设备。[line 1]显示其对应的[厂商ID:设备ID]，以上示例中为[9999:4001]。安装KubeVirt
用户可通过KubeVirt 快速启动 [3] 安装KubeVirt。 安装KubeVirt CR部分可参考 vfio‑gpu资源申请。
有关配置选项的更多信息，请参阅KubeVirt [4] 用户指南。部署成功后，用户可观察到集群中
virt-operator、virt-api、virt-handler、virt-controller等组件正常运行。准备虚拟机镜像
镜像可以直接下载开源三方镜像。
备注
三方镜像内核版本可能无法直接安装metax-driver驱动，需要升级内核。
也可以通过如下Dockerfile构建，例如准备一个qcow2格式的Ubuntu虚拟机镜像并拷贝到
/disk目录下：#Dockerfile文件 $ cat ./Dockerfile FROM scratch ADD ubuntu-template.qcow2 /disk/ #build镜像 $ docker build -t ubuntu-vm:18.04 .
之后可使用构建好的虚拟机镜像创建虚拟机。
创建带GPU的虚拟机
准备好KubeVirt环境和虚拟机镜像后，用户可通过编写虚拟机资源的配置文件来定义虚拟机，例如定义
VirtualMachine、VirtualMachineInstance等虚拟机资源。其中可通过指定
spec.domain.devices.hostDevices字段来为虚拟机分配沐曦GPU，示例配置可参考 vfio‑gpu资源申请中步骤2。 其中关键字段配置为：deviceName: 表示设备的资源名称name: 表示虚拟机中设备的名称containerDisk.image: 虚拟机镜像
将示例配置保存为
testvm.yaml，用户可通过命令kubectl apply -f testvm.yaml创建名为testvm的虚拟机。启动KubeVirt虚拟机
用户可通过
virtctl二进制工具管理KubeVirt虚拟机。virtctl获取请参阅kubevirt Release [5] 。启动名为
testvm的虚拟机：
$ virtctl start testvm
登录名为
testvm的虚拟机：
#vnc登录 $ virtctl vnc testvm #ssh账号密码登录 $ virtctl ssh testvm --local-ssh
验证GPU设备
登录到虚拟机内部，通过
lspci命令检查GPU设备是否存在:$ lscpi | grep 9999
备注
用户如需MXMACA软件包，可在虚拟机内部自行安装。