PODsys 2404 用户手册

简介

PODsys 是一个基于 Ubuntu Server 24.04.4 LTS 的 GPU 集群部署软件栈，实现快速大规模集群部署。 podsys-2404 支持 x86_64 加 NVIDIA 数据中心 GPU （低于 B200）。

Hugging Face下载链接

关键组件及其版本

Component	Version	Command
OS	Ubuntu 24.04.4 LTS	lsb_release -ds
Linux kernel	6.8.0-100-generic	uname -r
NVIDIA GPU Driver	570.211.01	nvidia-smi
NVIDIA Fabric Manager	570.211.01	nv-fabricmanager -v
CUDA Toolkit	12.8	nvcc --version
NCCL	2.26.2	ncclras --version
cuDNN	9.10.2
DCGM	4.5.2	dcgmi -v
Docker Engine	29.5.3	docker version
NVIDIA Container Toolkit	1.19.0	nvidia-container-toolkit -version
InfiniBand Driver	MLNX_OFED_LINUX-24.10-3.2.5.0	ofed_info -s
ipmitool	1.8.19	ipmitool -V
PDSH	2.34	pdsh -V

1. 管理节点要求

提示

集群中选一个节点作为管理节点，其余为计算节点，所有 PODsys 部署操作均在管理节点执行。

1.1 使用现有的管理节点

如果使用现有管理节点，请进行如下操作:

• 创建 nexus 用户。

sudo adduser nexus
sudo usermod -aG sudo nexus
sudo -su nexus

• 安装 Docker 环境。

参考命令

sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl start docker
sudo systemctl enable docker

sudo docker version
sudo groupadd docker
sudo usermod -aG docker nexus
newgrp docker

• 安装 pdsh

1.2 使用全新安装的管理节点

• 通过 BMC 或 USB 手动为管理节点安装 Ubuntu Server，设置:

version : 24.04.4
hostname : mu01
username : nexus

警告

• 用户名和 ubuntu 版本必须与建议保持一致。
• 在安装过程中不要连接外网，以避免自动更新内核。可以 disable 连接外网的网卡。

BMC 安装

1. 登录 BMC，具体方式参考服务器厂商手册。
2. 点击 [Remote Control] -> [Launch KVM]。
3. 将 ubuntu-24.04.4-live-server-amd64.iso 映像挂载为虚拟介质。
4. 重启系统并从虚拟介质启动。

USB 安装

1. 创建包含ubuntu-24.04.4-live-server-amd64.iso的可引导安装介质（如USB Flash），参考 https://rufus.ie/zh/
2. 重启系统并从 USB 启动。

1.3 下载 podsys 软件包

• 下载所需软件

# 验证MD5值
echo "02778a250816b970f6695967c63c9bd9 podsys-2404.tgz" | md5sum  --check
sudo tar -xzvf podsys-2404.tgz -C /home/nexus/

• 下载 iso & cuda

# 下载 iso 到 podsys-2404/workspace/
cd podsys-2404/workspace/
wget https://releases.ubuntu.com/noble/ubuntu-24.04.4-live-server-amd64.iso

# 下载 cuda 到 podsys-2404/workspace/drivers/
cd podsys-2404/workspace/drivers
wget https://developer.download.nvidia.com/compute/cuda/12.8.1/local_installers/cuda_12.8.1_570.124.06_linux.run

• 运行install_manager.sh （如果使用全新安装的管理节点）

cd podsys-2404/
sudo ./install_manager.sh

• 重启后健康检查

sudo ./scripts/health-checks.sh

2. 计算节点安装步骤

计算节点的安装步骤需要在管理节点上执行。
下载 ubuntu-24.04.4-live-server-amd64.iso 到 podsys-2404/workspace/ 文件夹.

2.1 修改 iplist.txt

sudo vim workspace/iplist.txt

iplist.txt的一个示例如下:

Serial Number	hostname	IP address	gateway	DNS	Docker IP
24X01	node01	192.168.0.1/24	192.168.0.1	8.8.8.8	172.17.0.1/16
24X02	node02	192.168.0.2/24	none	none	172.17.0.1/16
24X03	node03	192.168.0.3/24	none	none	none

技巧

首先可以在excel表格中按照相同格式编写好，然后直接复制到 vim 打开的空白 iplist.txt 中使用。

cat -A iplist.txt

查看格式，正确输出：

24X01^Inode01^I192.168.0.1/24^Inone^Inone^I192.168.1.1/24^Inone$  
24X02^Inode02^I192.168.0.2/24^Inone^Inone^I192.168.1.2/24^Inone$

这里，^I代表一个制表符，用于分隔每一行中的不同字段，而$则表示一行的结束。

警告

IP不要忘记子网掩码。

提示

• PODsys 部署需要在管理节点开启 DHCP 服务，请确保部署网络中没有其它 DHCP 源。
• 如果网络中已经存在 DHCP 服务，且无法隔离或关闭，请在/workspace/下 创建 mac_ip.txt 文件。
• 每一行前面是待部署计算节点的网卡 MAC 地址，部署服务器仅对这些 MAC 的 DHCP 请求响应，分配的 IP 为后面的 IP 地址。
• MAC 地址和 IP 用英文逗号区分。
• 如果不存在管理节点不便开启 DHCP 的情况不要创建此文件。

文件样式如下

24:01:00:00:00:01,192.168.0.1
24:01:00:00:00:02,192.168.0.2

2.2 修改 config.yaml

cd podsys-2404
sudo vim workspace/config.yaml

config.yaml 中需要修改的内容：

manager_ip: 192.168.0.1
manager_nic: ens6f0
dhcp_s: 192.168.0.1
dhcp_e: 192.168.0.200
compute_passwd: your_passwd
compute_storage: sda

• manager_ip: 管理节点的IP 地址。
• manager_nic: 管理节点的网卡名称。
• dhcp_s & dhcp_e: 计算节点安装过程中临时分配IP的范围。

警告

dhcp_s 和 dhcp_e 之间包含的IP地址数量必须大于计算节点的数量，否则会造成部分安装节点安装失败。

例子

• 管理节点的 IP：192.168.0.201/16。
• 计算节点（200台）在 iplist.txt 中设置为 192.168.0.1/24-192.168.0.200/24。
• 可以将 dhcp_s 设置为 192.168.1.1，dhcp_e 设置为 192.168.3.254。
• 这样dhcp的范围和计算节点在 iplist.txt 中分配的静态 IP 不冲突，同时保证了范围内IP和管理节点的连通性，范围内也有足够的IP地址。
• 安装结束后可以将 192.168.0.201/16 修改为 192.168.0.201/24

• compute_passwd: 计算节点的用户密码。

• compute_storage: 计算节点的系统存储设备名称（sda、nvme0n1等），
  也可以用 MIN_SATA MAX_SATA MIN_NVMEor MAX_NVME 。

• compute_storage(Beta)：目前仅支持使用恰好两块磁盘的 RAID1 配置。若要启用 RAID1，请在您的 config.yaml 文件中使用以下 YAML 块格式：

...
compute_passwd: your_passwd
compute_storage:
  type: raid1
  devices: [sda, sdb]

要求： devices 中必须恰好列出两块磁盘； 这两块磁盘必须已连接、未挂载，且容量足够； 支持的磁盘名称包括：sda、sdb、nvme0n1 等。

警告

系统安装将会覆盖整个硬盘的数据！

2.3 运行 install_compute.sh

警告

运行以下脚本后，会根据之前填写的配置信息，开启一些服务。
如果对于 config.yaml 和 iplist.txt 有所修改，需要退出脚本，重新执行。
运行之前可以参考6. 个性化配置，进行个性化配置。

sudo ./install_compute.sh

你会访问到在运行中的Docker容器内部的交互式命令行界面：

界面如下

**
 Welcome to the cluster deployment software
Configuring, please wait...
  ____     ___    ____    ____   __   __  ____
 |  _ \   / _ \  |  _ \  / ___|  \ \ / / / ___|
 | |_) | | | | | | | | | \___ \   \ V /  \___ \
 |  __/  | |_| | | |_| |  ___) |   | |    ___) |
 |_|      \___/  |____/  |____/    |_|   |____/

dhcp-config : /etc/dnsmasq.conf
user-data   : /user-data/user-data

starting services:
 * Starting DNS forwarder and DHCP server dnsmasq   [ OK ]
 * Starting nginx nginx                             [ OK ]

Running Monitor on following URLs:
 * http://192.168.0.201:5000

root@podsys:/ $

前置准备完成，待安装计算节点开机。

提示

• 裸金属节点开机自动进入 PXE(Preboot Execution Environment) 模式，等待自动安装。
• 如果计算节点已经存在操作系统，它们需要手动进入PXE 模式。
• 如果计算节点无法进入 PXE 安装，检查管理节点的防火墙是否关闭。

2.4 监控安装进度

你可以在浏览器输入 http://manager_ip:5000 查看监控界面。

界面如图

DANGER

• 对于每个项目出现 ✓表示检测正常，✗表示硬件不在位。
• 当日志出现具体日志名字的时候可以点击查看日志。
• 当disk栏出现 ！表示config.yaml中的磁盘在节点不存在。

计算节点安装完成后会自动重启。
在docker容器交互式命令行输入 exit 退出安装。

2.5 运行 install_progress.sh

待所有计算节点重启完成后，运行：

sudo ./install_progress.sh

执行过程中可能存在部分节点SSH失败，可能原因是重启后服务尚未加载。因此需要等待足够时间。 这条命令可以执行多次，直到所有的计算节点被成功SSH进入后，执行：

sudo ./config_server.sh -pre

脚本功能

• 在 podsys-2404 文件夹下，生成 host.txt 文件。该文件记录了所有可以 SSH 成功的节点的 IP 地址。对于后续并行环境配置比较重要。
• 实现在所有节点上的 nexus 用户之间实现免密的 SSH 登录。

2.6 安装结果检测

运行以下命令检测安装结果：

命令

sudo ./config_client.sh -health-check

输出

172.16.0.1: PODsys deployment successful
172.16.0.2: PODsys deployment successful
172.16.0.3: PODsys deployment successful
...