# MOFFETT SPU Operator 用户手册

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

- 容器化 SOLA 驱动
- Container Toolkit
- Device Plugin
- DCSM（Data Center SPU Manager）Exporter
- Node Status Exporter

如需单独部署及管理 Container Toolkit、Device Plugin 或 DCSM Exporter，详见[《MOFFETT Container Toolkit 用户手册》](./mct.md)、[《MOFFETT Device Plugin 用户手册》](./k8s-device-plugin.md)或[《DCSM Exporter 用户手册》](./dcsm/dcsm-exporter.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>。

## 部署

### 获取安装包

````{tabs}

```{tab} S4/S30/S40/S40AC
```bash
wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.12/spu-operator/spu-operator-v1.3.0.tgz
```

```{tab} S40Lite
```bash
wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.11/spu-operator/spu-lite-operator-v1.2.0.tgz
```
````

### 默认部署

````{tabs}

```{tab} S4/S30/S40/S40AC
```bash
helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.3.0.tgz
```

```{tab} S40Lite
```bash
helm install spu-operator -n moffett-spu-operator --create-namespace spu-lite-operator-v1.2.0.tgz
```
````

### 自定义部署

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

- **使用 --set 配置参数**

  ````{tabs}

  ```{tab} S4/S30/S40/S40AC
  ```bash
  helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.3.0.tgz --set <option-name>=<option-value>
  ```

  ```{tab} S40Lite
  ```bash
  helm install spu-operator -n moffett-spu-operator --create-namespace spu-lite-operator-v1.2.0.tgz --set <option-name>=<option-value>
  ```
  ````

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

  ````{tabs}

  ```{tab} S4/S30/S40/S40AC
  ```bash
  helm show values spu-operator-v1.3.0.tgz > values.yaml # 导出默认配置文件
  vim values.yaml # 修改参数配置
  helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.3.0.tgz -f values.yaml
  ```

  ```{tab} S40Lite
  ```bash
  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
  ```
  ````

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

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

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

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

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

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

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

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

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

(spu-operator-preinstalled-driver)=
#### 节点已预装 SOLA 驱动

SPU Operator 支持与主机方式预装的 SOLA 驱动配合使用。可根据集群中预装驱动节点的范围，选择以下方式配置：

- **所有节点均已预装 SOLA 驱动**

  若集群中所有节点均已通过主机方式安装 SOLA Toolkit，将驱动生命周期交由外部管理，并禁用 SPU Operator 的驱动部署。此时 SPU Operator 仍可继续部署 Container Toolkit、Device Plugin、DCSM Exporter、Node Status Exporter 等其他组件。

  可在安装时通过 `--set` 参数配置：

  ````{tabs}

  ```{tab} S4/S30/S40/S40AC
  ```bash
  helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.3.0.tgz --set driver.enabled=false
  ```

  ```{tab} S40Lite
  ```bash
  helm install spu-operator -n moffett-spu-operator --create-namespace spu-lite-operator-v1.2.0.tgz --set driver.enabled=false
  ```
  ````

- **大部分节点需要 Operator 安装驱动，少数节点不安装驱动**

  保持 `driver.enabled: true`，并为不需要部署容器化 SOLA 驱动的节点设置组件级标签：

  ```yaml
  driver:
    enabled: true
  ```

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

  该标签表示明确排除该节点的驱动部署，属于配置策略，不表示节点上已检测到预装驱动。

- **部分节点已预装 SOLA 驱动，其余节点由 Operator 安装驱动**

  保持 `driver.enabled: true`。对于已预装 SOLA 驱动的节点，SPU Operator 会在部署阶段检测节点上的主机驱动，为节点打上 `moffett.ai/spu.deploy.driver=pre-installed` 的标签，并跳过这些节点的容器化 SOLA 驱动部署。

  ```yaml
  driver:
    enabled: true
  ```

  `pre-installed` 状态仅用于表示该节点已存在主机方式安装的 SOLA 驱动。该状态只影响 Driver 组件调度，不影响 Container Toolkit、Device Plugin、DCSM Exporter、Node Status Exporter 等其他组件的部署。

## 部署后验证

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

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

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

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

SPU Operator 支持统一部署并暴露 DCSM 设备指标、Operator 协调指标和节点状态指标，便于在 Prometheus 中观察 SPU 设备运行状态、Operator 控制面状态以及节点上的 SOLA 驱动与 PCI 设备检测结果。

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

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

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

(spu-operator-custom-dcsm-metrics)=
### DCSM Exporter 指标

SPU Operator 部署的 DCSM Exporter 提供默认采集指标，详见《DCSM Exporter 用户手册》中的[可用 DCSM 字段参考](./dcsm/dcsm-exporter.md#dcsm-available-fields-reference)。如需采集自定义指标，可通过以下两种方式配置 ConfigMap，配置完成后执行 `helm upgrade` 使变更生效。

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

从当前运行的 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 用户手册》中的[可用 DCSM 字段参考](./dcsm/dcsm-exporter.md#dcsm-available-fields-reference)。

#### 配置 ConfigMap

以下两种方式二选一，相关配置项详见 [DCSM Exporter 配置](#spu-operator-dcsm-exporter-config)。

- **方法一：通过文件创建独立 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
  ```

#### 应用变更

````{tabs}

```{tab} S4/S30/S40/S40AC
```bash
helm upgrade spu-operator spu-operator-<current_operator_version>.tgz -n moffett-spu-operator -f values.yaml
```

```{tab} S40Lite
```bash
helm upgrade spu-operator spu-lite-operator-<current_operator_version>.tgz -n moffett-spu-operator -f values.yaml
```
````

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

#### 验证

在集群内验证指标输出，确认输出内容与自定义指标文件一致。

```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 | 当前是否检测到 Node Feature Discovery（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 用户手册》中的[可用 DCSM 字段参考](./dcsm/dcsm-exporter.md#dcsm-available-fields-reference)。

## 升级

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

### 升级 SPU Operator 版本

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

1. 获取新版本 Helm Chart 包。

   ````{tabs}

   ```{tab} S4/S30/S40/S40AC
   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.11/spu-operator/spu-operator-<new_operator_version>.tgz # <new_operator_version> 替换为实际的目标版本号
   ```

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

2. 执行升级。

   ````{tabs}

   ```{tab} S4/S30/S40/S40AC
   ```bash
   helm upgrade spu-operator spu-operator-<new_operator_version>.tgz -n moffett-spu-operator
   ```

   ```{tab} S40Lite
   ```bash
   helm upgrade spu-operator spu-lite-operator-<new_operator_version>.tgz -n moffett-spu-operator
   ```
   ````

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

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

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

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

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

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

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

   ````{tabs}

   ```{tab} S4/S30/S40/S40AC
   ```bash
   helm upgrade spu-operator spu-operator-<current_operator_version>.tgz -n moffett-spu-operator -f values.yaml
   ```

   ```{tab} S40Lite
   ```bash
   helm upgrade spu-operator spu-lite-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 版本、仅调整配置项的场景。

1. 确认自定义部署时[使用 values.yaml 配置](#spu-operator-values-yaml-deployment)保存的 `values.yaml`，并准备当前版本的 Helm Chart 包。

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

   ```bash
   vim values.yaml
   ```

3. 应用变更。

   ````{tabs}

   ```{tab} S4/S30/S40/S40AC
   ```bash
   helm upgrade spu-operator spu-operator-<current_operator_version>.tgz -n moffett-spu-operator --disable-openapi-validation -f values.yaml
   ```

   ```{tab} S40Lite
   ```bash
   helm upgrade spu-operator spu-lite-operator-<current_operator_version>.tgz -n moffett-spu-operator --disable-openapi-validation -f values.yaml
   ```
   ````

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

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

4. 验证更新结果。

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

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

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

## 卸载

1. 卸载 SPU Operator。

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

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

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

3. 删除 namespace。

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

4. 验证卸载结果。

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

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

(spu-operator-global-config)=
### 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` | 镜像拉取密钥名称（如果镜像仓库需要凭据）。<br/>创建密钥的操作参见<a href="https://kubernetes.io/zh-cn/docs/tasks/configure-pod-container/pull-image-private-registry/" target="_blank">从私有仓库拉取镜像</a>。 | `[]`                                  |
| `operator.cleanupCRD`       | 卸载时是否清理 CRD 资源。                                                                                                                                                                                       | `false`                               |
| `operator.upgradeCRD`       | 升级时是否自动升级 CRD 资源。                                                                                                                                                                                   | `true`                                |

```{admonition} 须知
:class: note
Operator 指标固定开启，无需额外配置。
```

(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 的资源请求与限制。 | `{}` |

```{admonition} 须知
:class: note
Node Status Exporter 默认关闭。如需采集节点状态指标，将 `nodeStatusExporter.enabled` 设置为 `true`。
```

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

| 配置项                    | 描述                                                                                                                                                                                                            | 默认值                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `driver.enabled`          | 是否通过 SPU Operator 安装 SOLA 驱动。<br>`true` 适用于节点上未安装 SOLA Toolkit 的场景；`false` 适用于节点上已安装 SOLA Toolkit 的场景。                                                                       | `true`                                                                  |
| `driver.repository`       | SOLA 驱动镜像仓库。                                                                                                                                                                                             | `moffett`                                                               |
| `driver.image`            | SOLA 驱动镜像名。                                                                                                                                                                                               | S4/S30/S40/S40AC：`driver`<br>S40Lite：`driver-lite`                    |
| `driver.version`          | SOLA 驱动镜像版本。                                                                                                                                                                                             | S4/S30/S40/S40AC：`3.13.0-ubuntu22.04`<br>S40Lite：`3.15.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 镜像版本。                                                                                                                                                                                        | S4/S30/S40/S40AC：`v0.3.0`<br>S40Lite：`v0.3.0-lite` |
| `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-dcsm-exporter-config)=
### DCSM Exporter 配置

| 配置项                                 | 描述                                                                                                                                                                                                            | 默认值                                                             |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `dcsmExporter.enabled`                 | 是否部署 DCSM Exporter。                                                                                                                                                                                        | `true`                                                             |
| `dcsmExporter.repository`              | DCSM Exporter 镜像仓库。                                                                                                                                                                                        | `moffett`                                                          |
| `dcsmExporter.image`                   | DCSM Exporter 镜像名。                                                                                                                                                                                          | S4/S30/S40/S40AC：`dcsm-exporter`<br>S40Lite：`dcsm-lite-exporter` |
| `dcsmExporter.version`                 | DCSM Exporter 镜像版本。                                                                                                                                                                                        | `1.2.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 名称。                                                                                                                                                                                     | `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。<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 在特定节点上的组件部署行为。标签可在 `helm install` 前预先设置（跳过初始部署），也可在部署后设置（Operator 将自动移除对应组件）。将标签值改回 `true` 可恢复部署。

| 标签                                         | 描述                                     |
| -------------------------------------------- | ---------------------------------------- |
| `moffett.ai/spu.deploy.operands=false`       | 禁止在该节点部署全部组件。               |
| `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.dcsm-exporter=false`  | 禁止在该节点部署 DCSM Exporter。         |