MOFFETT SPU Operator 用户手册

MOFFETT SPU Operator 使用 Operator 框架自动化部署和管理在 Kubernetes 中运行的 Device Plugin 和 DCSM Exporter 组件。

MOFFETT SPU Operator 支持统一部署 Device Plugin 和 DCSM Exporter，如需单独部署这两个组件，请参见 MOFFETT Device Plugin 用户手册和 MOFFETT DCSM Exporter 用户手册。

部署 SPU Operator

前提条件

部署 Kubernetes 集群，具体请参见安裝 K8s 集群。
安装 kubectl 命令行工具并具有对集群的访问权限，具体请参见在 Linux 系统中安装并设置 kubectl。
安装 Helm 3，具体请参见安装 Helm。

操作步骤

获取 SPU Operator 的 Chart 包。

wget https://moffett-release.tos-cn-guangzhou.volces.com/macs/macs-v1.10/spu-operator/spu-operator-v1.1.0.tgz

部署 SPU Operator。

在不额外修改参数的情况下，可以直接使用默认配置进行安装：

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

如果需要修改默认参数，可以通过 --set 指定配置项，具体请参见常用 Helm Chart 自定义配置项。

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

# 推荐配置示例
helm install spu-operator \
  -n moffett-spu-operator --create-namespace \
  spu-operator-v1.1.0.tgz \
  --set operator.cleanupCRD=true \
  --set dcsmExporter.serviceMonitor.enabled=true

查看 SPU Operator 部署状态。

helm list -n moffett-spu-operator # 当 NAME = spu-operator 的 STATUS = deployed 时，部署成功。

查看 SPU Operator 相关组件 Pod 状态。

须知

受网络环境影响，所有组件 Pod 成功运行需等待一段时间。

kubectl get pod -n moffett-spu-operator # 当各组件 pod 的 STATUS = running（READY = 1/1）时，组件部署成功。

常用 Helm Chart 自定义配置项

下表列出了使用 Helm 部署 SPU Operator 时可通过 --set 配置的常用参数项。执行 helm show values spu-operator-v1.1.0.tgz 命令可查看所有可用选项。可提取 Helm Chart 中的配置到 values.yaml 文件，修改后更新 Operator 配置，具体请参见更新 SPU Operator。

配置项	描述	默认值
`nfd.enabled`	默认情况下，SPU Operator 会启用 Node Feature Discovery（NFD）特性。如果集群中已运行 NFD，将此值设置为 `false`。	`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.enabled`	默认情况下，SPU Operator 会将 SOLA 驱动作为容器部署在系统上。如果主机上已预装了 SOLA 驱动程序，将此值设置为 `false`。	`true`
`driver.repository`	SOLA 驱动镜像仓库。	`moffett`
`driver.image`	SOLA 驱动镜像名。	`driver`
`driver.version`	SOLA 驱动镜像版本。	`3.13.0-ubuntu22.04`
`driver.imagePullPolicy`	SOLA 驱动镜像拉取策略。	`IfNotPresent`
`driver.imagePullSecrets`	镜像拉取密钥名称（如果镜像仓库需要凭据）。创建密钥的操作请参见从私有仓库拉取镜像。	`[]`
`devicePlugin.enabled`	是否启用 Device Plugin。	`true`
`devicePlugin.repository`	Device Plugin 镜像仓库。	`moffett`
`devicePlugin.image`	Device Plugin 镜像名。	`k8s-device-plugin`
`devicePlugin.version`	Device Plugin 镜像版本。	`v0.3.0`
`devicePlugin.imagePullPolicy`	Device Plugin 镜像拉取策略。	`IfNotPresent`
`devicePlugin.imagePullSecrets`	镜像拉取密钥名称（如果镜像仓库需要凭据）。创建密钥的操作请参见从私有仓库拉取镜像。	`[]`
`dcsmExporter.enabled`	是否启用 DCSM Exporter。	`true`
`dcsmExporter.repository`	DCSM Exporter 镜像仓库。	`moffett`
`dcsmExporter.image`	DCSM Exporter 镜像名。	`dcsm-exporter`
`dcsmExporter.version`	DCSM Exporter 镜像版本。	`1.2.0-1.0.0`
`dcsmExporter.imagePullPolicy`	DCSM Exporter 镜像拉取策略。	`IfNotPresent`
`dcsmExporter.imagePullSecrets`	镜像拉取密钥名称（如果镜像仓库需要凭据）。创建密钥的操作请参见从私有仓库拉取镜像。	`[]`
`dcsmExporter.env`	DCSM Exporter 环境变量。可用于指定 DCSM Exporter 监听的地址与端口、指标采集配置文件路径等。	`[ { name: DCSM_EXPORTER_LISTEN, value: ":7788" }, { name: DCSM_EXPORTER_KUBERNETES, value: "true" }, { name: DCSM_EXPORTER_COLLECTORS, value: "/etc/dcsm-exporter/default-counters.csv" } ]`
`dcsmExporter.serviceMonitor.enabled`	是否启用 ServiceMonitor。使用 Prometheus Operator 时将此参数设置为`true`。	`false`
`dcsmExporter.serviceMonitor.interval`	Prometheus 抓取间隔。	`15s`

自定义 DCSM 指标

DCSM Exporter 默认采集的指标字段详见 MOFFETT DCSM Exporter 用户手册。如需采集自定义指标，可通过以下任一方式创建 ConfigMap：

执行以下命令创建包含 CSV 格式指标数据的 ConfigMap, 并在 values.yaml 文件中 DCSM Exporter 环境变量的 DCSM_EXPORTER_COLLECTORS 字段指定该 ConfigMap。
```
kubectl create configmap <name> --from-file=dcsm-metrics.csv=<custom_metric_file> -n moffett-spu-operator
```

在 values.yaml 文件中使用 config 字段直接创建 ConfigMap 内容，自定义指标将覆盖 DCSM Exporter 环境变量 DCSM_EXPORTER_COLLECTORS 指定的默认值。示例如下：

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

须知

如自定义指标未生效，可使用 kubectl get configmap <config-map-name> -n moffett-spu-operator -o yaml 命令查看 ConfigMap 内容，确认是否存在格式错误等问题。

常见部署场景

防止在指定节点上部署相关组件

当 NFD 启用时，SPU Operator 默认为集群中所有 worker 节点打上标签 feature.node.kubernetes.io/pci-1f36.present=true 或 feature.node.kubernetes.io/pci-1200_1f36.present=true，并将 SOLA 驱动、Device Plugin 和 DCSM Exporter 组件部署到所有节点上。通过为指定节点添加标签，防止这些组件通过 SPU Operator 在这些节点上部署，步骤如下：

查询集群中的节点信息。
```
kubectl get nodes
```
为指定节点添加标签。
```
kubectl label nodes <node1_name> <node2_name> ... <label> [--overwrite] # 添加标签，如标签已存在，必须设置 --overwrite 参数覆盖原有标签的值
kubectl get nodes --show-labels | grep <node_name>                      # 验证标签
```
可为添加的 <label> 如下：
- 防止部署所有组件：moffett.ai/spu.deploy.operands=false
- 防止安装 SOLA 驱动： moffett.ai/spu.deploy.driver=false，已预装 SOLA 驱动的节点必须添加该标签，避免冲突。
- 防止部署 DCSM Exporter：moffett.ai/spu.deploy.dcsm-exporter=false
- 防止部署 Device Plugin：moffett.ai/spu.deploy.device-plugin=false
如需恢复在指定节点上部署这些组件，修改该节点标签的值为 true。
```
# 示例
kubectl label nodes idc-ubuntu2204-108 moffett.ai/spu.deploy.operands=true --overwrite
```

集群中所有节点已预装 SOLA 驱动

在这种场景下，集群中所有 worker 节点上已预装 SOLA 驱动。执行以下命令通过设置 driver.enabled=false，防止 SPU Operator 在集群的节点上安装 SOLA 驱动。

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

使用 Device Plugin 和 DCSM Exporter

SPU Operator 部署完成后，集成了 Device Plugin 和 DCSM Exporter 组件。关于这两个组件在 Kubernetes 集群环境中的应用，请参见 MOFFETT Device Plugin 用户手册和 DCSM Exporter 用户手册。

更新 SPU Operator

通过 Helm 自动更新 CRD 资源

SPU Operator 支持通过升级 CRD 的 Helm hook（operator.upgradeCRD）自动升级 CRD 资源，该 Hook 默认启用。通过 Helm 更新 Operator 的步骤如下：

提取 Helm Chart 中的配置到 values.yaml 文件。

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

更新 values.yaml 中的配置项。
```
vim values.yaml
```
更新 SPU Operator。
```
helm upgrade spu-operator spu-operator-v1.1.0.tgz -n moffett-spu-operator --disable-openapi-validation -f values.yaml
```
须知

为防止 Helm 根据旧版 CRD 验证新 Chart 中的自定义资源（CR）实例，必须使用 --disable-openapi-validation 选项。

更新 Cluster Policy

执行以下命令，可动态修改 ClusterPolicy 自定义资源：

kubectl edit clusterpolicy

完成编辑后，Kubernetes 会自动将更改应用到集群。

卸载 SPU Operator

查看部署的 SPU Operator 名称。
```
helm list -n moffett-spu-operator
```

通过 Helm 卸载 SPU Operator。

helm uninstall <name> -n moffett-spu-operator

（可选）如果未启用通过 Helm 卸载 SPU Operator 时删除 CRD（operator.cleanupCRD=false），执行以下命令手动删除。

kubectl get crd | grep "moffett" # 检查是否有 SPU Operator 相关的 CRD
kubectl delete crd <crd-name>    # 删除查询到的 CRD

删除 SPU Operator 的 namespace。
```
kubectl delete ns moffett-spu-operator
```

验证卸载是否完成。

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