MOFFETT SPU Operator 用户手册

MOFFETT SPU（Sparse Processing Unit，稀疏处理单元）Operator 基于 Kubernetes Operator Framework，实现对以下组件的统一部署与生命周期管理：

• SOLA 驱动

• Container Toolkit

• Device Plugin

• DCSM（Data Center SPU Manager）Exporter

如需单独部署及管理 Container Toolkit、Device Plugin 或 DCSM Exporter，详见《MOFFETT Container Toolkit 用户手册》、《MOFFETT Device Plugin 用户手册》或《DCSM Exporter 用户手册》。

准备环境

在部署 SPU Operator 之前，确保满足以下系统及工具要求：

• 部署可用的 Kubernetes 集群，详见 使用部署工具安装 Kubernetes。

• 安装 Kubernetes 命令行工具 kubectl，详见 安装工具 - kubectl。

• 安装 Helm，详见 Installing Helm。

部署

获取安装包

S4/S30/S40/S40ACS40Lite

wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.11/spu-operator/spu-operator-v1.2.0.tgz

默认部署

S4/S30/S40/S40ACS40Lite

helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.2.0.tgz

自定义部署

SPU Operator 支持通过 Helm 自定义参数选择以下任一方式安装，其中各配置项说明详见配置参考。

• 使用 --set 配置参数

  S4/S30/S40/S40ACS40Lite

  helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.2.0.tgz --set <option-name>=<option-value>
  

• 使用 values.yaml 配置

  S4/S30/S40/S40ACS40Lite

  helm show values spu-operator-v1.2.0.tgz > values.yaml # 导出默认配置文件
  vim values.yaml # 修改参数配置
  helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.2.0.tgz -f values.yaml
  

  须知

  请保留此 values.yaml 文件，后续更新配置时可直接复用。

常见部署场景

以下部署场景适用于包含 SPU 节点的 Kubernetes 集群。

禁止在部分节点部署全部组件

默认情况下，SPU Operator 会在所有检测到 SPU 的工作节点上部署全部运行组件。若需排除特定节点，为该节点设置以下标签：

kubectl label nodes <node> moffett.ai/spu.deploy.operands=false --overwrite

该标签可在执行 helm install 前设置，以跳过该节点的初始部署；也可在部署完成后设置，SPU Operator 将自动移除该节点上的全部组件。将标签值改回 true 可恢复部署。

如需单独控制特定组件在某节点的部署，可使用对应的组件级标签，详见节点标签。可执行以下命令查询节点上的标签信息：

kubectl get node                 # 查看节点 NAME
kubectl describe node <name>     # 查看 Labels 字段下的标签信息

节点已预装 SOLA 驱动

若集群中所有节点均已通过主机方式安装 SOLA Toolkit，驱动生命周期由外部管理，可在安装时通过 --set 参数禁用 Operator 的驱动部署：

S4/S30/S40/S40ACS40Lite

helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.2.0.tgz --set driver.enabled=false

须知

对于混合集群（部分节点已手动预装主机驱动），无需为这些节点单独设置节点标签。driver.enabled 默认为 true，k8s-driver-manager 在部署阶段会自动检测节点上已安装的主机驱动，并跳过该节点的容器化驱动部署。详见升级 SOLA 驱动。

部署后验证

SPU Operator 部署完成后，检查其组件是否成功运行。

须知

受网络环境影响，组件 Pod 可能需要一定时间才能进入 Running 状态。

kubectl get pod -n moffett-spu-operator # 当 Pod 的 STATUS = Running（READY = 1/1）时，表示正常启动

升级

本节适用于升级 SPU Operator Helm Chart 版本，或升级通过 SPU Operator 部署的容器化 SOLA 驱动版本的场景。

升级 SPU Operator 版本

SPU Operator 支持使用 Helm Hook 自动升级 CRD（operator.upgradeCRD 默认启用），步骤如下：

1. 获取新版本 Helm Chart 包。

   S4/S30/S40/S40ACS40Lite

   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.11/spu-operator/spu-operator-<new_operator_version>.tgz # <new_operator_version> 替换为实际的目标版本号
   

2. 执行升级。

   S4/S30/S40/S40ACS40Lite

   helm upgrade spu-operator spu-operator-<new_operator_version>.tgz -n moffett-spu-operator
   

升级 SOLA 驱动

SPU Operator 通过 k8s-driver-manager initContainer 管理容器化 SOLA 驱动的完整生命周期。升级时，k8s-driver-manager 会依次驱逐使用 SPU 的业务 Pod，完成旧驱动卸载，并在新驱动容器部署完成后恢复 SPU Operator 和业务 Pod 的调度。

以下步骤仅适用于通过 SPU Operator 部署的容器化 SOLA 驱动。若节点采用主机方式预装驱动，请参考《SOLA Toolkit 安装指南》手动升级。

升级容器化 SOLA 驱动的操作步骤如下：

1. 修改 values.yaml 中 SOLA 驱动版本。

   driver:
     version: <driver-version>
   

2. 执行 helm upgrade 将变更推送至集群。

   S4/S30/S40/S40ACS40Lite

   helm upgrade spu-operator spu-operator-<current_operator_version>.tgz -n moffett-spu-operator -f values.yaml
   

3. 手动删除当前 SOLA 驱动的 Pod，触发新版本驱动拉起。

   kubectl get node # 查看集群中的节点 NAME
   kubectl delete pod -l app=moffett-driver-daemonset --field-selector spec.nodeName=<NAME> -n moffett-spu-operator
   

   删除 SOLA 当前驱动后，需等待一段时间加载新驱动及其他组件。

4. （可选）查看新 SOLA 驱动 Pod 的实时部署状态。

   kubectl get pod -l app=moffett-driver-daemonset -n moffett-spu-operator -w
   

更新配置

本节适用于不变更 SPU Operator 版本、仅调整配置项的场景。

1. 确认自定义部署时使用 values.yaml 配置保存的 values.yaml，并准备当前版本的 Helm Chart 包。

2. 修改需要变更的配置项（详见配置参考）。

   vim values.yaml
   

3. 应用变更。

   S4/S30/S40/S40ACS40Lite

   helm upgrade spu-operator spu-operator-<current_operator_version>.tgz -n moffett-spu-operator --disable-openapi-validation -f values.yaml
   

   须知

   当 operator.upgradeCRD 启用时，为避免 Helm 以旧版本 CRD 校验新的 CR 实例，需使用 --disable-openapi-validation 选项跳过 Helm 的本地校验，让 Kubernetes 在新 CRD 生效后完成正确校验。

4. 验证更新结果。

   helm list -n moffett-spu-operator
   kubectl get pod -n moffett-spu-operator # 当 Pod 的 STATUS = Running（READY = 1/1）时，表示正常启动
   

   如需按组件进一步确认，可结合标签查看对应组件 Pod 状态，例如：

   kubectl get pod -l app=moffett-driver-daemonset -n moffett-spu-operator
   kubectl get pod -l app=moffett-device-plugin -n moffett-spu-operator
   kubectl get pod -l app=moffett-dcsm-exporter -n moffett-spu-operator
   

自定义 DCSM 指标

SPU Operator 部署的 DCSM Exporter 提供默认采集指标，详见《DCSM Exporter 用户手册》中的可用 DCSM 字段参考。如需采集自定义指标，可通过以下两种方式配置 ConfigMap，配置完成后执行 helm upgrade 使变更生效。

准备自定义指标文件

从当前运行的 dcsm-exporter Pod 中导出默认指标文件，再按需修改：

POD=$(kubectl get pod -n moffett-spu-operator -l app=moffett-dcsm-exporter -o jsonpath='{.items[0].metadata.name}')
kubectl cp moffett-spu-operator/$POD:/etc/dcsm-exporter/default-counters.csv ./dcsm-metrics.csv

编辑 dcsm-metrics.csv，删除不需要的字段或追加需要采集的字段。CSV 文件的字段格式为：DCSM字段名, 类型(gauge/counter/label), 描述。DCSM 字段的详细说明，参见《DCSM Exporter 用户手册》中的可用 DCSM 字段参考。

配置 ConfigMap

以下两种方式二选一，相关配置项详见 DCSM Exporter 配置。

• 方法一：通过文件创建独立 ConfigMap

  1. 使用 dcsm-metrics.csv 创建 ConfigMap（名称需与 dcsmExporter.config.name 一致，默认为 custom-dcsm-exporter-metrics）。如需更新，重复执行以下命令即可。

     kubectl create configmap custom-dcsm-exporter-metrics \
       --from-file=dcsm-metrics.csv \
       -n moffett-spu-operator \
       --dry-run=client -o yaml | kubectl apply -f -
     

  2. 在 values.yaml 中设置指标文件路径并声明引用该 ConfigMap（create: false）。

     dcsmExporter:
       env:
         - name: DCSM_EXPORTER_COLLECTORS
           value: "/etc/dcsm-exporter/dcsm-metrics.csv"
       config:
         name: custom-dcsm-exporter-metrics
         create: false
     

• 方法二：在 values.yaml 中定义指标内容

  在 values.yaml 的 dcsmExporter 段，将 DCSM_EXPORTER_COLLECTORS 指向 /etc/dcsm-exporter/dcsm-metrics.csv，并在 config.data 中填入完整的 CSV 内容。Helm 将自动创建 ConfigMap 并挂载至容器。

  dcsmExporter:
    env:
      - name: DCSM_EXPORTER_COLLECTORS
        value: "/etc/dcsm-exporter/dcsm-metrics.csv"
    config:
      name: custom-dcsm-exporter-metrics
      create: true
      data: |-
        # DCSM FIELD, Prometheus metric type, help message
  
        # Temperature
        DCSM_FI_DEV_SPU_TEMP, gauge, SPU temperature (in C).
  
        # Power
        DCSM_FI_DEV_POWER_USAGE, gauge, Power draw (in W).
  
        # Static configuration information. These appear as labels on the other metrics
        DCSM_FI_DEV_SERIAL,     label, Device Serial Number
        DCSM_FI_DRIVER_VERSION, label, Driver Version
  

应用变更

S4/S30/S40/S40ACS40Lite

helm upgrade spu-operator spu-operator-<current_operator_version>.tgz -n moffett-spu-operator -f values.yaml

• 方法一：升级完成后，DaemonSet 完成滚动重启后新配置生效（ConfigMap 已在升级前创建）。

• 方法二：升级完成后，Helm 自动创建 ConfigMap，DaemonSet 完成滚动重启后新配置生效。

验证

确认 CSV 文件已挂载到 Pod，输出内容与自定义指标文件一致。

POD=$(kubectl get pod -n moffett-spu-operator -l app=moffett-dcsm-exporter -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n moffett-spu-operator $POD -- cat /etc/dcsm-exporter/dcsm-metrics.csv

须知

Prometheus 按配置的抓取间隔采集数据，变更后需等待一个采集周期后方可在 Prometheus 中查询到新指标。

卸载

1. 卸载 SPU Operator。

   helm list -n moffett-spu-operator # 查看部署的 helm release NAME
   helm uninstall <NAME> -n moffett-spu-operator
   

2. （可选）如未启用自动清理（operator.cleanupCRD: false 默认关闭），手动删除 CRD。

   kubectl delete crd clusterpolicies.moffettai.com
   

3. 删除 namespace。

   kubectl delete ns moffett-spu-operator
   

4. 验证卸载结果。

   kubectl get all -A | grep spu-operator
   kubectl get ns | grep moffett-spu-operator
   

配置参考

以下表格列出了常用配置项。

Operator 全局配置

配置项	描述	默认值
nfd.enabled	是否启用 NFD。	true
operator.repository	SPU Operator 镜像仓库。	moffett
operator.image	SPU Operator 镜像名。	spu-operator
operator.version	SPU Operator 镜像版本。	未指定，默认使用 chart.AppVersion。
operator.imagePullPolicy	镜像拉取策略。	IfNotPresent
operator.imagePullSecrets	镜像拉取密钥名称（如果镜像仓库需要凭据）。 创建密钥的操作参见从私有仓库拉取镜像。	[]
operator.cleanupCRD	卸载时是否清理 CRD 资源。	false
operator.upgradeCRD	升级时是否自动升级 CRD 资源。	true

Driver 配置

配置项	描述	默认值
driver.enabled	是否通过 SPU Operator 安装 SOLA 驱动。 true 适用于节点上未安装 SOLA Toolkit 的场景；false 适用于节点上已安装 SOLA Toolkit 的场景。	true
driver.repository	SOLA 驱动镜像仓库。	moffett
driver.image	SOLA 驱动镜像名。	S4/S30/S40/S40AC：driver S40Lite：driver-lite
driver.version	SOLA 驱动镜像版本。	S4/S30/S40/S40AC：3.13.0-ubuntu22.04 S40Lite：3.15.0-ubuntu22.04
driver.imagePullPolicy	SOLA 驱动镜像拉取策略。	IfNotPresent
driver.imagePullSecrets	镜像拉取密钥名称（如果镜像仓库需要凭据）。 创建密钥的操作参见从私有仓库拉取镜像。	[]
driver.manager.env	k8s-driver-manager 环境变量。可用于配置控制驱动升级过程中 Pod 的驱逐（Eviction）行为以及节点排空（Drain）策略。	详见下表

k8s-driver-manager 环境变量	描述	默认值
ENABLE_SPU_POD_EVICTION	尝试驱逐节点的 SPU Pod。如果驱逐失败，且同时启用了 ENABLE_AUTO_DRAIN，对节点执行排空操作。	true
ENABLE_AUTO_DRAIN	当 SPU Pod 驱逐失败时，允许自动执行节点排空操作。	false
DRAIN_USE_FORCE	在节点排空过程中，强制驱逐未被任何副本控制器（Deployment、ReplicaSet、StatefulSet、DaemonSet）管理的 SPU Pod。	false
DRAIN_POD_SELECTOR_LABEL	为 SPU Pod 指定一个标签，在节点排空时驱逐带有该标签的 SPU Pod。	""
DRAIN_TIMEOUT_SECONDS	节点排空操作的超时时间（单位：秒）。超时后，强制删除 SPU Pod 以执行排空操作。	0s（表示无超时限制）
DRAIN_DELETE_EMPTYDIR_DATA	删除使用 emptyDir 卷的 SPU Pod。	false

Container Toolkit 配置

配置项	描述	默认值
toolkit.enabled	是否通过 SPU Operator 安装 Container Toolkit。 true 适用于节点上未安装 Container Toolkit 的场景；false 适用于节点上已安装 Container Toolkit 的场景。	true
toolkit.repository	Container Toolkit 镜像仓库。	moffett
toolkit.image	Container Toolkit 镜像名。	container-toolkit
toolkit.version	Container Toolkit 镜像版本。	v1.2.0
toolkit.imagePullPolicy	Container Toolkit 镜像拉取策略。	IfNotPresent
toolkit.imagePullSecrets	镜像拉取密钥名称（如果镜像仓库需要凭据）。 创建密钥的操作参见从私有仓库拉取镜像。	[]

Device Plugin 配置

配置项	描述	默认值
devicePlugin.enabled	是否部署 Device Plugin。	true
devicePlugin.repository	Device Plugin 镜像仓库。	moffett
devicePlugin.image	Device Plugin 镜像名。	k8s-device-plugin
devicePlugin.version	Device Plugin 镜像版本。	S4/S30/S40/S40AC：v0.3.0 S40Lite：v0.3.0-lite
devicePlugin.imagePullPolicy	Device Plugin 镜像拉取策略。	IfNotPresent
devicePlugin.imagePullSecrets	镜像拉取密钥名称（如果镜像仓库需要凭据）。 创建密钥的操作参见从私有仓库拉取镜像。	[]

DCSM Exporter 配置

配置项	描述	默认值
dcsmExporter.enabled	是否部署 DCSM Exporter。	true
dcsmExporter.repository	DCSM Exporter 镜像仓库。	moffett
dcsmExporter.image	DCSM Exporter 镜像名。	S4/S30/S40/S40AC：dcsm-exporter S40Lite：dcsm-lite-exporter
dcsmExporter.version	DCSM Exporter 镜像版本。	1.2.0-1.0.0
dcsmExporter.imagePullPolicy	DCSM Exporter 镜像拉取策略。	IfNotPresent
dcsmExporter.imagePullSecrets	镜像拉取密钥名称（如果镜像仓库需要凭据）。 创建密钥的操作参见从私有仓库拉取镜像。	[]
dcsmExporter.env	DCSM Exporter 环境变量。可用于指定 DCSM Exporter 监听的地址与端口、指标采集配置文件路径等。	详见下表
dcsmExporter.config.name	自定义指标 ConfigMap 名称。	custom-dcsm-exporter-metrics
dcsmExporter.config.create	是否由 Helm 自动创建 ConfigMap。设为 false 时，需在部署前手动创建同名 ConfigMap。	false
dcsmExporter.config.data	ConfigMap 中的指标内容（CSV 格式）。当 config.create: true 时生效，Helm 将以此内容创建 ConfigMap。	""
dcsmExporter.serviceMonitor.enabled	是否启用 ServiceMonitor。 使用 Prometheus Operator 时将此参数设置为true。	false
dcsmExporter.serviceMonitor.interval	Prometheus 抓取间隔。	15s

DCSM Exporter 环境变量	描述	默认值
DCSM_EXPORTER_LISTEN	DCSM Exporter 对外提供指标服务的监听端口。	:7788
DCSM_EXPORTER_KUBERNETES	DCSM Exporter 以 Kubernetes 集群模式运行。	true
DCSM_EXPORTER_COLLECTORS	DCSM Exporter 启用的指标采集配置文件路径。	/etc/dcsm-exporter/default-counters.csv

节点标签

以下标签用于控制 SPU Operator 在特定节点上的组件部署行为。标签可在 helm install 前预先设置（跳过初始部署），也可在部署后设置（Operator 将自动移除对应组件）。将标签值改回 true 可恢复部署。

标签	描述
moffett.ai/spu.deploy.operands=false	禁止在该节点部署全部组件。
moffett.ai/spu.deploy.driver=false	禁止在该节点通过镜像安装 SOLA 驱动。
moffett.ai/spu.deploy.container-toolkit=false	禁止在该节点部署 Container Toolkit。
moffett.ai/spu.deploy.device-plugin=false	禁止在该节点部署 Device Plugin。
moffett.ai/spu.deploy.dcsm-exporter=false	禁止在该节点部署 DCSM Exporter。