# MOFFETT SPU Operator 用户手册

MOFFETT SPU Operator 基于 Kubernetes Operator Framework，是 Kubernetes 环境下统一管理稀疏处理单元 SPU（Sparse Processing Unit）相关组件部署、配置与生命周期的控制器，管理以下 SPU 配套组件：

- 容器化 SOLA 驱动
- Container Toolkit
- Device Plugin
- SPU Feature Discovery（SFD）
- DCSM Exporter
- Node Status Exporter

各组件的职责参见[云原生组件概述](./index.md)。

## 准备环境

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

- 部署可用的 Kubernetes 集群，详见 <a href="https://kubernetes.io/zh-cn/docs/setup/production-environment/tools/" target="_blank">使用部署工具安装 Kubernetes</a>。
- 安装 Kubernetes 命令行工具 `kubectl`，详见 <a href="https://kubernetes.io/zh-cn/docs/tasks/tools/#kubectl" target="_blank">安装工具 - kubectl</a>。
- 安装 Helm，详见 <a href="https://helm.sh/zh/docs/intro/install/" target="_blank">Installing Helm</a>。

## 部署

### 获取安装包

```bash
wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.14/spu-operator/spu-operator-v1.4.0.tgz
```

(spu-operator-default-deployment)=
### 默认部署

Helm Chart 默认部署 Node Feature Discovery（NFD），用于节点特性发现和标签发布；SFD 默认开启。部分节点已预装 SOLA 驱动时，无需额外配置；Operator 检测到已有驱动后，会跳过该节点的容器化驱动部署，其余组件按配置部署。

```bash
helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.4.0.tgz
```

安装后，按[部署后验证](#spu-operator-verification)检查结果。

### 自定义部署

SPU Operator 支持通过 Helm 自定义参数选择以下任一方式安装，其中各配置项说明详见[配置参考](#spu-operator-config-reference)。

- 使用 --set 配置参数

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

(spu-operator-values-yaml-deployment)=
- 使用 values.yaml 配置

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

  ```{admonition} 须知
  :class: note
  请保留此 `values.yaml` 文件，后续更新配置时可直接复用。
  ```

(spu-operator-selective-deployment)=
### 常见部署场景

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

#### 排除部分 SPU 节点

默认情况下，SPU Operator 会在检测到 SPU 的工作节点上部署已启用的配套组件，包括驱动、Container Toolkit、Device Plugin、SFD 和监控组件。若需排除特定节点，为该节点设置以下标签：

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

该标签可在执行 `helm install` 前设置，以跳过该节点上配套组件的初始部署；也可在部署完成后设置，SPU Operator 将自动移除该节点上受此标签控制的组件。将标签值改回 `true` 可恢复已启用组件的部署。该标签不控制 NFD 或 Operator 控制器自身的调度。

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

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

(spu-operator-preinstalled-driver)=
(macs-1-14-spu-operator-preinstalled-driver)=
#### 所有节点的驱动自行维护

所有节点均已安装 SOLA 驱动，且自行维护时，设置 `driver.enabled=false`，由 Operator 管理其余组件：

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

(spu-operator-verification)=
## 部署后验证

SPU Operator 部署完成后，检查已启用组件的运行状态和功能。

### 验证组件状态

```{admonition} 须知
:class: note
受网络环境影响，组件 Pod 可能需要一定时间才能进入 Running 状态。
```

```bash
kubectl get pod -n moffett-spu-operator
```

确认持续运行的组件 Pod 处于 Running 状态，且 READY 显示所有容器均已就绪。设备申请与访问可按[Device Plugin 运行示例](./k8s-device-plugin.md#运行示例)验证；已启用监控组件时，按[监控指标](#spu-operator-observability-metrics)检查指标输出。

(spu-operator-sfd)=
(spu-operator-sfd-verification)=
### 查看设备属性

查看集群中各节点的 SPU 设备数量、内存容量和产品标识：

```bash
kubectl get nodes -L moffett.ai/spu.count,moffett.ai/spu.memory,moffett.ai/spu.product
```

核对目标节点的标签与实际设备信息是否一致，字段含义参见[设备属性标签](#spu-operator-sfd-labels)。若未生成预期标签，检查 SFD 和 NFD 的 Pod 状态及日志。

(spu-operator-observability-metrics)=
## 监控指标

SPU Operator 可通过 DCSM Exporter、Operator 自身的 `/metrics` 接口和 `nodeStatusExporter` 暴露运行状态指标，并可配合 Prometheus Operator 采集。

不同指标来源的应用如下表所示：

| 指标来源                  | 指标描述                        | 典型用途                                                                     |
| ------------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| DCSM Exporter 指标        | SPU 设备运行时健康与性能数据。  | 观察设备温度、功耗、利用率、错误信息等运行状态。                             |
| Operator 指标             | SPU Operator 控制面和协调状态。 | 观察 SPU 节点数量、协调循环是否成功、是否检测到 NFD 标签。                   |
| Node Status Exporter 指标 | 节点本地驱动与设备发现状态。    | 判断节点上的 SOLA 驱动是否就绪、驱动验证是否通过、SPU PCI 设备数量是否正常。 |

### DCSM Exporter 指标

(spu-operator-custom-dcsm-metrics)=

SPU Operator 部署的 DCSM Exporter 提供默认采集指标，详见《DCSM Exporter 用户手册》中的{ref}`可用 DCSM 字段参考 <dcsm-available-fields-reference>`。如需采集自定义指标，可通过以下两种方式配置 ConfigMap，并按下文应用变更。

#### 准备自定义指标文件

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

```bash
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 用户手册》中的{ref}`可用 DCSM 字段参考 <dcsm-available-fields-reference>`。

#### 配置 ConfigMap

以下两种方式二选一，相关配置项详见 [DCSM Exporter 配置](#spu-operator-dcsm-exporter-config)。示例仅列出需要修改的项：在现有 `dcsmExporter.env` 中修改或添加 `DCSM_EXPORTER_COLLECTORS`，保留其他环境变量，不要直接替换整个 `env` 列表。

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

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

     ```bash
     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`）。

     ```yaml
     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 并挂载至容器。

  ```yaml
  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
  ```

#### 应用变更

将上述配置合入当前 release 的配置，按[更新配置](#spu-operator-update-config)应用。等待 Operator 将配置同步到 DaemonSet，再检查其 Pod 模板：

```bash
kubectl get daemonset moffett-dcsm-exporter -n moffett-spu-operator -o yaml
```

确认 `spec.template.spec` 中 `DCSM_EXPORTER_COLLECTORS` 的路径、ConfigMap 名称和挂载路径与本次配置一致。确认后，滚动重启 DCSM Exporter，加载新的指标文件：

```bash
kubectl rollout restart daemonset/moffett-dcsm-exporter -n moffett-spu-operator
kubectl rollout status daemonset/moffett-dcsm-exporter -n moffett-spu-operator
```

#### 验证

重启完成后，在集群内查询新 Pod 提供的指标，确认输出内容与自定义指标文件一致，以实际指标内容确认配置生效。

```bash
kubectl get svc -n moffett-spu-operator | grep moffett-dcsm-exporter # 查看 DCSM Exporter 组件的 CLUSTER-IP
curl http://<CLUSTER-IP>:7788/metrics
```

```{admonition} 须知
:class: note
Prometheus 按配置的抓取间隔采集数据，变更后需等待一个采集周期后方可在 Prometheus 中查询到新指标。
```

### Operator 指标

Operator 指标固定开启，随 SPU Operator 通过 8080 端口的 `/metrics` 路径暴露。可通过以下命令在集群内验证指标输出：

```bash
kubectl get svc -n moffett-spu-operator | grep spu-operator # 查看 Operator 组件的 CLUSTER-IP
curl http://<CLUSTER-IP>:8080/metrics
```

Operator 指标用于观察 SPU Operator 的协调（reconciliation）状态和执行结果。协调是指 Operator 持续检查 SPU 相关组件和资源，并确保其创建、更新和运行状态符合当前配置。具体指标如下表所示：

| 指标名称                                              | Prometheus 指标类型 | 描述                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spu_operator_spu_nodes_total`                        | gauge               | 当前集群中识别到的 SPU 节点数量。可用于确认 SPU Operator 是否识别到预期数量的 SPU 节点。                                                                                                                                                                                                                       |
| `spu_operator_reconciliation_last_success_ts_seconds` | gauge               | SPU Operator 最近一次成功完成协调的 Unix 时间戳，单位：秒。可用于判断 Operator 已经多久没有成功完成一次协调。                                                                                                                                                                                                  |
| `spu_operator_reconciliation_status`                  | gauge               | SPU Operator 当前协调状态。<br/>- `1`：正常，SPU Operator 已成功完成协调。<br/>- `0`：未就绪，SPU Operator 正在运行，但部分组件或资源还没有准备好。<br/>- `-1`：不可用，SPU Operator 暂时无法继续协调，通常表示所需的配置或集群资源无法读取、未创建或状态异常，可能导致 SPU 相关组件无法部署、更新或刷新状态。 |
| `spu_operator_reconciliation_total`                   | counter             | SPU Operator 累计执行协调的次数。                                                                                                                                                                                                                                                                              |
| `spu_operator_reconciliation_failed_total`            | counter             | SPU Operator 累计协调失败的次数。                                                                                                                                                                                                                                                                              |
| `spu_operator_reconciliation_has_nfd_labels`          | gauge               | 当前是否检测到 NFD 标签。NFD 标签用于帮助识别节点硬件能力，缺失时可能影响 SPU 节点识别。<br/>- `1`：已检测到 NFD 标签。<br/>- `0`：未检测到 NFD 标签。                                                                                                                                |

### Node Status Exporter 指标

节点指标由 `nodeStatusExporter` 组件暴露，用于观察每个 SPU 节点上的驱动状态和 PCI 设备检测结果。节点指标默认不启用，可在 `values.yaml` 中开启，相关配置项详见 [Node Status Exporter 配置](#spu-operator-node-status-exporter-config)。可通过以下命令在集群内验证指标输出：

```bash
kubectl get svc -n moffett-spu-operator | grep moffett-node-status-exporter # 查看 Node Status Exporter 组件的 CLUSTER-IP
curl http://<CLUSTER-IP>:8000/metrics
```

节点状态相关指标如下表所示：

| 指标名称                                                      | Prometheus 指标类型 | 描述                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spu_operator_node_metrics_ready_ts_seconds`                  | gauge               | 该节点上的 `nodeStatusExporter` 指标服务启动时间，使用 Unix 时间戳表示，单位：秒。                                                                                                                                                                                     |
| `spu_operator_node_driver_ready`                              | gauge               | 该节点上的 SOLA 驱动是否已完成就绪检查。<br/>- `1`：驱动已就绪，节点可以继续启动或使用依赖驱动的 SPU 组件。<br/>- `0`：驱动未就绪，相关 SPU 组件可能无法正常启动或使用。                                                                                               |
| `spu_operator_node_driver_validation`                         | gauge               | 该节点上的 SOLA 驱动验证是否通过，用于确认驱动是否可正常工作。<br/>- `1`：验证通过。<br/>- `0`：验证未通过，驱动可能安装异常、未加载或无法正常访问 SPU 设备。                                                                                                          |
| `spu_operator_node_driver_validation_last_success_ts_seconds` | gauge               | 该节点最近一次 SOLA 驱动验证通过的 Unix 时间戳，单位：秒。可用于判断驱动已经多久没有成功通过验证。                                                                                                                                                                     |
| `spu_operator_moffett_pci_devices_total`                      | gauge               | 该节点通过 PCI 总线检测到的 SPU 设备数量。<br/>`-1` 表示 `nodeStatusExporter` 无法读取节点上的 PCI 设备信息，因此无法确认 SPU 设备数量。出现该值时，可登录对应节点执行 `lspci | grep 1f36`：如有输出，表示节点可识别到 SPU 设备；如无输出，表示节点未识别到 SPU 设备。 |

### 接入 Prometheus

在 Kubernetes 集群环境中，建议使用 Prometheus Operator 采集指标。Prometheus 的安装步骤和参数设置，详见《DCSM Exporter 用户手册》中的[接入 Prometheus](./dcsm/dcsm-exporter.md#接入-prometheus)。

Prometheus 按配置的抓取间隔采集数据。配置生效后，可在 Prometheus 中检索 `spu_operator_` 前缀的指标确认 Operator 和节点状态指标采集结果；DCSM Exporter 设备指标详见《DCSM Exporter 用户手册》中的{ref}`可用 DCSM 字段参考 <dcsm-available-fields-reference>`。

## 升级

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

### 升级 SPU Operator 版本

SPU Operator 支持使用 Helm Hook 自动升级自定义资源定义（Custom Resource Definition，CRD）（`operator.upgradeCRD` 默认启用），步骤如下：

1. 获取新版本 Helm Chart 包。

   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.14/spu-operator/spu-operator-v1.4.0.tgz
   ```

2. 导出目标版本的默认配置，并合并现有自定义配置。

   ```bash
   helm get values spu-operator -n moffett-spu-operator -o yaml > values-before-upgrade.yaml
   helm show values spu-operator-v1.4.0.tgz > values-target.yaml
   ```

   按目标版本的配置说明，将仍需使用的镜像仓库、组件开关和资源配置等自定义项合并到 `values-target.yaml`。核对组件镜像版本及配置项的变化，避免直接沿用旧配置覆盖目标版本的默认值。

3. 执行升级。

   ```bash
   helm upgrade spu-operator spu-operator-v1.4.0.tgz -n moffett-spu-operator --disable-openapi-validation -f values-target.yaml
   ```

   `--disable-openapi-validation` 跳过 Helm 使用旧 CRD 执行的本地校验；Kubernetes 仍会按生效的 CRD 校验资源。默认升级钩子会更新 ClusterPolicy CRD；启用内置 NFD 时，也会更新其 CRD。

4. 检查配置和功能是否生效。

   ```bash
   helm list -n moffett-spu-operator
   kubectl get clusterpolicy cluster-policy -o yaml
   kubectl get pods -n moffett-spu-operator
   ```

   确认 Helm release 已更新至目标 Chart 版本、ClusterPolicy 配置符合预期，再按[部署后验证](#spu-operator-verification)检查已启用组件的状态和功能。

(spu-operator-upgrade-driver)=
### 升级容器化 SOLA 驱动

仅适用于通过 SPU Operator 部署的容器化 SOLA 驱动。若节点采用主机方式预装驱动，请参考[《SOLA Toolkit 安装指南》](../installation/sola-toolkit-installation-guide.md)手动升级。

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

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

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

   ```yaml
   driver:
     version: <driver-version>
   ```

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

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

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

   ```bash
   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 的实时部署状态。

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

   驱动升级完成后，按[部署后验证](#spu-operator-verification)检查组件是否恢复。

(spu-operator-update-config)=
## 更新配置

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

1. 查看已安装的 Helm Chart 版本，并准备相同版本的 Chart 包。

   ```bash
   helm list -n moffett-spu-operator
   ```

2. 导出当前 release 的完整配置，保存副本后修改。

   ```bash
   helm get values spu-operator -n moffett-spu-operator --all -o yaml > values-before-update.yaml
   cp values-before-update.yaml values-update.yaml
   ```

   导出的配置包含默认值和自定义值。保留更新前的副本，在 `values-update.yaml` 中修改所需配置；升级 Chart 时使用[版本升级流程](#升级-spu-operator-版本)。

3. 修改需要变更的配置项，详见[配置参考](#spu-operator-config-reference)。

   ```bash
   vim values-update.yaml
   ```

4. 应用变更，将 `<current_operator_version>` 替换为步骤 1 中的 Chart 版本。

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

   ```{admonition} 须知
   :class: note

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

5. 验证更新结果。

   ```bash
   helm list -n moffett-spu-operator
   kubectl get pod -n moffett-spu-operator
   ```

   核对已修改组件的配置是否生效，再按[部署后验证](#spu-operator-verification)检查相应功能。

## 卸载

1. 卸载 SPU Operator。

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

2. （可选）清理 CRD。`operator.cleanupCRD` 默认关闭，卸载时保留 CRD。需要移除 SPU Operator 的资源定义时，执行：

   ```bash
   kubectl delete crd clusterpolicies.moffettai.com
   ```

3. 删除 namespace。

   ```bash
   kubectl delete ns moffett-spu-operator
   ```

4. 验证卸载结果。

   ```bash
   helm list -n moffett-spu-operator
   kubectl get namespace moffett-spu-operator
   ```

   确认 release 已移除，命名空间查询返回 NotFound。未清理的 CRD 会继续保留。

(spu-operator-config-reference)=
## 配置参考

(spu-operator-global-config)=
### Operator 全局配置

| 配置项                      | 描述                                                                                                                                                                                                            | 默认值                                |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `nfd.enabled`               | 是否随 SPU Operator 部署 NFD。                                                                                                                                                                                                  | `true`                                |
| `operator.repository`       | SPU Operator 镜像仓库。                                                                                                                                                                                         | `moffett`                             |
| `operator.image`            | SPU Operator 镜像名。                                                                                                                                                                                           | `spu-operator`                        |
| `operator.version`          | SPU Operator 镜像版本。                                                                                                                                                                                         | 未指定，默认使用 `chart.AppVersion`。 |
| `operator.imagePullPolicy`  | 镜像拉取策略。                                                                                                                                                                                                  | `IfNotPresent`                        |
| `operator.imagePullSecrets` | 镜像拉取密钥名称（如果镜像仓库需要凭据）。<br/>创建密钥的操作参见<a href="https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/pull-image-private-registry/" target="_blank">从私有仓库拉取镜像</a>。 | `[]`                                  |
| `operator.cleanupCRD`       | 卸载时是否清理 ClusterPolicy CRD；启用内置 NFD 时也清理其 CRD。                                                                                                                                                                                       | `false`                               |
| `operator.upgradeCRD`       | 升级时是否自动升级 CRD 资源。                                                                                                                                                                                   | `true`                                |

(spu-operator-node-status-exporter-config)=
### Node Status Exporter 配置

| 配置项                                | 描述                                                                                                               | 默认值                                |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| `nodeStatusExporter.enabled`          | 是否启用 Node Status Exporter。<br/>启用后，`spu-operator-validator` 会暴露节点驱动状态和 SPU PCI 设备数量等指标。 | `false`                               |
| `nodeStatusExporter.repository`       | Node Status Exporter 镜像仓库。                                                                                    | `moffett`                             |
| `nodeStatusExporter.image`            | Node Status Exporter 镜像名。                                                                                      | `spu-operator-validator`              |
| `nodeStatusExporter.version`          | Node Status Exporter 镜像版本。                                                                                    | 未指定，默认使用 `chart.AppVersion`。 |
| `nodeStatusExporter.imagePullPolicy`  | Node Status Exporter 镜像拉取策略。                                                                                | `IfNotPresent`                        |
| `nodeStatusExporter.imagePullSecrets` | 镜像拉取密钥名称（如果镜像仓库需要凭据）。                                                                         | `[]`                                  |
| `nodeStatusExporter.resources`        | Node Status Exporter 的资源请求与限制。                                                                            | `{}`                                  |

(spu-operator-driver-config)=
### Driver 配置

| 配置项                    | 描述                                                                                                                                                                                                            | 默认值                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `driver.enabled`          | 是否由 SPU Operator 部署容器化 SOLA 驱动。                                                                       | `true`                                                                  |
| `driver.repository`       | SOLA 驱动镜像仓库。                                                                                                                                                                                             | `moffett`                                                               |
| `driver.image`            | SOLA 驱动镜像名。                                                                                                                                                                                               | `driver`                    |
| `driver.version`          | SOLA 驱动镜像版本。                                                                                                                                                                                             | `3.17.0-ubuntu22.04` |
| `driver.imagePullPolicy`  | SOLA 驱动镜像拉取策略。                                                                                                                                                                                         | `IfNotPresent`                                                          |
| `driver.imagePullSecrets` | 镜像拉取密钥名称（如果镜像仓库需要凭据）。<br/>创建密钥的操作参见<a href="https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/pull-image-private-registry/" target="_blank">从私有仓库拉取镜像</a>。 | `[]`                                                                    |
| `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`                |

(spu-operator-toolkit-config)=
### Container Toolkit 配置

| 配置项                     | 描述                                                                                                                                                                                                            | 默认值              |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `toolkit.enabled`          | 是否通过 SPU Operator 安装 Container Toolkit。<br>`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` | 镜像拉取密钥名称（如果镜像仓库需要凭据）。<br/>创建密钥的操作参见<a href="https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/pull-image-private-registry/" target="_blank">从私有仓库拉取镜像</a>。 | `[]`                |

(spu-operator-device-plugin-config)=
### Device Plugin 配置

| 配置项                          | 描述                                                                                                                                                                                                            | 默认值                                               |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `devicePlugin.enabled`          | 是否部署 Device Plugin。                                                                                                                                                                                        | `true`                                               |
| `devicePlugin.repository`       | Device Plugin 镜像仓库。                                                                                                                                                                                        | `moffett`                                            |
| `devicePlugin.image`            | Device Plugin 镜像名。                                                                                                                                                                                          | `k8s-device-plugin`                                  |
| `devicePlugin.version`          | Device Plugin 镜像版本。                                                                                                                                                                                        | `v0.4.0` |
| `devicePlugin.imagePullPolicy`  | Device Plugin 镜像拉取策略。                                                                                                                                                                                    | `IfNotPresent`                                       |
| `devicePlugin.imagePullSecrets` | 镜像拉取密钥名称（如果镜像仓库需要凭据）。<br/>创建密钥的操作参见<a href="https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/pull-image-private-registry/" target="_blank">从私有仓库拉取镜像</a>。 | `[]`                                                 |

(spu-operator-sfd-config)=
### SFD 配置

SFD 与 Device Plugin 共用镜像，以独立 DaemonSet 运行。SFD 依赖节点驱动就绪，并通过 NFD 发布设备属性标签。

| 配置项 | 描述 | 默认值 |
| --- | --- | --- |
| `sfd.enabled` | 是否部署 SFD。 | `true` |
| `sfd.repository` | SFD 镜像仓库。 | `moffett` |
| `sfd.image` | SFD 镜像名。 | `k8s-device-plugin` |
| `sfd.version` | SFD 镜像版本。 | `v0.4.0` |
| `sfd.imagePullPolicy` | 镜像拉取策略。 | `IfNotPresent` |
| `sfd.imagePullSecrets` | 镜像拉取密钥名称。 | `[]` |
| `sfd.env` | SFD 环境变量，详见下表。 | 设置 `SFD_SLEEP_INTERVAL=60s` |
| `sfd.args` | 传递给 SFD 的命令行参数。 | 未指定 |
| `sfd.resources` | SFD 容器的资源请求与限制。 | `{}` |

SFD 支持以下探测参数。环境变量可通过 `sfd.env` 设置，命令行参数可通过 `sfd.args` 设置。

| 命令行参数 / 环境变量 | 描述 | 默认值 |
| --- | --- | --- |
| `--sleep-interval` / `SFD_SLEEP_INTERVAL` | 两次设备属性重新探测之间的间隔。 | `60s` |
| `--no-timestamp` / `SFD_NO_TIMESTAMP` | 是否关闭时间戳标签；设为 `true` 时不生成该标签。 | `false` |

(spu-operator-dcsm-exporter-config)=
### DCSM Exporter 配置

| 配置项                                 | 描述                                                                                                                                                                                                            | 默认值                                                                    |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `dcsmExporter.enabled`                 | 是否部署 DCSM Exporter。                                                                                                                                                                                        | `true`                                                                    |
| `dcsmExporter.repository`              | DCSM Exporter 镜像仓库。                                                                                                                                                                                        | `moffett`                                                                 |
| `dcsmExporter.image`                   | DCSM Exporter 镜像名。                                                                                                                                                                                          | `dcsm-exporter`        |
| `dcsmExporter.version`                 | DCSM Exporter 镜像版本。                                                                                                                                                                                        | `1.3.0-1.0.0` |
| `dcsmExporter.imagePullPolicy`         | DCSM Exporter 镜像拉取策略。                                                                                                                                                                                    | `IfNotPresent`                                                            |
| `dcsmExporter.imagePullSecrets`        | 镜像拉取密钥名称（如果镜像仓库需要凭据）。<br/>创建密钥的操作参见<a href="https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/pull-image-private-registry/" target="_blank">从私有仓库拉取镜像</a>。 | `[]`                                                                      |
| `dcsmExporter.env`                     | DCSM Exporter 环境变量。可用于指定 DCSM Exporter 监听的地址与端口、指标采集配置文件路径等。                                                                                                                     | 详见下表                                                                  |
| `dcsmExporter.config.name`             | 自定义指标 ConfigMap 名称；未配置时使用镜像内的默认指标文件。                                                                                                                                                                                     | 未指定 |
| `dcsmExporter.config.create`           | 是否由 Helm 创建自定义指标 ConfigMap。显式配置 `config.name` 且不启用创建时，需预先创建同名 ConfigMap。                                                                                                                             | `false`                                                                   |
| `dcsmExporter.config.data`             | ConfigMap 中的指标内容（CSV 格式）。当 `config.create: true` 时生效，Helm 将以此内容创建 ConfigMap。                                                                                                            | `""`                                                                      |
| `dcsmExporter.serviceMonitor.enabled`  | 是否启用 ServiceMonitor。<br/>使用 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-node-labels)=
### 节点标签

节点标签用于控制组件部署范围或描述设备属性。

#### 部署控制标签

以下列出部署控制标签及自动生成的驱动状态标签。控制部署范围的操作参见[常见部署场景](#spu-operator-selective-deployment)。

| 标签                                            | 描述                                                                                                                             |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `moffett.ai/spu.deploy.operands=false`          | 禁止在该节点部署受 Operator 节点标签控制的配套组件，包括驱动、Container Toolkit、Device Plugin、SFD 和监控组件。 |
| `moffett.ai/spu.deploy.driver=false`            | 禁止在该节点安装容器化 SOLA 驱动。                                                                                               |
| `moffett.ai/spu.deploy.driver=pre-installed`    | 表示该节点已检测到主机方式安装的 SOLA 驱动，Driver 组件将跳过该节点。<br/>该标签由 `k8s-driver-manager` 自动添加，无需手动设置。 |
| `moffett.ai/spu.deploy.container-toolkit=false` | 禁止在该节点部署 Container Toolkit。                                                                                             |
| `moffett.ai/spu.deploy.device-plugin=false`     | 禁止在该节点部署 Device Plugin。                                                                                                 |
| `moffett.ai/spu.deploy.spu-feature-discovery=false` | 禁止在该节点部署 SFD。 |
| `moffett.ai/spu.deploy.dcsm-exporter=false`     | 禁止在该节点部署 DCSM Exporter。                                                                                                 |

(spu-operator-sfd-labels)=
#### 设备属性标签

SFD 发布以下设备属性标签，标签值由实际探测结果决定。

| 标签 | 含义 |
| --- | --- |
| `moffett.ai/spu.count` | 探测到的 `spu.product` 对应的设备（device）数量。 |
| `moffett.ai/spu.memory` | 探测到的 SPU 设备内存容量大小，单位：MiB。 |
| `moffett.ai/spu.product` | 探测到的 SPU 产品标识。 |
| `moffett.ai/sfd.timestamp` | SFD 开始探测的时间戳；可通过 `SFD_NO_TIMESTAMP=true` 关闭。 |

设备运行时的温度、利用率和错误信息参见[监控指标](#spu-operator-observability-metrics)。