MOFFETT SPU Operator 用户手册

MOFFETT SPU Operator 基于 Kubernetes Operator Framework，实现对以下组件的统一部署与生命周期管理：

SOLA 驱动
Container Toolkit
Device Plugin
DCSM Exporter

如需单独部署及管理 Container Toolkit、Device Plugin 或 DCSM Exporter，请参见本手册最后列出的相关组件的用户手册。

准备环境

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

部署可用的 Kubernetes 集群，具体请参见使用部署工具安装 Kubernetes。
安装 Kubernetes 命令行工具 kubectl，具体请参见安装工具 - kubectl。
安装 Helm，具体请参见 Installing Helm。

快速开始

获取 Helm Chart 包。

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

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

安装 SPU Operator（默认配置）。

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

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

自定义部署

SPU Operator 支持通过 Helm 自定义参数选择以下任一方式安装。

使用 --set 配置参数

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

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

使用 values.yaml 配置

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

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

配置参考

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

Operator 全局配置

配置项	描述	默认值
`nfd.enabled`	是否启用 Node Feature Discovery（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.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`

自定义 DCSM 指标

SPU Operator 部署的 DCSM Exporter 提供默认采集指标，详见 MOFFETT DCSM Exporter 用户手册。如需采集自定义指标，可通过以下两种方式配置 ConfigMap：

方法一：通过文件创建 ConfigMap
```
kubectl create configmap <name> --from-file=dcsm-metrics.csv=<custom_metric_file> -n moffett-spu-operator
```
然后在 values.yaml 的环境变量 DCSM_EXPORTER_COLLECTORS 中指定该 ConfigMap 文件。

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

config:
  name: custom-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

须知

如自定义指标未生效，可使用以下命令检查 ConfigMap 格式是否正确：

kubectl get configmap <name> -n moffett-spu-operator -o yaml

节点选择性部署

SPU Operator 会根据 NFD 添加的以下任一标签识别 SPU 节点：

feature.node.kubernetes.io/pci-1f36.present=true
feature.node.kubernetes.io/pci-1200_1f36.present=true

SPU Operator 默认会在所有检测到 SPU 的工作节点上部署其各个运行组件（operands）。如果需要控制特定节点上的组件部署，可通过为节点设置相应标签来启用或禁止部署。

禁止在指定节点部署所有 SPU 组件

为某个 SPU 节点设置以下标签，可阻止 SPU Operator 在该节点部署任何组件：

kubectl label nodes <node> moffett.ai/spu.deploy.operands=false --overwrite # 禁止在该节点上部署 SPU Operator 管理的所有组件 

禁止在指定节点部署特定组件

执行以下命令查询节点上的标签信息：

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

如仅需阻止某些组件的部署，为节点设置以下标签；如标签已存在并需覆盖，需使用 --overwrite 参数。

kubectl label nodes <node> moffett.ai/spu.deploy.driver=false --overwrite # 禁止在该节点上通过镜像安装 SOLA 驱动
kubectl label nodes <node> moffett.ai/spu.deploy.container-toolkit=false --overwrite # 禁止在该节点部署 Container Toolkit
kubectl label nodes <node> moffett.ai/spu.deploy.dcsm-exporter=false --overwrite # 禁止在该节点部署 DCSM Exporter
kubectl label nodes <node> moffett.ai/spu.deploy.device-plugin=false --overwrite # 禁止在该节点部署 Device Plugin

恢复部署

要重新允许在指定节点部署组件，将对应标签的值设置为 true。

部署后验证

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

须知

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

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

升级

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

提取默认配置。

helm show values spu-operator-v1.2.0.tgz > values.yaml

helm show values spu-lite-operator-v1.2.0.tgz > values.yaml

修改配置。
```
vim values.yaml
```
使用更新后的配置进行升级。
helm upgrade spu-operator spu-operator-v1.2.0.tgz -n moffett-spu-operator --disable-openapi-validation -f values.yaml
helm upgrade spu-operator spu-lite-operator-v1.2.0.tgz -n moffett-spu-operator --disable-openapi-validation -f values.yaml
须知

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

升级 SOLA 驱动

SPU Operator 支持通过 k8s-driver-manager 管理和自动化 SOLA 驱动的升级过程。k8s-driver-manager是运行在 SOLA 驱动 DaemonSet 中的一个 initContainer，仅用于管理容器化 SOLA 驱动在节点上的生命周期。在部署阶段，该组件会检测节点是否已预装主机 SOLA 驱动，并通过节点标签避免重复部署容器化 SOLA 驱动。在升级过程中，k8s-driver-manager 会依次驱逐使用 SPU 的业务 Pod，完成驱动卸载，并在新驱动容器部署完成后恢复 SPU Operator 和业务 Pod 的调度。

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

修改 values.yaml 中 SOLA 驱动版本。
```
driver:
   version: <driver-version>
```

手动删除当前 SOLA 驱动的 Pod。

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

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

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

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

卸载

卸载 SPU Operator。

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

（可选）如未启用自动清理（operator.cleanupCRD: false 默认关闭），手动删除 CRD。
```
kubectl delete crd clusterpolicies.moffettai.com
```
删除 namespace。
```
kubectl delete ns moffett-spu-operator
```

验证卸载结果。

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