# MOFFETT SPU Operator 用户手册
MOFFETT SPU Operator 使用 Operator 框架自动化部署和管理在 Kubernetes 中运行的 Device Plugin 和 DCSM Exporter 组件。
MOFFETT SPU Operator 支持统一部署 Device Plugin 和 DCSM Exporter，如需单独部署这两个组件，请参见 [MOFFETT Device Plugin 用户手册](./k8s-device-plugin.md) 和 [MOFFETT DCSM Exporter 用户手册](./dcsm/dcsm-exporter.md)。
## 部署 SPU Operator
### 前提条件
- 部署 Kubernetes 集群，具体请参见 安裝 K8s 集群。
- 安装 kubectl 命令行工具并具有对集群的访问权限，具体请参见 在 Linux 系统中安装并设置 kubectl。
- 安装 Helm 3，具体请参见 安装 Helm。
### 操作步骤
1. 获取 SPU Operator 的 Chart 包。
```bash
wget https://moffett-release.tos-cn-guangzhou.volces.com/macs/macs-v1.10/spu-operator/spu-operator-v1.1.0.tgz
```
2. 部署 SPU Operator。
````{tabs}
```{tab} 使用默认配置
在不额外修改参数的情况下，可以直接使用默认配置进行安装：
```bash
helm install spu-operator \
-n moffett-spu-operator --create-namespace \
spu-operator-v1.1.0.tgz
```
```{tab} 使用指定配置
如果需要修改默认参数，可以通过 `--set` 指定配置项，具体请参见 [常用 Helm Chart 自定义配置项](#helm-chart)。
```bash
helm install spu-operator \
-n moffett-spu-operator --create-namespace \
spu-operator-v1.1.0.tgz \
--set =
# 推荐配置示例
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
```
3. 查看 SPU Operator 部署状态。
```bash
helm list -n moffett-spu-operator # 当 NAME = spu-operator 的 STATUS = deployed 时，部署成功。
```
4. 查看 SPU Operator 相关组件 Pod 状态。
```{admonition} 须知
:class: note
受网络环境影响，所有组件 Pod 成功运行需等待一段时间。
```
```bash
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](#id6)。
| 配置项 | 描述 | 默认值 |
|----------------------------------------|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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 用户手册](./dcsm/dcsm-exporter.md#id5)。如需采集自定义指标，可通过以下任一方式创建 ConfigMap：
- 执行以下命令创建包含 CSV 格式指标数据的 ConfigMap, 并在 `values.yaml` 文件中 DCSM Exporter 环境变量的 `DCSM_EXPORTER_COLLECTORS` 字段指定该 ConfigMap。
```bash
kubectl create configmap --from-file=dcsm-metrics.csv= -n moffett-spu-operator
```
- 在 `values.yaml` 文件中使用 `config` 字段直接创建 ConfigMap 内容，自定义指标将覆盖 DCSM Exporter 环境变量 `DCSM_EXPORTER_COLLECTORS` 指定的默认值。示例如下：
```bash
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
```
```{admonition} 须知
:class: note
如自定义指标未生效，可使用 `kubectl get configmap -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 在这些节点上部署，步骤如下：
1. 查询集群中的节点信息。
```bash
kubectl get nodes
```
2. 为指定节点添加标签。
```bash
kubectl label nodes ...