docs: add superpod user guide-sig-orchestration-engine-AtomGit

已开启

docs: add superpod user guide #126

huoran创建于 10 天前从huoran/sig-orchestration-engine： superpod 合入到 openFuyao/sig-orchestration-engine： master

docs: add superpod user guide #126

已开启

huoran创建于 10 天前

从huoran/sig-orchestration-engine superpod合入到openFuyao/sig-orchestration-engine master

共 5 个文件变更+850-0

Adocs/zh/superpod_user_guide/_toc.yaml+2-0

@@ -0,0 +1,2 @@
	1	+label: SuperPod
	2	+href: ./superpod_user_guide.md

Adocs/zh/superpod_user_guide/figures/icon-caution.gif+0-0

Adocs/zh/superpod_user_guide/figures/icon-note.gif+0-0

Adocs/zh/superpod_user_guide/figures/icon-notice.gif+0-0

Adocs/zh/superpod_user_guide/superpod_user_guide.md+848-0

@@ -0,0 +1,848 @@
	1	+# SuperPod
	X X xijing10 天前文档名不体现拓扑调度的内容吗
	2	+
	3	+## 特性介绍
	X X xijing10 天前通用问题：中英文混合时，中间空格删除
	4	+
	5	+SuperPod（超节点）是基于UBS（Unified Bus System）拓扑发现机制构建的Kubernetes集群拓扑抽象实体，将物理节点按`superPodId`聚合成逻辑拓扑单元，并以自定义资源（`SuperPod` CR）的形式纳管到集群中。控制器周期性采集节点拓扑与内存信息，自动维护`SuperPod` CR的生命周期，并可选联动生成Volcano `HyperNode` CR，使能Volcano调度器的网络拓扑感知调度能力。同时提供独立`superpod-exporter`组件以Prometheus格式暴露SuperPod成员关系、内存借用、共享内存、URMA设备等指标，支撑监控平台对SuperPod资源的可视化与运维。
	6	+
	7	+当前版本仅支持FM（Full-Mesh）组网形态：单个SuperPod内的物理节点间全互联（两两直连，跳数均为1），SuperPod间不互联（仅通过Eth互联）。
	8	+
	9	+当用户在大规模集群中需要按物理拓扑边界（UB互联域）对节点进行逻辑分组、并希望Volcano调度器据此执行拓扑感知调度（如将通信密集型负载调度到同一SuperPod内）时，可使用SuperPod特性。
	10	+
	11	+### 应用场景
	12	+
	13	+- 大规模集群分层调度：集群节点数量多、跨多个SuperPod分布时，借助SuperPod拓扑抽象支撑Volcano的网络拓扑感知调度，将通信密集型负载（如分布式训练）调度到同一SuperPod内，提升通信局部性。
	14	+- UB节点拓扑感知：UB互联场景下，将同一`superPodId`的节点归并，Volcano基于`HyperNode`选择通信最优的节点组合部署分布式训练或推理服务，避免跨SuperPod调度导致通信性能劣化。
	15	+- 内存池化拓扑纳管：与容器内存借用特性配合，为远端内存借用提供拓扑边界，借用优先发生在同一SuperPod内。
	16	+- 运维侧拓扑覆盖：运维人员通过为节点打`unifiedbus.com/superpod`标签即可覆盖节点归属的SuperPod，无需依赖底层metric上报。
	17	+- SuperPod资源监控与运维：集群管理员部署`superpod-exporter`后，可在监控平台查看各SuperPod信息、各SuperPod中NUMA内存借用信息、共享内存分布信息与URMA设备健康信息，无需登录节点执行CLI，便于及时发现资源倾斜与设备故障。
	18	+
	19	+### 能力范围
	20	+
	21	+- 架构支持：支持操作系统openEuler 24.03 LTS SP3及以上版本，Kubernetes v1.31.1及以上版本，架构ARM64。
	22	+- 组网形态：当前版本仅支持FM组网（节点全互联，顶层Tier=1，单Tier-1子组）。
	23	+- 拓扑抽象：支持按`superPodId`聚合节点，自动生成`SuperPod`CR（cluster scope，group `resource.matrix.huawei.com`，version `v1`）。
	24	+- superPodId双来源解析：
	25	+ - 优先来源1：节点label `unifiedbus.com/superpod`（运维侧覆盖）。
	26	+ - 备选来源2：MatrixMetric拓扑metric中上报的`superPodId`字段。
	27	+- 内存纳管：基于NUMA信息采集节点`total`/`used`内存，写入`SuperPod`的`spec.groups[].nodes[].memory`字段。
	28	+- HyperNode可选联动：通过环境变量`HYPERNODE_ENABLED`开关，可选生成Volcano `HyperNode` CR（`topology.volcano.sh/v1alpha1`），供Volcano调度器执行网络拓扑感知调度。
	29	+- 调谐机制：MatrixMetric CR变更触发去抖调谐（5s去抖），同时周期全量resync（默认5min）；拓扑数据12h刷新一次，NUMA数据30s刷新。
	30	+- 指标采集与上报：独立`superpod-exporter` DaemonSet组件以Prometheus格式暴露SuperPod成员关系、NUMA内存借用、共享内存提供、URMA设备信息与健康等指标，默认经`:9102/metrics`端点暴露，由监控平台抓取汇聚。
	31	+- 规格限制：
	32	+ - 同一`superPodId`下所有节点被装入同一个Tier-1 group（`group-0`）。
	33	+ - `HyperNode`联动需集群已安装Volcano并注册`hypernodes` CRD。
	34	+
	35	+> ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	36	+> kube-matrix-agent单实例可管理最多150个Pod、300个容器、300个进程，此为matrix-agent组件的通用规格限制，非SuperPod特性独有约束。
	37	+
	38	+### 亮点特征
	39	+
	40	+- 双来源superPodId：节点label优先于metric，保证运维侧通过打标签即可覆盖拓扑归属，无需依赖底层metric上报，也无需重启组件。
	41	+- 声明式调谐：MatrixMetric CR变更自动触发调谐，最终一致，无需手动干预。
	42	+- 可插拔HyperNode：默认不产生`HyperNode` CR，仅当显式开启`HYPERNODE_ENABLED=true`且`HyperNode` CRD已注册时联动，避免对未安装Volcano的集群造成负担。
	43	+- CRD就绪感知：`SuperPod`/`HyperNode` CRD未就绪时自动退避重试，不崩溃、不影响既有控制器。
	44	+- 独立指标导出器：`superpod-exporter`独立DaemonSet部署，单类指标采集失败不阻塞其他类别，`/metrics`始终可访问；SuperPod维度`superpod_name`label源自节点标签，当前即可承载SuperPod级汇聚。
	45	+
	46	+### 基本概念
	47	+
	48	+- SuperPod：超节点，由同一`superPodId`的物理节点聚合而成的逻辑拓扑单元，对应`SuperPod` CR（`resource.matrix.huawei.com/v1`，集群级）。
	49	+- superPodId：SuperPod标识，直接决定SuperPod命名（`superpod-<superPodId>`）；可通过节点label `unifiedbus.com/superpod`覆盖。
	50	+- FM组网：SuperPod内物理节点全互联（两两直连，跳数均为1）、SuperPod间不互联的组网形态，顶层Tier=1。
	51	+- HyperNode：Volcano定义的拓扑层级CR（`topology.volcano.sh/v1alpha1`），由本特性控制器在`HYPERNODE_ENABLED=true`时联动产出，供Volcano调度器执行网络拓扑感知调度。
	52	+- Tier-1子组：SuperPod内部按1跳连通分量划分的拓扑子组，FM组网下每个SuperPod仅含一个Tier-1子组（`group-0`），包含该SuperPod下全部节点。
	53	+- superpod-exporter：独立SuperPod指标导出组件，以DaemonSet形态部署于SuperPod每个物理节点，经Prometheus文本格式在`:9102/metrics`端点暴露指标，由监控平台抓取汇聚。
	54	+
	55	+### 实现原理
	X X xijing9 天前当前章节做一下调整，原因是实现原理只放"怎么做到的"，不放"产出是什么"和"怎么用"，可参考如下：实现原理总体方案拓扑采集工作流程指标采集机制 ← 仅保留"怎么工作"，不含指标定义表配置说明 SuperPod CR字段说明 ← 表3 + 内存统计口径作为memory字段补充指标定义 ← 表5 Label语义 + 表6 指标定义直接内联（不再引用回实现原理）配置样例样例1 SuperPod CR FM组网组装结果表 ← 从实现原理移入样例2 HyperNode CR 样例3 Gang调度样例4 指标输出 + URMA聚合说明 + 内存借还PromQL ← 从实现原理移入样例5 PromQL汇聚
	56	+
	57	+#### 总体方案
	58	+
	59	+总体思路：matrixagent采集单物理节点拓扑（含`superPodId`）通过MatrixMetric CR上报 → matrixcontroller按`superPodId`汇总组装`SuperPod`资源 → Volcano拓扑感知调度。
	60	+
	61	+- 采集与上报复用既有matrixagent DaemonSet框架与MatrixMetric CR，新增`node_network_topology_info`指标项。
	62	+- 组装控制器内嵌既有matrixcontroller进程，与既有容器逃生告警控制器并行、互不干扰。
	63	+- `SuperPod`为本仓新增CRD（`resource.matrix.huawei.com/v1`，集群级）。
	64	+- 是否组装Volcano `HyperNode`资源由环境变量`HYPERNODE_ENABLED`控制，默认`false`（不启用）。关闭时Controller仅产出`SuperPod`（`hyperNodeRef`字段留空），不依赖Volcano与HyperNode CRD；启用时额外产出`HyperNode`并填充`SuperPod`中的`hyperNodeRef`引用。
	65	+
	66	+#### 工作流程
	67	+
	68	+SuperPod由matrixcontroller中的控制器协程负责装配和维护，整体工作流程如下：
	69	+
	70	+1. 拓扑上报：matrixagent采集本节点`superPodId`与邻居链路信息，将拓扑信息与NUMA内存信息写入MatrixMetric CR。
	71	+2. 事件触发：MatrixMetric CR的增、改、删事件触发去抖调谐（5s去抖窗口）；同时每5min执行一次周期全量resync。
	72	+3. 调谐流程：控制器执行一次完整reconcile：
	73	+ 1. 校验`SuperPod` CRD已注册，未就绪则退避重试。
	74	+ 2. 若开启`HYPERNODE_ENABLED=true`，校验`HyperNode` CRD已注册；未就绪则跳过HyperNode装配，仅产出`SuperPod`。
	75	+ 3. 读取全部MatrixMetric CR与Node标签，解析每个节点的`superPodId`与内存信息。
	76	+ 4. superPodId解析：节点label优先，metric字段次之；二者皆空则跳过该节点。
	77	+ 5. 按`superPodId`分组所有节点，FM组网下同一`superPodId`的所有节点装入单个Tier-1 group（`group-0`）。
	78	+ 6. 若开启HyperNode，每个`superPodId`额外生成一个Tier-1 `HyperNode` CR。
	79	+ 7. 创建或更新各SuperPod/HyperNode CR，并清理已不存在的stale CR。
	80	+
	81	+#### 指标采集机制
	82	+
	83	+`superpod-exporter`以独立DaemonSet部署于SuperPod中（通过节点亲和性筛选标签包含`unifiedbus.com/superpod`的节点），经HTTP`/metrics`（默认`:9102/metrics`）暴露Prometheus指标，由集群监控平台抓取。指标为节点级：所有指标均携带`node`/`slot_id`label；URMA虽为SuperPod粒度数据，但每节点全量上报后通过PromQL `min by`聚合为SuperPod级视图。采集周期由Prometheus `scrape_interval`驱动（建议30s），导出器对低频数据（拓扑）做缓存（12h），高频数据（借用/设备）实时采集。
	84	+
	85	+> ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	86	+> - `superpod_name`label取自本节点K8s Node标签`unifiedbus.com/superpod`，缓存12h。标签缺失时为`"unknown"`。
	87	+> - URMA设备为SuperPod粒度数据，采用每节点全量上报 + PromQL `min by (superpod_name, device_name)`聚合去重模式（故障优先，任一节点观测到故障即判故障）。
	88	+
	89	+### 与相关特性的关系
	X X xijing9 天前与相关特性的关系与实现原理是同级别章节不是子章节
	90	+
	91	+- 依赖UBS Engine：matrixagent上报的拓扑信息依赖底层ubs-engine及其拓扑发现组件，需预先安装，UBS Engine SDK socket（`/run/ubse`）需可用。
	92	+- 与容器内存借用特性共用组件：SuperPod与容器内存借用特性共用matrixagent、matrixcontroller组件，部署流程一致（参见[安装](#安装)章节）。
	93	+- 可选联动Volcano HyperNode：需集群已安装Volcano并注册`hypernodes` CRD（`topology.volcano.sh/v1alpha1`）。Volcano Scheduler需开启network-topology特性以消费`HyperNode`执行网络拓扑感知调度。未安装Volcano时保持`HYPERNODE_ENABLED=false`（默认值）即可，仅产生`SuperPod` CR。
	94	+- 与Prometheus/Grafana监控平台关系：`superpod-exporter`以Prometheus文本格式暴露`ubs_*`指标，需集群已部署Prometheus（抓取方）与Grafana（可视化，可选）方可汇聚查看。不部署监控平台时导出器仍运行，但指标无人消费。`superpod-exporter`不创建任何CR，不影响调度与既有资源。
	95	+
	96	+### 相关实例
	97	+
	98	+业务Pod使用样例请参见本文档[配置样例](#配置样例)小节，包括SuperPod CR、HyperNode CR以及基于Volcano gang调度将业务Pod部署到同一SuperPod的完整示例。`superpod-exporter`指标输出样例与Grafana PromQL汇聚示例亦参见[配置样例](#配置样例)小节。
	99	+
	100	+## 安装
	101	+
	102	+### 前提条件
	103	+
	104	+* 操作系统： openEuler 24.03 LTS SP3或更高版本
	105	+* CPU架构： ARM64
	106	+* 内存：大于等于64GB
	107	+* 磁盘： SSD，IOPS 500MB/s
	108	+* 芯片互联： UB
	109	+* 用户权限：安装与管理需root权限
	110	+* 软件要求：
	111	+ 1. Kubernetes v1.31.1及以上版本。
	112	+ 2. 参考[ubs-engine](https://gitcode.com/openeuler/ubs-engine)安装ubs-engine及其依赖组件，确保UBS Engine SDK socket（`/run/ubse`）可用。
	113	+ 3. 参考[Helm安装文档](https://helm.sh/docs/intro/install/)安装Helm。
	114	+ 4. （可选）如需使用`superpod-exporter`指标采集与上报能力，需集群已部署Prometheus（抓取方）与Grafana（可视化，可选），且目标节点已配置`unifiedbus.com/superpod`标签。
	115	+
	116	+### 开始安装
	117	+
	118	+1. 构建指导。
	119	+
	120	+ 1.1 拉取源码。
	121	+
	122	+ ```shell
	123	+ git clone -b master https://gitcode.com/openFuyao/ubs-k8s-enable.git
	124	+ ```
	125	+
	126	+ 1.2 安装依赖。
	127	+
	128	+ 构建前请确保宿主机已安装以下工具（版本要求如下）：
	129	+
	130	+ ```shell
	131	+ docker # 版本要求 > 20.10
	132	+ helm # 版本要求 v3 及以上
	133	+ ```
	134	+ Dockerfile使用了BuildKit特性，执行`docker build`前请确保已启用BuildKit。
	135	+
	136	+ 1.3 执行构建镜像。
	137	+
	138	+ ```shell
	139	+ # 版本号示例，可按实际发布版本调整
	140	+ export VERSION=1.0.0
	141	+ export DOCKER_BUILDKIT=1
	142	+
	143	+ # 构建 matrixagent 镜像
	144	+ # 如需使用自定义镜像仓，请将 cr.openfuyao.cn 替换为实际镜像仓库地址
	145	+ docker build -f build/matrixagent.dockerfile -t cr.openfuyao.cn/openfuyao/matrixagent:${VERSION} .
	146	+
	147	+ # 构建 matrixcontroller 镜像
	148	+ docker build -f build/matrixcontroller.dockerfile -t cr.openfuyao.cn/openfuyao/matrixcontroller:${VERSION} .
	149	+ ```
	150	+
	151	+ 1.4 导出镜像包。
	152	+
	153	+ ```shell
	154	+ mkdir -p output
	155	+
	156	+ docker save cr.openfuyao.cn/openfuyao/matrixagent:${VERSION} \| gzip -c > output/ubs-k8s.matrixagent.image.${VERSION}.aarch64.tgz
	157	+ docker save cr.openfuyao.cn/openfuyao/matrixcontroller:${VERSION} \| gzip -c > output/ubs-k8s.matrixcontroller.image.${VERSION}.aarch64.tgz
	158	+ ```
	159	+
	160	+ 1.5 打包Helm Chart。
	161	+
	162	+ ```shell
	163	+ helm package charts/matrixagent --destination output
	164	+ helm package charts/matrixcontroller --destination output
	165	+ mv output/matrixagent-*.tgz output/ubs-k8s.matrixagent.chart.${VERSION}.aarch64.tgz
	166	+ mv output/matrixcontroller-*.tgz output/ubs-k8s.matrixcontroller.chart.${VERSION}.aarch64.tgz
	167	+ ```
	168	+ 构建产物如下：
	169	+ ```
	170	+ └── output
	171	+ ├── ubs-k8s.matrixagent.image.${VERSION}.aarch64.tgz
	172	+ ├── ubs-k8s.matrixagent.chart.${VERSION}.aarch64.tgz
	173	+ ├── ubs-k8s.matrixcontroller.image.${VERSION}.aarch64.tgz
	174	+ ├── ubs-k8s.matrixcontroller.chart.${VERSION}.aarch64.tgz
	175	+ ```
	176	+
	177	+ 1.6 （可选）构建superpod-exporter镜像与Chart。
	178	+ 如需使用指标采集与上报能力，需额外构建`superpod-exporter`镜像与Chart。
	179	+
	180	+ ```shell
	181	+ export VERSION=1.0.0
	182	+ export DOCKER_BUILDKIT=1
	183	+
	184	+ # 构建 superpod-exporter 镜像
	185	+ # 如需使用自定义镜像仓，请将 cr.openfuyao.cn 替换为实际镜像仓库地址
	186	+ docker build -f build/superpodexporter.dockerfile -t cr.openfuyao.cn/openfuyao/superpod-exporter:${VERSION} .
	187	+
	188	+ # 导出镜像包
	189	+ docker save cr.openfuyao.cn/openfuyao/superpod-exporter:${VERSION} \| gzip -c > output/ubs-k8s.superpodexporter.image.${VERSION}.aarch64.tgz
	190	+
	191	+ # 打包Helm Chart
	192	+ helm package charts/superpodexporter --destination output
	193	+ mv output/superpod-exporter-*.tgz output/ubs-k8s.superpodexporter.chart.${VERSION}.aarch64.tgz
	194	+ ```
	195	+
	196	+ 构建产物更新如下：
	197	+ ```
	198	+ └── output
	199	+ ├── ubs-k8s.matrixagent.image.${VERSION}.aarch64.tgz
	200	+ ├── ubs-k8s.matrixagent.chart.${VERSION}.aarch64.tgz
	201	+ ├── ubs-k8s.matrixcontroller.image.${VERSION}.aarch64.tgz
	202	+ ├── ubs-k8s.matrixcontroller.chart.${VERSION}.aarch64.tgz
	203	+ ├── ubs-k8s.superpodexporter.image.${VERSION}.aarch64.tgz
	204	+ ├── ubs-k8s.superpodexporter.chart.${VERSION}.aarch64.tgz
	205	+ ```
	206	+
	207	+2. 部署步骤。
	208	+ 执行如下命令，设置版本变量：
	209	+
	210	+ ```bash
	211	+ export VERSION=1.0.0
	212	+ export OCI_VERSION=0.0.0-latest
	213	+ ```
	214	+
	215	+ > ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	216	+ > `VERSION`用于离线方式（方式一）匹配本地构建产物版本号；`OCI_VERSION`用于在线方式（方式二）从OCI仓拉取Chart的版本号，两者相互独立，按实际场景设置其一即可。
	217	+
	218	+ 2.1 获取部署文件。
	219	+ 可根据实际场景选择以下任一种方式获取部署所需镜像和Helm Chart。
	220	+
	221	+ - 方式一：使用离线发布件。
	222	+
	223	+ 准备以下文件：
	224	+
	225	+ * `ubs-k8s.matrixagent.image.${VERSION}.aarch64.tgz`
	226	+ * `ubs-k8s.matrixagent.chart.${VERSION}.aarch64.tgz`
	227	+ * `ubs-k8s.matrixcontroller.image.${VERSION}.aarch64.tgz`
	228	+ * `ubs-k8s.matrixcontroller.chart.${VERSION}.aarch64.tgz`
	229	+
	230	+ - 方式二：从镜像仓和OCI仓获取。
	231	+
	232	+ 拉取镜像：
	233	+
	234	+ ```bash
	235	+ docker pull cr.openfuyao.cn/openfuyao/matrixcontroller:latest
	236	+ docker pull cr.openfuyao.cn/openfuyao/matrixagent:latest
	237	+ ```
	238	+
	239	+ 拉取Helm Chart：
	240	+
	241	+ ```bash
	242	+ helm pull oci://cr.openfuyao.cn/charts/matrixagent --version ${OCI_VERSION}
	243	+ helm pull oci://cr.openfuyao.cn/charts/matrixcontroller --version ${OCI_VERSION}
	244	+ ```
	245	+
	246	+ 2.2 导入离线镜像（仅离线方式）。
	247	+
	248	+ ```bash
	249	+ gunzip -c ubs-k8s.matrixagent.image.${VERSION}.aarch64.tgz \| ctr -n k8s.io images import -
	250	+ gunzip -c ubs-k8s.matrixcontroller.image.${VERSION}.aarch64.tgz \| ctr -n k8s.io images import -
	251	+ ```
	252	+ > ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	253	+ > 步骤1.4使用`docker save`导出的镜像包为docker tar格式，`ctr images import`兼容该格式可直接导入，无需额外转换。
	254	+ > 如果使用"方式二"直接从镜像仓拉取镜像，可跳过此步骤。
	255	+
	256	+ 2.3 部署服务。
	257	+ 可根据实际场景选择以下任一种方式部署服务。
	258	+ - 使用离线Chart部署。
	259	+
	260	+ ```bash
	261	+ helm install matrixagent ubs-k8s.matrixagent.chart.${VERSION}.aarch64.tgz -n kube-system \
	262	+ --set images.matrixagent.tag=${VERSION}
	263	+ helm install matrixcontroller ubs-k8s.matrixcontroller.chart.${VERSION}.aarch64.tgz -n kube-system \
	264	+ --set images.matrixcontroller.tag=${VERSION}
	265	+ ```
	266	+ - 使用OCI Chart部署。
	267	+
	268	+ ```bash
	269	+ helm install matrixagent oci://cr.openfuyao.cn/charts/matrixagent --version ${OCI_VERSION} -n kube-system \
	270	+ --set images.matrixagent.tag=latest
	271	+ helm install matrixcontroller oci://cr.openfuyao.cn/charts/matrixcontroller --version ${OCI_VERSION} -n kube-system \
	272	+ --set images.matrixcontroller.tag=latest
	273	+ ```
	274	+ 2.4 验证结果。
	275	+ 执行以下命令，查看Pod状态。
	276	+
	277	+ ```bash
	278	+ kubectl get pods -A
	279	+ ```
	280	+
	281	+ 预期结果如下：
	282	+ * 每个节点应有对应的`matrixagent`相关Pod，且状态为`Running`。
	283	+ * 集群中应有`matrixcontroller`相关Pod，且状态为`Running`。
	284	+
	285	+ 2.5 （可选）部署superpod-exporter。
	286	+ 如需使用指标采集与上报能力，部署`superpod-exporter` DaemonSet。
	287	+
	288	+ - 方式一：使用离线Chart部署。
	289	+
	290	+ ```bash
	291	+ helm install superpod-exporter ubs-k8s.superpodexporter.chart.${VERSION}.aarch64.tgz -n kube-system \
	292	+ --set image.tag=${VERSION}
	293	+ ```
	294	+
	295	+ - 方式二：使用OCI Chart部署。
	296	+
	297	+ ```bash
	298	+ helm install superpod-exporter oci://cr.openfuyao.cn/charts/superpod-exporter --version ${OCI_VERSION} -n kube-system \
	299	+ --set image.tag=latest
	300	+ ```
	301	+
	302	+ > ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	303	+ > superpod-exporter DaemonSet默认配置节点亲和性筛选`unifiedbus.com/superpod`标签节点、暴露9102端口、关联ServiceAccount。如需对接Prometheus Operator自动发现，可在部署时设置`serviceMonitor.enabled=true`。部署前请确认目标节点`unifiedbus.com/superpod`标签已配置且UBS socket可访问。
	304	+
	305	+ 验证superpod-exporter部署结果：
	306	+
	307	+ ```bash
	308	+ kubectl get pods -n kube-system -l app.kubernetes.io/name=superpod-exporter -o wide
	309	+ ```
	310	+
	311	+ 预期结果：每个配置了`unifiedbus.com/superpod`标签的节点应有对应的`superpod-exporter`Pod，且状态为`Running`。
	312	+
	313	+## 使用SuperPod
	314	+
	315	+### 前提条件
	316	+
	317	+- 已按[安装](#安装)章节完成matrixagent、matrixcontroller组件部署，且各组件Pod状态为`Running`。
	318	+- UBS Engine SDK socket（`/run/ubse`）可用。
	319	+- （可选）若需使能Volcano HyperNode联动，需已安装Volcano并注册`hypernodes` CRD（`topology.volcano.sh/v1alpha1`），Volcano Scheduler需开启network-topology特性。
	320	+- （可选）若需查看SuperPod指标，需已按[安装](#安装)章节2.5部署`superpod-exporter`，且已部署Prometheus抓取与Grafana可视化。
	321	+
	322	+### 背景信息
	323	+
	324	+在大规模集群或UB互联场景中，单节点视角的调度无法感知物理拓扑边界，容易导致跨SuperPod的负载分散，通信效率下降。通过部署UBS K8S Enable相关组件中的SuperPod控制器，可以将物理节点按`superPodId`聚合成逻辑拓扑单元，并以`SuperPod` CR的形式暴露给上层调度器。开启`HYPERNODE_ENABLED=true`后，控制器额外产出Volcano `HyperNode` CR，使Volcano调度器可基于拓扑层级执行网络拓扑感知调度，将通信密集型负载（如分布式训练）调度到同一SuperPod内，提升通信局部性与故障隔离能力。SuperPod控制器以声明式方式自动维护`SuperPod`/`HyperNode` CR的生命周期，无需人工干预。
	325	+
	326	+当前版本不支持Clos组网。
	327	+
	328	+`superpod-exporter`组件以Prometheus格式暴露SuperPod成员关系、NUMA内存借用、共享内存、URMA设备等指标，管理员可在监控平台查看各SuperPod资源使用与健康度，无需登录节点执行CLI，便于及时发现资源倾斜与设备故障（指标定义详见[配置说明-指标定义](#指标定义)，使用样例详见[配置样例](#配置样例)）。
	329	+
	330	+### 使用限制
	331	+
	332	+- 组网限制：不支持Clos组网。
	333	+- 架构限制：仅支持ARM64架构。
	334	+- superPodId来源要求：节点必须具备以下任一superPodId来源，否则该节点不会被纳入任何`SuperPod`：
	335	+ - 节点label `unifiedbus.com/superpod`；
	336	+ - matrixagent上报的`node_network_topology_info`中包含非空`superPodId`字段。
	337	+- 层级限制：FM组网下顶层Tier恒为1，同一`superPodId`下所有节点被装入同一个Tier-1 group（`group-0`）。Volcano拓扑约束`highest-tier`只能取`"1"`。
	338	+- HyperNode联动前置：开启`HYPERNODE_ENABLED=true`时，集群必须已安装Volcano并注册`hypernodes` CRD；否则控制器会跳过HyperNode装配，仅产生`SuperPod` CR。
	339	+- 覆盖语义：节点label是`superPodId`的优先来源。若节点同时存在label和metric中的`superPodId`，以label为准；label为空时才回退使用metric值。
	340	+- 指标导出器限制：
	341	+ - 节点标签`unifiedbus.com/superpod`缺失或RBAC权限不足时，`superpod_name`回退为`"unknown"`，SuperPod级汇聚不可用，节点级指标正常。
	342	+ - URMA服务不支持时`ubs_urma_*`指标缺失，其他类别指标正常。
	343	+
	344	+> ![image](./figures/icon-notice.gif) 注意：
	345	+>
	346	+> - `SuperPod` CR为cluster scope资源，`metadata.name`由控制器按`superpod-<superPodId>`规则自动生成，请勿手工创建或重命名，否则会被控制器视为stale资源删除。
	347	+> - 修改节点label后，控制器会在下一次去抖或周期resync时（最长5min）生效，无需重启matrixcontroller。
	348	+
	349	+### 配置说明
	350	+
	351	+`SuperPod` CRD注册于`resource.matrix.huawei.com`组、`v1`版本、cluster scope，资源名`superpods`。其字段说明如下。
	352	+
	353	+表3 SuperPod CR字段说明
	354	+
	355	+\| 字段路径 \| 类型 \| 说明 \|
	356	+\| :--- \| :--- \| :--- \|
	357	+\| `spec.superPodId` \| string \| 必选。SuperPod标识，直接决定SuperPod命名（`superpod-<superPodId>`）。 \|
	358	+\| `spec.tier` \| integer \| 必选。SuperPod顶层层级。FM组网下固定为1。 \|
	359	+\| `spec.hyperNodeRef` \| string \| 可选。引用顶层Volcano HyperNode名称，仅当`HYPERNODE_ENABLED=true`时填充，格式为`hn-t1-<superPodId>`。 \|
	360	+\| `spec.groups[]` \| array \| 必选。Tier-1拓扑子分组列表。FM组网下每个SuperPod仅含一个group（`group-0`），包含该SuperPod下全部节点。 \|
	361	+\| `spec.groups[].name` \| string \| group名称，格式为`group-<ordinal>`（FM下为`group-0`）。 \|
	362	+\| `spec.groups[].tier` \| integer \| group层级，FM组网下固定为1。 \|
	363	+\| `spec.groups[].hyperNodeRef` \| string \| 可选。引用该group对应的Tier-1 HyperNode，仅当`HYPERNODE_ENABLED=true`时填充。 \|
	364	+\| `spec.groups[].nodes[]` \| array \| group下的节点资源信息列表。 \|
	365	+\| `spec.groups[].nodes[].name` \| string \| 节点名。 \|
	366	+\| `spec.groups[].nodes[].ip` \| string \| 节点内网IP地址。 \|
	367	+\| `spec.groups[].nodes[].memory.total` \| string \| 节点物理内存总量（BinarySI，如`256Gi`）。 \|
	368	+\| `spec.groups[].nodes[].memory.used` \| string \| 节点已用物理内存（BinarySI）。 \|
	369	+\| `status.nodeCount` \| integer \| SuperPod成员节点数。 \|
	370	+\| `status.conditions[]` \| array \| 状态条件列表，遵循Kubernetes Condition规范。 \|
	371	+\| `metadata.annotations["superpod.matrix.huawei.com/node-hash"]` \| string \| 成员节点名排序后SHA256取前8字符，作为拓扑指纹，用于成员变更校验。 \|
	372	+
	373	+#### 指标定义
	374	+
	375	+`superpod-exporter`产出的Prometheus指标统一`ubs_`前缀，单位字节。指标为节点级，所有指标携带`node`/`slot_id`label，SuperPod维度以`superpod_name`label承载。
	376	+
	377	+表5 superpod-exporter公共Label语义
	378	+
	379	+\| Label \| 含义 \|
	380	+\| :--- \| :--- \|
	381	+\| `superpod_name` \| SuperPod名称，取自节点标签`unifiedbus.com/superpod` \|
	382	+\| `node` \| K8s节点名 \|
	383	+\| `slot_id` \| UBS物理节点唯一标识 \|
	384	+\| `export_node` \| 借出/提供方节点的K8s节点名 \|
	385	+\| `export_slot_id` \| 借出/提供方节点的UBS slot_id \|
	386	+\| `name` \| 借用/共享资源的名称 \|
	387	+\| `numa_id` \| 借用形成的远端NUMA id \|
	388	+\| `device_name` \| URMA设备名称 \|
	389	+\| `hw_res_id` \| URMA硬件资源ID \|
	390	+
	391	+表6 superpod-exporter指标定义
	392	+
	393	+\| 指标名 \| 描述 \| 数据类型 \| 指标值 \| 指标label \|
	394	+\| :--- \| :--- \| :--- \| :--- \| :--- \|
	395	+\| `ubs_exporter_up` \| superpod-exporter就绪状态 \| Gauge \| 1=就绪，0=不可用 \| 无 \|
	396	+\| `ubs_superpod_info` \| 节点与SuperPod归属信息 \| Gauge \| 恒1 \| `superpod_name`, `node`, `slot_id` \|
	397	+\| `ubs_mem_numa_borrow_bytes` \| 本节点借入的NUMA远端内存大小 \| Gauge \| NUMA借用大小（字节） \| `superpod_name`, `node`, `slot_id`, `export_node`, `export_slot_id`, `numa_id`, `name` \|
	398	+\| `ubs_mem_numa_borrow_count` \| 本节点NUMA借用关系数 \| Gauge \| NUMA借用关系总数 \| `superpod_name`, `node`, `slot_id` \|
	399	+\| `ubs_mem_shm_provide_bytes` \| 本节点提供的共享内存大小 \| Gauge \| 共享内存大小（字节） \| `superpod_name`, `node`, `slot_id`, `name` \|
	400	+\| `ubs_mem_shm_provide_count` \| 本节点提供的共享内存数 \| Gauge \| 共享内存数 \| `superpod_name`, `node`, `slot_id` \|
	401	+\| `ubs_urma_device_info` \| URMA设备信息（用于发现/关联） \| Gauge \| 恒1 \| `superpod_name`, `node`, `slot_id`, `device_name`, `hw_res_id` \|
	402	+\| `ubs_urma_device_healthy` \| URMA设备健康状态 \| Gauge \| 1=健康，0=故障 \| `superpod_name`, `node`, `slot_id`, `device_name` \|
	403	+
	404	+### 配置样例
	405	+
	406	+表2 FM组网组装结果
	407	+
	408	+以含2个SuperPod（`superPodId=0`、`superPodId=1`，共16节点）的集群为例，组装产出（按`superPodId`分组为2个SuperPod，FM全互联下每SuperPod内仅单Tier-1子组，topTier=1）：
	409	+
	410	+\| 层级 \| HyperNode \| 成员类型 \| 成员 \| 说明 \|
	411	+\| :--- \| :--- \| :--- \| :--- \| :--- \|
	412	+\| Tier 1 \| `hn-t1-0` \| Node \| node1~node8 \| SuperPod A内8节点1跳连通分量。 \|
	413	+\| Tier 1 \| `hn-t1-1` \| Node \| node9~node16 \| SuperPod B内8节点1跳连通分量。 \|
	414	+
	415	+样例1：SuperPod CR（FM组网，8节点全互联，`HYPERNODE_ENABLED=true`）。
	416	+
	417	+```yaml
	418	+apiVersion: resource.matrix.huawei.com/v1
	419	+kind: SuperPod
	420	+metadata:
	421	+ name: superpod-0 # 命名直接来自 superPodId
	422	+ annotations:
	423	+ superpod.matrix.huawei.com/node-hash: a1b2c3d4 # 成员节点名排序 hash 前 8 位
	424	+spec:
	425	+ superPodId: "0" # SuperPod 标识
	426	+ tier: 1 # FM 全互联，仅 Tier-1
	427	+ hyperNodeRef: hn-t1-0 # 引用顶层 HyperNode（HYPERNODE_ENABLED=true 时填充）
	428	+ groups: # 单组（全体8节点1跳连通）
	429	+ - name: group-0
	430	+ tier: 1
	431	+ hyperNodeRef: hn-t1-0 # 引用同层 Tier-1 HyperNode
	432	+ nodes:
	433	+ - name: node1
	434	+ ip: "10.8.0.1"
	435	+ memory:
	436	+ total: "256Gi"
	437	+ used: "128Gi"
	438	+ # ... node2 ~ node7
	439	+ - name: node8
	440	+ ip: "10.8.0.8"
	441	+ memory:
	442	+ total: "256Gi"
	443	+ used: "120Gi"
	444	+status:
	445	+ nodeCount: 8
	446	+```
	447	+
	448	+> ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	449	+> 当`HYPERNODE_ENABLED=false`（默认）时，`hyperNodeRef`字段留空，SuperPod仍完整承载`superPodId`、拓扑层级与节点资源，仅不引用HyperNode。上方示例为启用时的形态，未启用时将`hyperNodeRef`行去掉即可。
	450	+
	451	+样例2：HyperNode CR（FM组网，Tier-1，8节点全互联，`HYPERNODE_ENABLED=true`时由控制器自动产出）。
	452	+
	453	+```yaml
	454	+apiVersion: topology.volcano.sh/v1alpha1
	455	+kind: HyperNode
	456	+metadata:
	457	+ name: hn-t1-0
	458	+spec:
	459	+ tier: 1
	460	+ tierName: "superpod"
	461	+ members:
	462	+ - type: Node
	463	+ selector:
	464	+ exactMatch:
	465	+ name: node1
	466	+ # ... node2 ~ node7
	467	+ - type: Node
	468	+ selector:
	469	+ exactMatch:
	470	+ name: node8
	471	+status:
	472	+ nodeCount: 8
	473	+```
	474	+
	475	+样例3：三Pod Gang部署到同一SuperPod（FM组网，`highest-tier=1`）。
	476	+
	477	+场景：3个业务Pod（如分布式训练Worker）需部署在同一个SuperPod内以使用高速互联与池化内存通信，且要求gang调度（3个全部调度成功，否则全部等待）。
	478	+
	479	+1. PodGroup：声明gang策略 + 拓扑硬约束。
	480	+
	481	+```yaml
	482	+apiVersion: scheduling.volcano.sh/v1beta1
	483	+kind: PodGroup
	484	+metadata:
	485	+ name: gang-in-superpod
	486	+ annotations:
	487	+ volcano.sh/network-topology-mode: "hard" # 硬约束：同组 Pod 必须落在同一 HyperNode
	488	+ volcano.sh/network-topology-highest-tier: "1" # FM 组网仅 Tier-1，限制在同一 SuperPod 内
	489	+spec:
	490	+ minMember: 3 # gang 策略：3 个 Pod 必须全部调度成功，否则全部 pending
	491	+ queue: default
	492	+ priorityClassName: high
	493	+```
	494	+
	495	+2. 业务Pod：关联PodGroup，由Volcano调度。
	496	+
	497	+```yaml
	498	+apiVersion: v1
	499	+kind: Pod
	500	+metadata:
	501	+ name: worker-0
	502	+ annotations:
	503	+ scheduling.k8s.io/group-name: gang-in-superpod # 关联 PodGroup
	504	+spec:
	505	+ schedulerName: volcano # 使用 Volcano 调度器
	506	+ containers:
	507	+ - name: worker
	508	+ image: registry.example.com/app/worker:1.0
	509	+ resources:
	510	+ requests: { cpu: "8", memory: "16Gi" }
	511	+ limits: { cpu: "8", memory: "16Gi" }
	512	+---
	513	+apiVersion: v1
	514	+kind: Pod
	515	+metadata:
	516	+ name: worker-1
	517	+ annotations:
	518	+ scheduling.k8s.io/group-name: gang-in-superpod
	519	+spec:
	520	+ schedulerName: volcano
	521	+ containers:
	522	+ - name: worker
	523	+ image: registry.example.com/app/worker:1.0
	524	+ resources:
	525	+ requests: { cpu: "8", memory: "16Gi" }
	526	+ limits: { cpu: "8", memory: "16Gi" }
	527	+---
	528	+apiVersion: v1
	529	+kind: Pod
	530	+metadata:
	531	+ name: worker-2
	532	+ annotations:
	533	+ scheduling.k8s.io/group-name: gang-in-superpod
	534	+spec:
	535	+ schedulerName: volcano
	536	+ containers:
	537	+ - name: worker
	538	+ image: registry.example.com/app/worker:1.0
	X X xijing9 天前这个是不是占位域名，是的话建议标明需要替换为实际镜像地址
	539	+ resources:
	540	+ requests: { cpu: "8", memory: "16Gi" }
	541	+ limits: { cpu: "8", memory: "16Gi" }
	542	+```
	543	+
	544	+> ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	545	+> - gang + hard topology组合：Volcano先做gang检查（`minMember`），再做拓扑约束校验；`hard`模式下若没有任何Tier-1 HyperNode能同时容纳3个Pod，则全部pending，不会部分调度。
	546	+> - soft模式（可选）：将`mode`改为`soft`，则拓扑为打分偏好而非硬约束，优先调度到同一SuperPod但允许降级到其他SuperPod。
	547	+> - FM组网`highest-tier`：FM下SuperPod间不互联，`highest-tier`只能取`"1"`。
	548	+
	549	+样例4：superpod-exporter指标输出样例（`curl <node>:9102/metrics`，节选）。
	550	+
	551	+```
	552	+# HELP ubs_exporter_up superpod-exporter is up and UBSE SDK is initialized (1=up, 0=SDK unavailable).
	553	+# TYPE ubs_exporter_up gauge
	554	+ubs_exporter_up 1
	555	+# HELP ubs_superpod_info SuperPod membership info: which SuperPods exist and which physical nodes belong to each.
	556	+# TYPE ubs_superpod_info gauge
	557	+ubs_superpod_info{superpod_name="0",node="node1",slot_id="1"} 1
	558	+ubs_superpod_info{superpod_name="0",node="node2",slot_id="2"} 1
	559	+# HELP ubs_mem_numa_borrow_bytes Bytes of numa-form remote memory borrowed by this node from export_node.
	560	+# TYPE ubs_mem_numa_borrow_bytes gauge
	561	+ubs_mem_numa_borrow_bytes{superpod_name="0",node="node1",slot_id="1",export_node="node2",export_slot_id="2",numa_id="4",name="numa-remote-0"} 2.147483648e+09
	562	+# HELP ubs_mem_numa_borrow_count Number of numa-form memory borrow relationships on this node.
	563	+# TYPE ubs_mem_numa_borrow_count gauge
	564	+ubs_mem_numa_borrow_count{superpod_name="0",node="node1",slot_id="1"} 1
	565	+# HELP ubs_mem_shm_provide_bytes Bytes of shared memory provided by this node (export_node == local).
	566	+# TYPE ubs_mem_shm_provide_bytes gauge
	567	+ubs_mem_shm_provide_bytes{superpod_name="0",node="node1",slot_id="1",name="shm-provide-0"} 1.073741824e+09
	568	+# HELP ubs_mem_shm_provide_count Number of shared memory regions provided by this node.
	569	+# TYPE ubs_mem_shm_provide_count gauge
	570	+ubs_mem_shm_provide_count{superpod_name="0",node="node1",slot_id="1"} 1
	571	+# HELP ubs_urma_device_info URMA device info (always 1, used for discovery/association).
	572	+# TYPE ubs_urma_device_info gauge
	573	+ubs_urma_device_info{superpod_name="0",node="node1",slot_id="1",device_name="urma-0",hw_res_id="100"} 1
	574	+# HELP ubs_urma_device_healthy URMA device health status: 1=healthy, 0=fault.
	575	+# TYPE ubs_urma_device_healthy gauge
	576	+ubs_urma_device_healthy{superpod_name="0",node="node1",slot_id="1",device_name="urma-0"} 1
	577	+```
	578	+
	579	+样例5：Grafana PromQL汇聚示例。
	580	+
	581	+\| 视图 \| PromQL \|
	582	+\| :--- \| :--- \|
	583	+\| SuperPod数量 \| `count(count by (superpod_name)(ubs_superpod_info))` \|
	584	+\| 各SuperPod物理节点数 \| `count by (superpod_name)(ubs_superpod_info)` \|
	585	+\| 指定SuperPod的成员节点列表 \| `ubs_superpod_info{superpod_name="$superpod"}` \|
	586	+\| SuperPod NUMA借入总量 \| `sum by (superpod_name)(ubs_mem_numa_borrow_bytes)` \|
	587	+\| 节点NUMA借入总量 \| `sum by (node)(ubs_mem_numa_borrow_bytes)` \|
	588	+\| 节点借出总量 \| `sum by (export_node)(ubs_mem_numa_borrow_bytes)` \|
	589	+\| SuperPod共享内存提供总量 \| `sum by (superpod_name)(ubs_mem_shm_provide_bytes)` \|
	590	+\| SuperPod URMA健康设备数 \| `sum by (superpod_name)(min by (superpod_name, device_name)(ubs_urma_device_healthy))` \|
	591	+\| URMA故障设备 \| `min by (superpod_name, device_name)(ubs_urma_device_healthy) == 0` \|
	592	+
	593	+> ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	594	+> - URMA指标为SuperPod粒度数据，每节点全量上报会产生N份重复series，SuperPod级查询必须带`min by (superpod_name, device_name)`前缀聚合去重（故障优先，任一节点观测到故障即判故障）。
	595	+> - 节点内存借还仅有一种运行态（借入或借出的关系实例），借还总量可直接由本节点已上报的借用关系series汇总得出：节点借入总量 = `sum by (node)(ubs_mem_numa_borrow_bytes)`，节点借出总量 = `sum by (export_node)(ubs_mem_numa_borrow_bytes)`。
	596	+
	597	+### 操作步骤
	598	+
	599	+1. 使能SuperPod拓扑纳管。
	600	+ 前置条件
	601	+ 完成matrixagent和matrixcontroller的安装。UBS Engine SDK socket（`/run/ubse`）可用。
	602	+ 1.1 配置节点superPodId标签。
	603	+ 在K8s的master节点通过命令行配置worker节点的标签，标识节点所属的SuperPod。节点label是superPodId的优先来源，未打标签的节点会回退使用matrixagent上报的`superPodId`字段；二者皆空则该节点不会被纳入任何SuperPod。
	604	+
	605	+ ```shell
	606	+ kubectl label nodes <node-name> unifiedbus.com/superpod=<superPodId>
	607	+ # <superPodId> 替换为该节点所属的 SuperPod 标识（如 0、1、2）
	608	+ # <node-name> 替换为需要纳管的节点名
	609	+ # 示例：将 node1~node8 归入 SuperPod 0（FM 组网）
	610	+ # kubectl label nodes node1 unifiedbus.com/superpod=0
	611	+ # kubectl label nodes node2 unifiedbus.com/superpod=0
	612	+ # ... 至 node8
	613	+ ```
	614	+
	615	+ > ![输入图片说明](./figures/icon-note.gif) 说明：<br />
	616	+ > `unifiedbus.com/superpod`的值为字符串形式的superPodId，控制器据此将节点归入`superpod-<superPodId>`。FM组网下，建议同一UB互联域（同一SuperPod）内的所有物理节点使用相同的superPodId。
	617	+
	618	+ 1.2 （可选）使能Volcano HyperNode联动。
	619	+ 若需将SuperPod拓扑联动到Volcano的`HyperNode` CR（供Volcano调度器执行网络拓扑感知调度），需将matrixcontroller的环境变量`HYPERNODE_ENABLED`设置为`true`。默认值为`false`，即仅产生`SuperPod` CR，不联动HyperNode。
	620	+
	621	+ 前置条件：
	622	+ - 集群已安装Volcano并注册`hypernodes` CRD（`topology.volcano.sh/v1alpha1`）。可通过以下命令确认：
	623	+
	624	+ ```bash
	625	+ kubectl get crd hypernodes.topology.volcano.sh
	626	+ ```
	627	+
	628	+ - Volcano Scheduler已开启network-topology特性。
	629	+
	630	+ - 方式一：部署后通过`kubectl set env`修改（无需重新部署Chart）。
	X X xijing9 天前方式一的重启是否有等待时间需要说明 H huoran 8 天前评论： 8 天前评论：
	631	+
	632	+ ```bash
	633	+ kubectl set env deployment/matrixcontroller -n kube-system HYPERNODE_ENABLED=true
	634	+ kubectl rollout restart deployment/matrixcontroller -n kube-system
	635	+ ```
	636	+
	637	+ - 方式二：部署前修改`charts/matrixcontroller/templates/deploy.yaml`，将`HYPERNODE_ENABLED`的`value`改为`"true"`，再按[开始安装](#开始安装)中部署服务的步骤部署matrixcontroller。
	X X xijing9 天前三种获取部署文件的场景下是否可以直接编辑此文件 H huoran 8 天前评论： 8 天前评论：
	638	+
	639	+ > ![输入图片说明](./figures/icon-notice.gif) 注意：<br />
	640	+ > 仅当`HyperNode` CRD已注册时控制器才会装配HyperNode；若CRD未就绪，控制器会跳过HyperNode装配并打印告警日志，但`SuperPod` CR的产生不受影响。
	641	+
	642	+ 1.3 触发拓扑调谐。
	643	+ 完成节点label配置后，matrixcontroller会自动侦听MatrixMetric CR的变化并触发调谐：
	644	+ - MatrixMetric CR增、改、删事件触发去抖调谐（5s去抖窗口）。
	645	+ - 每5min执行一次周期全量resync。
	646	+ - 拓扑数据12h刷新一次。
	647	+
	648	+ 如需立即触发调谐，可等待matrixagent下一次上报，或手动触发MatrixMetric CR变更（如`kubectl annotate`任一MatrixMetric CR触发UpdateEvent）。
	649	+
	650	+ 1.4 验证SuperPod CR。
	651	+ 执行以下命令，查看集群中的SuperPod CR。
	652	+
	653	+ ```bash
	654	+ kubectl get superpods.resource.matrix.huawei.com
	655	+ ```
	656	+
	657	+ 预期结果：每个有节点归属的`superPodId`对应一个`superpod-<id>`资源，例如：
	658	+
	659	+ ```
	660	+ NAME SUPERPODID TIER NODECOUNT
	661	+ superpod-0 0 1 8
	662	+ superpod-1 1 1 8
	663	+ ```
	664	+
	665	+ 查看SuperPod详细信息（含group、节点、内存）：
	666	+
	667	+ ```bash
	668	+ kubectl get superpod superpod-0 -o yaml
	669	+ ```
	670	+
	671	+ 预期输出（FM组网，`HYPERNODE_ENABLED=true`，节选）：
	672	+
	673	+ ```yaml
	674	+ apiVersion: resource.matrix.huawei.com/v1
	675	+ kind: SuperPod
	676	+ metadata:
	677	+ name: superpod-0
	678	+ annotations:
	679	+ superpod.matrix.huawei.com/node-hash: a1b2c3d4
	680	+ spec:
	681	+ superPodId: "0"
	682	+ tier: 1
	683	+ hyperNodeRef: hn-t1-0
	684	+ groups:
	685	+ - name: group-0
	686	+ tier: 1
	687	+ hyperNodeRef: hn-t1-0
	688	+ nodes:
	689	+ - name: node1
	690	+ ip: 10.8.0.1
	691	+ memory:
	692	+ total: 256Gi
	693	+ used: 128Gi
	694	+ # ... node2 ~ node7
	695	+ - name: node8
	696	+ ip: 10.8.0.8
	697	+ memory:
	698	+ total: 256Gi
	699	+ used: 120Gi
	700	+ status:
	701	+ nodeCount: 8
	702	+ ```
	703	+
	704	+ 1.5 （可选）验证HyperNode CR。
	705	+ 若已开启`HYPERNODE_ENABLED=true`，执行以下命令查看联动产生的Volcano HyperNode CR。
	706	+
	707	+ ```bash
	708	+ kubectl get hypernodes.topology.volcano.sh
	709	+ ```
	710	+
	711	+ 预期结果：每个`superPodId`对应一个`hn-t1-<id>`资源，其`spec.members`包含该SuperPod下所有节点。
	712	+
	713	+ 1.6 查看节点哈希指纹。
	714	+ SuperPod的annotation `superpod.matrix.huawei.com/node-hash`为成员节点名排序后的SHA256取前8字符，可用于快速判断SuperPod成员拓扑是否变化。
	715	+
	716	+ ```bash
	717	+ kubectl get superpod <superpod-name> \
	718	+ -o jsonpath='{.metadata.annotations.superpod\.matrix\.huawei\.com/node-hash}'
	719	+ ```
	720	+
	721	+ - 观察拓扑变更结果。
	722	+ 当节点label变更或MatrixMetric CR更新导致SuperPod成员变化时，控制器会在下一次调谐中更新`SuperPod` CR的`spec.groups[].nodes[]`与`status.nodeCount`，并刷新`node-hash`。可重复执行验证SuperPod CR小节的命令观察变化。
	723	+2. （可选）业务Pod调度到同一SuperPod。
	724	+ 前置条件
	725	+ 完成HyperNode联动使能（[操作步骤](#操作步骤)的"使能SuperPod拓扑纳管"小节），Volcano Scheduler已开启network-topology特性。
	726	+ 2.1 创建PodGroup。
	727	+ 参考[配置样例-样例3](#配置样例)，创建声明gang策略与拓扑硬约束的PodGroup。FM组网下`highest-tier`只能取`"1"`。
	728	+
	729	+ ```bash
	730	+ kubectl apply -f podgroup-gang-in-superpod.yaml
	731	+ ```
	732	+
	733	+ 2.2 创建业务Pod。
	734	+ 创建关联PodGroup的业务Pod，由Volcano调度器调度。
	735	+
	736	+ ```bash
	737	+ kubectl apply -f workers.yaml
	738	+ ```
	739	+
	740	+ 2.3 验证调度结果。
	741	+ 执行以下命令，查看Pod调度状态。
	742	+
	743	+ ```bash
	744	+ kubectl get pod -o wide
	745	+ ```
	746	+
	747	+ 预期结果：3个worker Pod全部调度成功且位于同一SuperPod内（同一`superPodId`的节点上）。若没有任何Tier-1 HyperNode能同时容纳3个Pod，则全部pending。
	748	+3. （可选）验证superpod-exporter指标。
	749	+ 前置条件
	750	+ 已按[安装](#安装)章节2.5部署`superpod-exporter`，且Pod状态为`Running`。
	751	+ 3.1 验证导出器就绪。
	752	+ 执行以下命令，查看superpod-exporter Pod状态与就绪指标。
	753	+
	754	+ ```bash
	755	+ kubectl get pods -n kube-system -l app.kubernetes.io/name=superpod-exporter -o wide
	756	+ ```
	757	+
	758	+ 预期结果：每个配置了`unifiedbus.com/superpod`标签的节点应有对应的`superpod-exporter`Pod，且状态为`Running`。
	759	+
	760	+ 3.2 查询指标端点。
	761	+ 通过`kubectl exec`进入任一superpod-exporter Pod，或直接`curl`节点IP查询指标端点。
	762	+
	763	+ ```bash
	764	+ # 方式一：kubectl exec 查询
	765	+ POD=$(kubectl -n kube-system get pods -l app.kubernetes.io/name=superpod-exporter -o jsonpath='{.items[0].metadata.name}')
	766	+ kubectl -n kube-system exec $POD -- curl -s localhost:9102/metrics \| grep ubs_exporter_up
	767	+
	768	+ # 方式二：直接 curl 节点IP（需节点端口可达）
	769	+ curl -s <node-ip>:9102/metrics \| grep ubs_superpod_info
	770	+ ```
	771	+
	772	+ 预期结果：`ubs_exporter_up`值为1；`ubs_superpod_info`含本节点`node`/`slot_id`/`superpod_name`，`superpod_name`值与节点标签`unifiedbus.com/superpod`一致。
	773	+
	774	+ 3.3 验证SuperPod维度汇聚。
	775	+ 在Grafana或Prometheus中执行[配置样例-样例5](#配置样例)中的PromQL，验证SuperPod级汇聚视图。
	776	+
	777	+ ```bash
	778	+ # SuperPod数量
	779	+ count(count by (superpod_name)(ubs_superpod_info))
	780	+ # 各SuperPod物理节点数
	781	+ count by (superpod_name)(ubs_superpod_info)
	782	+ # SuperPod NUMA借入总量
	783	+ sum by (superpod_name)(ubs_mem_numa_borrow_bytes)
	784	+ # URMA故障设备
	785	+ min by (superpod_name, device_name)(ubs_urma_device_healthy) == 0
	786	+ ```
	787	+
	788	+ 预期结果：SuperPod数量、成员数、借入总量、URMA健康状态等查询返回正确结果。
	789	+
	790	+### 后续操作
	791	+
	792	+- 验证组件状态：通过`kubectl get pods -A`查看matrixagent、matrixcontroller与`superpod-exporter`运行状态，确认均为`Running`。
	793	+- 检查CRD注册：通过`kubectl get crd superpods.resource.matrix.huawei.com`确认SuperPod CRD已注册；若开启HyperNode联动，通过`kubectl get crd hypernodes.topology.volcano.sh`确认HyperNode CRD已注册。
	794	+- 验证指标导出器：通过`curl <node-ip>:9102/metrics`确认`ubs_exporter_up=1`且各`ubs_*`指标series数与节点实际借用关系一致；`superpod_name`应与节点标签一致，非`unknown`。
	795	+- 调整拓扑归属：如需调整某节点的SuperPod归属，重新执行[操作步骤](#操作步骤)中配置节点superPodId标签的步骤即可，无需重启matrixcontroller；控制器会在下一次去抖或周期resync时（最长5min）生效。`superpod-exporter`的`superpod_name`label源自节点标签，标签变更后exporter会在12h缓存到期后刷新，或重启exporter立即生效。
	796	+- 切换HyperNode联动：如需开启/关闭HyperNode联动，通过`kubectl set env deployment/matrixcontroller -n kube-system HYPERNODE_ENABLED=<true\|false>`并`kubectl rollout restart`即可，全量resync会幂等覆盖既有资源。
	797	+- 故障排查：
	798	+ 1. `kubectl get superpod`检查数量与成员，`nodeCount`应与该SuperPod内实际节点数一致。
	799	+ 2. 查matrixcontroller日志：`kubectl logs -n kube-system -l app=matrixcontroller`。
	800	+ 3. 查matrixagent日志确认采集正常：`kubectl logs -n kube-system -l app=matrixagent`。
	801	+ 4. 检查UBS Engine SDK socket：节点上`/run/ubse`是否存在。
	802	+ 5. 指标缺失排查：`kubectl logs -n kube-system -l app.kubernetes.io/name=superpod-exporter`查exporter日志；`superpod_name`为`unknown`时检查节点标签`unifiedbus.com/superpod`与RBAC权限。
	803	+
	804	+### 相关操作
	805	+
	806	+- 查看SuperPod：
	807	+
	808	+ ```bash
	809	+ kubectl get superpods.resource.matrix.huawei.com
	810	+ kubectl get superpod <superpod-name> -o yaml
	811	+ kubectl get superpod <superpod-name> \
	812	+ -o jsonpath='{.metadata.annotations.superpod\.matrix\.huawei\.com/node-hash}'
	813	+ ```
	814	+
	815	+- 查看HyperNode（仅`HYPERNODE_ENABLED=true`时存在）：
	816	+
	817	+ ```bash
	818	+ kubectl get hypernodes.topology.volcano.sh
	819	+ kubectl get hypernode <hn-name> -o yaml
	820	+ ```
	821	+
	822	+- 删除SuperPod / HyperNode：
	823	+
	824	+ > ![image](./figures/icon-notice.gif) 注意：
	825	+ >
	826	+ > 控制器会自动维护`SuperPod`/`HyperNode` CR的生命周期，正常情况下无需手工删除。仅在停用特性、清理残留资源或排查异常时手工删除。建议优先按名称删除特定资源，仅在下线或重置场景使用批量删除。
	827	+
	828	+ ```bash
	829	+ kubectl delete superpod <superpod-name>
	830	+ kubectl delete hypernode <hn-name>
	831	+ # 批量清理全部资源（仅下线/重置场景使用）
	832	+ kubectl delete superpods.resource.matrix.huawei.com --all
	833	+ kubectl delete hypernodes.topology.volcano.sh --all
	834	+ ```
	835	+
	836	+- 查看superpod-exporter指标：
	837	+
	838	+ ```bash
	839	+ kubectl get pods -n kube-system -l app.kubernetes.io/name=superpod-exporter -o wide
	840	+ curl -s <node-ip>:9102/metrics \| grep ubs_
	841	+ curl -s <node-ip>:9102/healthz
	842	+ ```
	843	+
	844	+- 停用superpod-exporter：卸载`superpod-exporter` DaemonSet即停用指标采集，无残留K8s资源，不影响既有matrixagent、matrixcontroller与`SuperPod`/`HyperNode`资源。
	845	+
	846	+ ```bash
	847	+ helm uninstall superpod-exporter -n kube-system
	848	+ ```

实现原理

总体方案

拓扑采集

工作流程

指标采集机制 ← 仅保留"怎么工作"，不含指标定义表

配置说明

SuperPod CR字段说明 ← 表3 + 内存统计口径作为memory字段补充

指标定义 ← 表5 Label语义 + 表6 指标定义直接内联（不再引用回实现原理）

配置样例