3. 安装与维护

3.1. 安装

3.1.1. 环境要求

在安装之前，请确保环境和资源满足以下所有要求。

重要

• Kubernetes集群：

  • Helm 包管理器 ≥ 3.0

  • Kubernetes版本及CRI支持范围：

    Kubernetes	CRI	Version
    = 1.23	docker	≥ 18.09.3
    	containerd	≥ 1.5.0
    ≥ 1.24	cri-dockerd	≥ 0.2.0
    	containerd	≥ 1.5.0

• 主机节点：

  • Host应使用如下操作系统或其衍生版本，并选择有metax内核驱动支持的内核版本：

    Host OS	Ubuntu	18.04 / 20.04 / 22.04
    	CentOS	8.x / 9.x
    	OpenEuler	20.03 / 22.03

  • 管理节点以及工作节点应允许创建特权容器。

  • （可选）GPU节点开启IOMMU。

  • 工作节点无需预装 MXMACA^® 和内核驱动，若已安装也无需处理。

3.1.2. 软件包获取

请通过商务途径获得 cr.metax-tech.com 的访问权限或软件中心下载离线安装包。

• 核心组件包：

  metax-gpu-k8s-package.<VERSION>.tar.gz，解压后应包含：

  • metax-k8s-images.<VERSION>.run：镜像资源包

  • metax-operator-<VERSION>.tgz：Operator Helm Chart

  • metax-gpu-extensions-<VERSION>.tgz：Extensions Helm Chart

• MXMACA^® SDK 镜像包：

  随 MXMACA^® 的发布包发布，例如 maca-native-<VERSION>-<DISTRO>-<ARCH>.container.xz 或者 maca-c500-container-*.xz

• 内核驱动镜像包

  metax-k8s-driver-image.<VERSION>-<ARCH>.run：包含内核态驱动和配套 mx-smi 工具的资源包

本文涉及的软件列表如下，可通过 helm 或 docker 工具从指定 URL 拉取：

类型	制品 URL
Helm Chart	oci://cr.metax-tech.com/cloud/metax-gpu-extensions
Helm Chart	oci://cr.metax-tech.com/cloud/metax-operator
Image	cr.metax-tech.com/cloud/operator-controller
Image	cr.metax-tech.com/cloud/gpu-label
Image	cr.metax-tech.com/cloud/gpu-device
Image	cr.metax-tech.com/cloud/driver-manager
Image	cr.metax-tech.com/cloud/container-runtime
Image	cr.metax-tech.com/cloud/topo-master
Image	cr.metax-tech.com/cloud/topo-worker
Image	cr.metax-tech.com/cloud/gpu-aware

3.1.3. 安装步骤

完成所有准备工作后，请按照以下步骤执行安装。

3.1.3.1. 准备容器镜像仓库和 Helm仓库

为了在集群高效分发资源，建议使用私有镜像仓库。假设仓库地址为 DOMAIN，项目名 PROJECT。

• Docker 登录仓库：

  docker login DOMAIN -u $USER
  

• Helm 登录仓库（仓库需要支持OCI）：

  helm registry login DOMAIN -u $USER
  

备注

在一些规模较小或验证性质的集群中，可能缺失容器仓库服务，管理员可将 metax-k8s-images.<VERSION>.run 分发至集群的所有节点，并直接加载到本地。

3.1.3.2. 推送资源到仓库

将准备阶段获取的镜像资源和 Helm Chart 推送到私有仓库中。

1. 推送核心组件镜像

   • 执行以下命令，将所需的镜像推送到仓库：

     # 默认使用docker进行镜像推送
     ./k8s/metax-k8s-images.<VERSION>.run push DOMAIN/PROJECT
     # 使用nerdctl进行镜像推送
     ./k8s/metax-k8s-images.<VERSION>.run nerdctl push DOMAIN/PROJECT
     

   • （无仓库备选方案）在所有节点执行 load 命令：

     # 默认使用docker进行镜像load
     ./k8s/metax-k8s-images.<VERSION>.run load
     # 使用nerdctl进行镜像load
     ./k8s/metax-k8s-images.<VERSION>.run nerdctl load
     

     备注

     • 自 0.13.0 起，该工具支持多种运行时：docker、nerdctl、ctr。

     • 若未显式指定，默认使用 docker。若主机未安装 docker，系统将自动检测可用运行时并执行镜像推送与load。

     • 使用 nerdctl 或 ctr 加载镜像时，将自动将镜像加载至 k8s.io 命名空间下。

2. 推送 Helm Charts

   • 执行以下命令，将 Helm Chart 推送到仓库：

     helm push ./k8s/metax-gpu-extensions-<VERSION>.tgz oci://DOMAIN/PROJECT
     helm push ./k8s/metax-operator-<VERSION>.tgz oci://DOMAIN/PROJECT
     

   • （无仓库备选方案）无需操作，请妥善保管这两个文件，后续安装将直接使用本地文件。

3. 推送 MXMACA^® SDK 镜像

   • 3.0.0.0及之后版本

     # 加载进行到本地
     $ docker load < maca-native-<VERSION>-<DISTRO>-<ARCH>.container.xz
     # 给镜像重新打tag
     $ docker tag <MACA-IMAGE> <DOMAIN/PROJECT/MACA-IMAGE>
     # 推送镜像到仓库
     $ docker push <DOMAIN/PROJECT/MACA-IMAGE>
     

   • 2.23.0.x 到 3.0.0.0之前版本

     # 加载进行到本地
     $ docker load < mxc500-maca-<VERSION>-<DISTRO>-<ARCH>.container.xz
     # 给镜像重新打tag
     $ docker tag <MACA-IMAGE> <DOMAIN/PROJECT/MACA-IMAGE>
     # 推送镜像到仓库
     $ docker push <DOMAIN/PROJECT/MACA-IMAGE>
     

   • 2.23.0.x及之前版本

     # 加载进行到本地
     $ docker load < maca-c500-container-<VERSION>-<DISTRO>-<ARCH>.xz
     # 给镜像重新打tag
     $ docker tag <MACA-IMAGE> <DOMAIN/PROJECT/MACA-IMAGE>
     # 推送镜像到仓库
     $ docker push <DOMAIN/PROJECT/MACA-IMAGE>
     

4. 推送内核驱动镜像

   执行以下命令推送镜像：

   $ REGISTRY="IMAGE REGISTRY"
   $ chmod a+x metax-k8s-driver-image.<VERSION>-<ARCH>.run
   $ ./metax-k8s-driver-image.<VERSION>-<ARCH>.run push $REGISTRY
   

3.1.3.3. 安装 GPU Operator

在 Kubernetes 管理节点执行以下命令，即可完成 GPU Operator 的安装：

• 从私有仓库进行安装：

  helm install oci://DOMAIN/PROJECT/metax-operator \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait \
  --set registry=DOMAIN/PROJECT
  

• 使用本地 Helm Chart 离线安装：

  helm install ./k8s/metax-operator-<VERSION>.tgz \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait \
  --set registry=DOMAIN/PROJECT
  

3.2. 构建应用镜像

成功安装 GPU Operator 之后，可以开始构建和部署需要使用GPU资源的应用程序。 为了让应用容器可以正确调用 MXMACA^® SDK，需确保容器内包含必要的系统依赖。

3.2.1. 容器内使用 MXMACA^® 环境要求

用户在基于 MXMACA^® 软件栈进行实际作业过程中，需确保容器环境满足以下环境要求：

	Debian系依赖项	Red Hat系依赖项
运行依赖	libltdl7	libtool-ltdl
	libelf	elfutils-libelf
	libnuma	numactl-libs

基于非 MXMACA^® 容器镜像做应用镜像时，需安装SDK运行时依赖，示例Dockerfile如下：

• 在 Debian 系发行版上，使用以下命令安装依赖：

  FROM ubuntu:18.04
  
  RUN apt-get update && apt-get install -y \
  libelf1  \
  libltdl7 \
  libnuma1 \
  ... \
  && rm -rf /var/lib/apt/lists/*
  

• 在 Red Hat 系发行版上，使用以下命令安装依赖：

  FROM centos:8
  
  RUN yum update && yum install -y \
  elfutils-libelf \
  libtool-ltdl \
  numactl-libs \
  ... \
  && yum clean all
  

提示

基于 MXMACA^® 容器镜像做应用镜像时，镜像已提供必要运行时依赖，无需额外安装。

3.3. MinimalMode

3.3.1. 介绍

MinimalMode 是一种专为高级用户和特殊场景设计的轻量级模式。它的核心理念是：只部署必要组件，将节点底层的驱动和用户态环境交由用户全权负责。

在此模式下，系统不会自动管理节点上的内核驱动和 MXMACA^® SDK。这意味着：

• 不会自动安装内核驱动，需要管理员自行准备并安装内核驱动

• 不会自动注入 MXMACA^® SDK

• 适用于特定业务场景，如已有驱动环境或需要手动控制驱动版本

3.3.2. 支持的组件

组件	安装类型
gpu-label	必选
gpu-device	必选
mx-exporter	可选
topo-discovery	可选
gpu-scheduler	可选

3.3.3. 前置准备

在使用MinimalMode前，需手动准备内核驱动和 MXMACA^® SDK，并确保目标节点上已正确安装驱动。驱动安装参见《曦云系列通用GPU驱动安装指南》中“安装驱动”章节。

3.3.3.1. 内核态驱动资源获取安装

请通过商务途径获得驱动资源或软件中心下载离线安装包。此处以通过软件中心下载为例：

1. 在 下载 页面选择 Driver驱动程序，点击 前往下载，依次选择 Linux → 本地部署 → $ARCH → $OS_DISTRO → Runfile安装，下载离线安装包 metax-driver-mxc500-.<VERSION>-<deb/rpm>-<ARCH>.run。

2. 以 2.32.0.6 版本为例，目标工作节点操作系统为x86_64架构的Ubuntu20.04：

   sudo chmod +x metax-driver-mxc500-2.32.0.6-deb-x86_64.run
   sudo ./metax-driver-mxc500-2.32.0.6-deb-x86_64.run -- -f
   
   # 验证安装
   # 在安装完成后需要重启服务器
   reboot
   # 重启服务器后,可以通过以下命令确认驱动是否成功加载,如果看到相关驱动模块列出,说明
   # 安装已成功
   lsmod | egrep "(metax|mxgvm)"
   # 安装 metax-driver,安装过程中将包含四个软件包：
   # metax-driver
   # metax-linux
   # mxsmt
   # mxfw
   
   # 检查已安装包,使用以下命令检查相关包的安装情况：
   dpkg -l | egrep "(metax|mxsmt|mxfw)"
   

3.3.3.2. MXMACA^® SDK 资源获取安装

请通过商务途径获得驱动资源或软件中心下载离线安装包。此处以通过软件中心下载为例：

1. 在 下载 页面选择 SDK开发工具包，点击 前往下载，依次选择 Linux → 本地部署 → $ARCH → $OS_DISTRO → 本地安装，下载离线安装包 maca-sdk-mxc500-.<VERSION>-<deb/rpm>-<ARCH>.tar.xz。

2. 以 2.32.0.6 版本为例，目标工作节点操作系统为x86_64架构的Ubuntu20.04：

   # 获取MXMACA SDK的tar安装包 maca-sdk-mxc500-2.32.0.6-deb-x86_64.tar.xz，解压后可以看到 mxmaca-sdk-install.sh、version_compatible_check.sh、appimage、deb 等子目录。将安装包放入目标服务器，包内基础文件如下所示。
   
   # ├── appimage
   # ├── deb
   # ├── mxmaca-sdk-install.sh
   # └── version_compatible_check.sh
   
   # 获取metax驱动安装包 metax-driver-mxc500-2.32.0.6-deb-x86_64.run。将安装包放入目标服务器。
   
   # 执行以下命令，安装MXMACA编程环境。
   
   cd mxc500-2.32.0.6 #(MXMACA SDK解压目录)
   sudo ./mxmaca-sdk-install.sh -f
   
   # 安装成功后的目录如下所示。
   root@device-01:/opt/maca$ tree -L 1
   # .
   # ├── bin
   # ├── etc
   # ├── ffmpeg
   # ├── include
   # ├── lib
   # ├── mxgpu_llvm
   # ├── ompi
   # ├── samples
   # ├── share
   # ├── tools
   # ├── ucx
   # ├── Version.txt
   # └── wheel
   

3.3.4. MinimalMode安装

在 Kubernetes 管理节点执行以下命令，即可完成 GPU Operator MinimalMode的安装：

# 在线安装
helm install oci://DOMAIN/PROJECT/metax-operator \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=DOMAIN/PROJECT \
--set minimalMode=true

备注

• 必须部署且不应该关闭的组件： gpu-label 和 gpu-device

• MinimalMode仅在安装时可选，运行中无法动态切换

3.4. 卸载

3.4.1. 卸载 GPU Operator

卸载 GPU Operator 时，需谨慎操作，以免影响其他关联系统组件或业务运行。卸载步骤如下：

1. 停止作业

   停止所有依赖 GPU Operator 的应用程序，释放 GPU 资源。

2. 卸载 Helm Chart

   helm uninstall [RELEASE_NAME] -n metax-operator --wait  # [RELEASE_NAME] 为安装时生成的名称（如 metax-operator-1620000000）
   

   也可直接运行以下脚本自动检查已安装的 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 参数为必选项，不可省略。

3. （可选）清理 CRD(自定义资源定义)

   若需完全清理资源，执行以下命令：

   kubectl delete crd clusteroperators.gpu.metax-tech.com
   

   备注

   卸载后，若需重新安装，需确保集群环境和资源（镜像、Chart）已重新准备。

3.4.2. 卸载异常

若软件卸载时出现异常，参见 5.3.1 卸载异常处理。

3.5. 更新

3.5.1. GPU Operator 版本更新

在更新 GPU Operator 之前，请务必确认当前系统环境与目标版本的兼容性，备份关键配置文及数据，避免更新过程中出现数据丢失或服务中断。更新操作可通过以下步骤进行。

1. 停止作业

   停止所有依赖 GPU Operator 的应用程序，释放 GPU 资源。

2. 执行更新安装

   假设在已经运行名为 <release_name> GPU Operator release的情况下将 GPU Operator Helm Chart更新至version为 <desired-version> 的新版本。

   • 仅升级新版本镜像，保留旧版本运行参数不变。

     #使用本地包
     helm upgrade <release_name> metax-operator-<desired-version>.tgz \
     -n metax-operator
     
     #使用oci仓库
     helm upgrade <release_name> oci://DOMAIN/PROJECT/metax-operator \
     -n metax-operator --version <desired-version>
     

   • 升级新版本镜像，更新部分参数，未指定的参数保持不变。

     #使用本地包
     helm upgrade <release_name> metax-operator-<desired-version>.tgz \
     -n metax-operator --reuse-values --set key1=values1 --set ...
     
     #使用oci仓库
     helm upgrade <release_name> oci://DOMAIN/PROJECT/metax-operator \
     -n metax-operator --version <desired-version> \
     --reuse-values --set key1=values1 --set ...
     

   • 升级新版本镜像，丢弃旧版本参数并重新配置参数。

     #使用本地包
     helm upgrade <release_name> metax-operator-<desired-version>.tgz \
     -n metax-operator --reset-values --set key1=values1 ...
     
     #使用oci仓库
     helm upgrade <release_name> oci://DOMAIN/PROJECT/metax-operator \
     -n metax-operator --version <desired-version> \
     --reset-values --set key1=values1 ...
     

     通过命令行指定的参数会覆盖掉chart包中指定的参数。

   备注

   必须在新版Operator的CRD兼容旧版本的情况下才能使用 helm upgrade 进行升级。 当CRD不兼容时，需要手动卸载旧版本Oprerator、CRD，再安装新版本。

3. 验证状态

   # 检查 Pods 运行状态
   kubectl get pods -n metax-operator
   
   # 检查 Node metax相关标签状态
   kubectl describe node $NODE_NAME
   

3.5.2. 动态更新 GPU Operator 配置参数

GPU Operator 支持通过CR(自定义资源)动态调整运行时参数，无需重启服务即可生效。以下为通过 kubectl edit 命令修改 ClusterOperator 资源的操作指南，适用于按需优化资源调度、设备管理等场景。

3.5.2.1. 操作步骤

1. 查看当前配置

   首先获取 ClusterOperator 资源的当前配置，确认参数路径：

   kubectl get clusteroperators.gpu.metax-tech.com <cluster-operator-resource-name> -o yaml
   

   将 <cluster-operator-resource-name> 替换为实际资源名称，如 cluster-operator

2. 进入编辑模式

   使用 kubectl edit 命令打开 CR 配置文件，修改目标参数：

   kubectl edit clusteroperators.gpu.metax-tech.com <cluster-operator-resource-name>
   

   • 编辑器默认使用 vi，可通过环境变量 KUBE_EDITOR 指定其他编辑器（如 nano）

   • 文件中 spec 字段下包含可配置的参数组，根据需求定位至对应字段

3. 修改参数值

   在 spec 中找到需调整的参数，按 YAML 格式更新值。以下为常见参数类型及修改示例（结合参数列表），具体的CRD定义参见 3.6 参数介绍：

   spec:
     gpuDevice:
       deploy: true
       healthyInterval: 10  # 修改健康检查间隔为10秒
     driver:
       deployPolicy: PreferCloud
       payload:
         version: "2.32.0.6"  # 指定驱动版本
   

   备注

   以上参数需根据实际支持的参数列表调整，示例字段需与 CRD 定义一致。

4. 保存并应用修改

   编辑完成后保存文件，Kubernetes 将自动更新 ClusterOperator 资源，参数实时生效（部分配置可能需等待控制器 reconciliation）。

3.6. 参数介绍

3.6.1. 设置Chart选项

GPU Operator Chart安装时可通过 --set option=value 的方式改变选项默认设置。 对于结构体类型选项，配置其成员选项时使用 . 字符连接。 例如，指定 --set gpuLabel.log.format=text 参数，设置gpu-label组件使用 text 日志格式。

更多选项，参见下方表格:

表 3.1 Global Options

选项	类型	描述
gpuDevice	struct	gpu-device组件选项，参见 表 3.2
gpuLabel	struct	gpu-label组件选项，参见 表 3.3
openshift	struct	OpenShift平台相关选项，用于配置OpenShift安全上下文约束(SCC)，参见 表 3.24
driver	struct	driver组件内核态驱动控制选项，参见 表 3.4，灰度升级参见 表 3.9
maca	struct	maca组件选项， 参见 表 3.6
runtime	struct	container-runtime组件选项，参见 表 3.7
dataExporter	struct	data-exporter组件选项，参见 表 3.11
topoDiscovery	struct	topo-discovery组件选项，参见 表 3.13
gpuScheduler	struct	gpu-scheduler组件选项，参见 表 3.18
podTemplateSpec	struct	全局工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。目前仅支持 NodeSelector、 Affinity 和 Tolerations，参见 表 3.22

表 3.2 gpu-device Options

选项	类型	描述
healthyInterval	integer	GPU健康检查间隔的秒数，＞0 时启用功能，＝0 时禁用功能，默认值为5
connectDetectPeriod	string	和Kubelet组件的连接探测周期，＞0s 时启用功能，＝0s 时禁用功能，默认值为 0s。配置格式为时间周期，例如 10s 表示10秒，20m 表示20分钟。
deploy	bool	是否启用组件，默认为 true，可选 false
log	struct	日志选项，参见 表 3.21
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 表 3.22
sGPUHybridMode	bool	是否启用sGPUHybrid模式，启用后所有沐曦GPU都会启用GPU共享功能，并注册为 metax-tech.com/sgpu 资源。仅支持Helm安装时设置。 默认为 false，可选 true

表 3.3 gpu-label Options

选项	类型	描述
deploy	bool	是否启用组件，默认为 true，可选 false
log	struct	日志选项，参见 表 3.21
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 表 3.22

表 3.4 Kernel Module Control Options

选项	类型	描述
deployPolicy	enum	资源部署策略，默认为 PreferCloud，可选 PreferHost 和 PreferNewer，参见 表 3.5
payload	struct	内核驱动控制资源包选项，参见 表 3.8
fwUpgradePolicy	enum	固件升级策略，默认为 Never，可选 PreferCloud 和 Never， 参见 表 4.6 Driver Firmware Upgrade Options
fwEnableVirt	bool	是否使用虚拟化固件，默认为 false，可选 false， 参见 表 4.7 Driver Firmware Virt Options
deploy	bool	是否启用组件，默认为 true，可选 false
log	struct	日志选项，参见 表 3.21
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 表 3.22
deviceAsRootGroup	bool	容器内使用的GPU设备是否设置为root组权限。默认为 false, 可选 true

表 3.5 Driver Deploy Policy Options

选项	描述
PreferCloud	使用payload镜像中的内核驱动
PreferHost	优先使用主机上的内核驱动，如果不存在，则使用payload镜像中的内核驱动
PreferNewer	如果主机上的内核驱动版本高于payload镜像中的驱动版本，使用主机上的内核驱动，否则使用payload镜像中的内核驱动

表 3.6 MXMACA Control Options

选项	类型	描述
payload	struct	MXMACA® 控制资源包选项，参见 表 3.10
deploy	bool	是否启用组件，默认为 true，可选 false
log	struct	日志选项，参见 表 3.21
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 表 3.22

表 3.7 Container Runtime Options

选项	类型	描述
deploy	bool	是否启用组件，默认为 true，可选 false
log	struct	日志选项，参见 表 3.21
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 表 3.22

表 3.8 Driver Payload Options

选项	类型	描述
name	string	payload镜像名，默认值为 driver-image
version	string	payload镜像版本，若 driver.deploy 的值为 true，需显式指定
registry	string	payload镜像地址，默认使用全局选项 registry 的值

表 3.9 Driver Upgrade Options (driver.upgradePolicy)

选项	类型	描述
enableRollout	bool	是否开启内核态驱动灰度发布升级，默认为 false ，可选 true
upgradeSteps[].replicas	integer or percentage	该升级批次完成后Pod为新版本的副本数量
upgradeSteps[].pauseDuration	time	定义升级完成后暂停阶段的行为。默认为空，系统自动暂停。管理员手动设置 upgradePolicy.pause 为 false 后，系统会自动进入下一升级阶段。如果设定超时时间，等超时时间达到，系统自动进入下一升级阶段
upgradeSteps[].toleration	integer or percentage	当前升级批次允许失败节点个数，默认为 0%
pause	bool	是否暂停灰度发布升级，默认为 false ，可选 true
maxParallel	integer or percentage	最大并行升级节点数量，默认为 100%。 0 为不设限制，一次性升级所有可用节点，当使用百分比时，系统会自动向上取整到整数
maxUnavailable	integer or percentage	本次灰度发布结束时允许节点不可用（升级失败）的数量，默认为 0%。所有参与升级的节点均需要升级到目标版本
maxFailureThreshold	integer	每批次最大错误重试次数，默认为 0
fallback	string	每批次升级遇到操作异常或者升级失败节点超过 upgradeSteps[].toleration 时，被视为一次失败，达到最大错误重试次数时，系统会执行相应的降级操作（暂停和回滚），默认为 pause，可选为 rollback

表 3.10 MXMACA Payload Options

选项	类型	描述
images	string list	payload镜像列表， 格式为 {IMAGE_1， IMAGE2， ...}， 其中 IMAGE 应使用完整格式显式指定tag，如 maca-native:3.2.1.4-ubuntu20.04-amd64
registry	string	payload镜像地址，默认使用全局选项 registry 的值

表 3.11 Data Exporter Options

选项	类型	描述
deploy	bool	是否启用exporter组件，默认 false，可选 false
service	struct	服务启动配置，参见 表 3.12
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 表 3.22

表 3.12 Exporter Service Options

选项	类型	描述
type	enum	服务类型，默认为 ClusterIP，可选 NodePort， LoadBalancer 和 ExternalName
port	integer	服务端口号，仅在 type 为 NodePort 和 LoadBalancer 时可用

表 3.13 Topo Discovery Options

选项	类型	描述
deploy	bool	是否启用拓扑组件，默认 false，可选 false，为 true 时会部署topo-master和topo-worker组件
mode	string	拓扑组件的运行模式，默认为 config，可选 dragonfly 和 switchbox
dragonfly	struct	dragonfly模式选项，参见 表 3.14
switchbox	struct	switchbox模式选项，参见 表 3.15
rpcServerPort	integer	rpc服务端口号
master	struct	topo-master选项配置，参见 表 3.16
worker	struct	topo-worker选项配置，参见 表 3.17

表 3.14 topoDiscovery Dragonfly Options

选项	类型	描述
nodeNumber	integer	一个节点组中节点的数量，默认为 2，可选 4
enableTraining	bool	是否开启节点自动Training功能，默认为 false

表 3.15 topoDiscovery Switchbox Options

选项	类型	描述
clusterManagerAddress	string	cluster manager服务的地址，必填项
clusterManagerUser	string	登录cluster manager服务的用户名，需要使用base64编码，必填项
clusterManagerPassword	string	登录cluster manager服务的密码，需要使用base64编码，必填项
clusterManagerPollTopoPeriod	int	轮询cluster manager拓扑信息的时间间隔，单位为秒，默认为30秒
clusterManagerPollEventPeriod	int	轮询cluster manager告警事件的时间间隔，单位为秒，默认为10秒

表 3.16 TopoDiscovery Master Options

选项	类型	描述
image	struct	镜像选项，参见 表 3.23
log	struct	日志选项，参见 表 3.21
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 表 3.22
Env	struct	环境选项，参考Kubernetes 原生环境结构体定义
ServerPort	integer	Topo-Master 服务端口

表 3.17 TopoDiscovery Worker Options

选项	类型	描述
image	struct	镜像选项，参见 表 3.23
log	struct	日志选项，参见 表 3.21
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见 表 3.22
MetricsPort	integer	Metrics 服务端口

表 3.18 GPU Scheduler Options

选项	类型	描述
deploy	bool	是否启用组件，默认为 true，可选 和 false
kubeScheduler	struct	kubernetes scheduler配置，参见 表 3.19
gpuAware	struct	gpu aware配置，参见 表 3.20

表 3.19 Kube Scheduler Options

选项	类型	描述
image	struct	镜像选项，参见 表 3.23，如果为空，会默认使用当前集群的调度器镜像

表 3.20 GPU Aware Options

选项	类型	描述
image	struct	镜像选项，参见 表 3.23

表 3.21 Log Options

选项	类型	描述
dir	string	日志文件存储目录，默认为 /var/log/metax
level	enum	日志级别，默认为 info，可选 debug， warning， error， fatal
format	enum	日志格式，默认为 json，可选 text
rotationTime	string	日志轮替时间，默认为 1w，可选单位为 w (星期)， d (日)， h (小时)
maxAge	string	日志保存的最长时间，默认为 26w，可选单位为 w (星期)， d (日)， h (小时)

表 3.22 Custom Pod Template Spec Options

选项	类型	描述
spec.nodeSelector	struct	指定 Pod 调度所需的节点标签匹配规则
spec.affinity	struct	配置 Pod 与节点的亲和性/反亲和性调度策略
spec.tolerations	struct	定义 Pod 对节点污点的容忍规则，允许调度到特定节点

表 3.23 Container Image Options

选项	类型	描述
registry	string	镜像仓库地址（含域名与项目路径），格式为 <域名>/<项目名>
pullPolicy	string	镜像拉取策略，控制 Kubernetes 何时从仓库拉取镜像。可选： Always （每次强制拉取）、 IfNotPresent （本地无镜像时拉取，默认）、 Never （仅使用本地镜像）
name	string	镜像名称（不含仓库地址与版本标签）
version	string	镜像版本标签或哈希值

表 3.24 OpenShift Options

选项	类型	描述
enabled	bool	是否启用OpenShift平台支持，默认为 false，可选 true。启用后，系统将自动配置OpenShift安全上下文约束(SCC)，确保GPU工作负载在OpenShift环境中正常运行

3.6.2. 典型场景配置示例

以下展示几种典型使用场景的配置示例，包括安装命令和参数配置。

3.6.2.1. 场景一：指定 MXMACA^® 版本安装

安装时指定特定 MXMACA^® 版本，适用于需要特定SDK版本的场景：

# 安装并指定maca版本为3.2.1.4
helm install oci://cr.metax-tech.com/cloud/metax-operator \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=cr.metax-tech.com/cloud \
--set maca.payload.images[0]="maca-native:3.2.1.4-ubuntu20.04-amd64"

3.6.2.2. 场景二：多 MXMACA^® 版本配置

配置多个 MXMACA^® 版本，适用于需要支持多个SDK版本的场景：

# 安装并配置多个maca版本
helm install oci://cr.metax-tech.com/cloud/metax-operator \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=cr.metax-tech.com/cloud \
--set maca.payload.images[0]="maca-native:3.2.1.4-ubuntu20.04-amd64" \
--set maca.payload.images[1]="maca-c500:2.33.0.6-ubuntu20.04-amd64"

3.6.2.3. 场景三：指定驱动版本安装

安装时指定特定驱动版本，适用于需要特定驱动版本的场景：

# 安装并指定驱动版本为2.32.0.6
helm install oci://cr.metax-tech.com/cloud/metax-operator \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=cr.metax-tech.com/cloud \
--set driver.payload.version="2.32.0.6-amd64"

3.6.2.4. 场景四：OpenShift平台安装

在OpenShift平台上安装时，需要启用OpenShift支持以确保GPU工作负载正常运行：

# 在OpenShift平台上安装并启用SCC配置
helm install oci://cr.metax-tech.com/cloud/metax-operator \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=cr.metax-tech.com/cloud \
--set openshift.enabled=true