# 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。 ## 快速开始 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-v1.2.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 ``` ```` 2. 安装 SPU Operator（默认配置）。 ````{tabs} ```{tab} S4/S30/S40/S40AC ```bash helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.2.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 自定义参数选择以下任一方式安装。 ### 使用 --set 配置参数 ````{tabs} ```{tab} S4/S30/S40/S40AC ```bash helm install spu-operator -n moffett-spu-operator --create-namespace spu-operator-v1.2.0.tgz --set = ``` ```{tab} S40Lite ```bash helm install spu-operator -n moffett-spu-operator --create-namespace spu-lite-operator-v1.2.0.tgz --set = ``` ```` ### 使用 values.yaml 配置 ````{tabs} ```{tab} S4/S30/S40/S40AC ```bash 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 ``` ```{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 ``` ```` ## 配置参考 以下表格列出了常用配置项。 ### 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 用户手册](./dcsm/dcsm-exporter.md)。如需采集自定义指标，可通过以下两种方式配置 ConfigMap： - 方法一：通过文件创建 ConfigMap ```bash kubectl create configmap --from-file=dcsm-metrics.csv= -n moffett-spu-operator ``` 然后在 values.yaml 的环境变量 `DCSM_EXPORTER_COLLECTORS` 中指定该 ConfigMap 文件。 - 方法二：在 values.yaml 中定义指标内容 ```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 如自定义指标未生效，可使用以下命令检查 ConfigMap 格式是否正确： ```bash kubectl get configmap -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 在该节点部署任何组件： ```bash kubectl label nodes moffett.ai/spu.deploy.operands=false --overwrite # 禁止在该节点上部署 SPU Operator 管理的所有组件 ``` ### 禁止在指定节点部署特定组件 执行以下命令查询节点上的标签信息： ```bash kubectl get node -o wide # 查看节点 NAME kubectl describe node # 查看 Labels 字段下的标签信息 ``` 如仅需阻止某些组件的部署，为节点设置以下标签；如标签已存在并需覆盖，需使用 `--overwrite` 参数。 ```bash kubectl label nodes moffett.ai/spu.deploy.driver=false --overwrite # 禁止在该节点上通过镜像安装 SOLA 驱动 kubectl label nodes moffett.ai/spu.deploy.container-toolkit=false --overwrite # 禁止在该节点部署 Container Toolkit kubectl label nodes moffett.ai/spu.deploy.dcsm-exporter=false --overwrite # 禁止在该节点部署 DCSM Exporter kubectl label nodes moffett.ai/spu.deploy.device-plugin=false --overwrite # 禁止在该节点部署 Device Plugin ``` ### 恢复部署 要重新允许在指定节点部署组件，将对应标签的值设置为 `true`。 ## 部署后验证 SPU Operator 部署完成后，检查其组件是否成功运行。 ```{admonition} 须知 :class: note 受网络环境影响，组件 Pod 可能需要一定时间才能进入 Running 状态。 ``` ```bash kubectl get pod -n moffett-spu-operator # 当 Pod 的 STATUS = running（READY = 1/1）时，表示正常启动 ``` ## 升级 SPU Operator 支持使用 Helm Hook 自动升级 CRD（`operator.upgradeCRD` 默认启用），步骤如下： 1. 提取默认配置。 ````{tabs} ```{tab} S4/S30/S40/S40AC ```bash helm show values spu-operator-v1.2.0.tgz > values.yaml ``` ```{tab} S40Lite ```bash helm show values spu-lite-operator-v1.2.0.tgz > values.yaml ``` ```` 2. 修改配置。 ```bash vim values.yaml ``` 3. 使用更新后的配置进行升级。 ````{tabs} ```{tab} S4/S30/S40/S40AC ```bash helm upgrade spu-operator spu-operator-v1.2.0.tgz -n moffett-spu-operator --disable-openapi-validation -f values.yaml ``` ```{tab} S40Lite ```bash helm upgrade spu-operator spu-lite-operator-v1.2.0.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 生效后完成正确校验。 ``` ### 升级 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 驱动的操作步骤如下： 1. 修改 values.yaml 中 SOLA 驱动版本。 ```yaml driver: version: ``` 2. 手动删除当前 SOLA 驱动的 Pod。 ```bash kubectl get node # 查看集群中的节点 NAME kubectl delete pod -l app=moffett-driver-daemonset --field-selector spec.nodeName= -n moffett-spu-operator ``` 删除 SOLA 当前驱动后，需等待一段时间加载新驱动及其他组件。 3. （可选）查看新 SOLA 驱动 Pod 的实时部署状态。 ```bash kubectl get pod -l app=moffett-driver-daemonset -n moffett-spu-operator -w ``` ## 卸载 1. 卸载 SPU Operator。 ```bash helm list -n moffett-spu-operator # 查看部署的 helm release NAME helm uninstall -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 ``` ## 相关文档 - [MOFFETT Container Toolkit 用户手册](./mct.md) - [MOFFETT Device Plugin 用户手册](./k8s-device-plugin.md) - [MOFFETT DCSM Exporter 用户手册](./dcsm/dcsm-exporter.md)