UBS Kubernetes Enable

在 Kubernetes 生态中，插件化加入 UBS Server 组件，构筑双层调度架构能力，使能云管系统在高带宽、内存池化场景中的调度竞争力。

核心能力

内存无感借用

基于 UB 内存池化机制，当节点或 NUMA 的内存使用率达到预设值时，触发内存借用，将内存压力分担到借过来的内存上，实现容器进程的冷热数据流动。

适用场景：裸机容器场景，支持容器绑 NUMA 和容器不绑 NUMA 两种部署模式。

内存共享

UBS-Core 的内存池化组件，支持通过内存池化能力将内存块在 UBS Server 集群内导入导出，实现跨节点以及多进程共享使用内存。

适用场景：裸机容器场景，通过 CSI 插件机制管理容器共享内存的生命周期。

目录结构

.
├── build           # 编译和构建相关脚本
├── charts          # Helm charts，用于 Kubernetes 部署
├── cmd             # 主程序入口
├── doc             # 项目文档
│   ├── build_install/  # 构建指导和部署说明
│   ├── config/         # 配置说明
│   ├── design/         # 架构设计和安全设计
│   └── example/        # 参考实践
├── pkg             # 核心业务逻辑
├── shm_proxy       # 共享内存 C++ 代码
└── test            # 单元测试文件

前提条件

组件	版本要求
Kubernetes	v1.31.1 及以上版本
操作系统	OpenEuler 24.03 LTS 及以上版本
容器运行时	containerd

内存无感借用额外要求

• 需提前配置 /etc/default/grub 文件，新增 numa_remote=nofallback 启动参数（禁止应用直接申请远端内存）

部署说明

方式一：Helm 部署

# 部署 MatrixController（中心侧）
helm install matrixcontroller ./charts/matrixcontroller

# 部署 MatrixAgent（节点侧）
helm install matrixagent ./charts/matrixagent

# 部署 MatrixSHM（共享内存 CSI 组件）
helm install matrixshm ./charts/matrixshm

详细部署步骤请参考：部署说明

本地构建

环境要求

• Go 1.24.1+
• CMake 3.10+
• GCC 9.0+
• Kubernetes v1.31.1+ 源码（用于生成代码）

构建步骤

1. 构建 Go 部分

# 安装依赖
go mod download

# 构建 matrixcontroller
go build -o bin/matrixcontroller ./cmd/matrixcontroller

# 构建 matrixagent
go build -o bin/matrixagent ./cmd/matrixagent

# 构建 shm-csi-driver (CSI Node)
go build -o bin/shm-csi-driver ./cmd/matrixshm/csi-node

2. 构建 C++ 部分 (shm_proxy)

mkdir build && cd build
cmake .. && make -j$(nproc)

详细构建步骤请参考：构建指导

配置说明

内存无感借用配置

配置项	说明	配置范围
内存水线	触发内存借用的内存使用率阈值	92%
归还水线	触发内存归还的内存使用率阈值	80%
节点内存超分比例	节点标签，配置内存超分比例	整数 (0, 25]
Pod 远端内存比例	Pod 标签，设置容器进程本地/远端内存配比	整数 (0, 67]

节点标签配置：

apiVersion: v1
kind: Node
metadata:
  labels:
    # 配置节点内存超分比例为 25%
    remote-mem-allocation-ratio: "25"

Pod 标签配置：

apiVersion: v1
kind: Pod
metadata:
  labels:
    # 设置容器进程最大使用远端内存比例为 25%
    remote-mem-allocation-ratio: "25"

内存共享配置

配置项	说明
共享域标签	声明共享内存资源域
资源配额	共享内存使用限额

详细配置说明请参考：配置说明

快速开始

1. 部署 UBS Core 依赖组件

确保 UBS Engine、UBSM、RMRS 等组件已正确部署。

2. 部署 Kubernetes 插件

# 安装 Helm charts
helm install matrixcontroller ./charts/matrixcontroller
helm install matrixagent ./charts/matrixagent
helm install matrixshm ./charts/matrixshm

3. 验证部署

# 检查 Pod 运行状态
# 内存共享
kubectl get pod -A |grep shm-csi-driver
# 内存无感借用 
kubectl get pod -A |grep kube-matrix-agent
kubectl get pod -A |grep kube-matrix-controller

参考文档

设计文档

文档	说明
架构设计	软件架构、接口设计和业务流程
内存无感借用详细设计	内存借用功能规格、约束条件与业务流程
内存共享详细设计	内存共享功能规格、约束条件与业务流程
安全设计	安全设计说明

API 文档

文档	说明
API 接口文档	CLI 命令和 SDK 接口说明

构建与部署

文档	说明
构建指导	本地构建指南
部署说明	详细部署步骤

配置与使用

文档	说明
配置说明	配置项详解
参考实践	使用示例

测试

文档	说明
单元测试开发指南	单元测试开发指南

许可证

本项目采用木兰开源许可，详见 LICENSE 文件。