从 tlinux qcow2 构建 GB200/GB300 统一 GCE 镜像(v17 基线)

一句话结论:在一台 ARM64 builder VM 上,把客户 tlinux(TencentOS Server 4.x)qcow2 qemu-img 转 raw → loop 挂载探测 → 分区并 rsync 到目标盘 → chroot 修复引导/装驱动/配网络 → gcloud compute images create --source-disk 封装,即得一份同时兼容 GB200(VM/GVNIC)与 GB300(裸金属/IDPF)的统一镜像。本文基线 = v17(生产已验证可用)。

可复现脚本:deploy/scripts/build-gb-image-v17.sh(端到端固化;本文 §3 逐步解释)。 权威参考:deploy/tlinux_image_guide-v2.html(项目规定"制作镜像以此 HTML 为准"; 本文在其基础上对齐 v17 实况,差异见 §5)。


0. 适用范围与方法论


1. 前置:builder VM + 目标盘 + qcow2

在本地工作站执行(公司 poc 项目须用 cgcloud 包装,见根 CLAUDE.md)。

# 1) 目标根盘(50GB)+ builder VM(Rocky9 ARM64,与 EL9 生态同源,便于取 boost/libicu 依赖)
cgcloud compute disks create tlinux-v9-target --size=50GB --type=pd-ssd \
  --zone=us-central1-a --project=tencent-gcp-taiji-poc

cgcloud compute instances create tlinux-img-builder-v9 \
  --project=tencent-gcp-taiji-poc --zone=us-central1-a --machine-type=t2a-standard-8 \
  --image-family=rocky-linux-9-optimized-gcp-arm64 --image-project=rocky-linux-cloud \
  --boot-disk-size=100GB --boot-disk-type=pd-ssd --scopes=cloud-platform \
  --disk=name=tlinux-v9-target,device-name=target,mode=rw,boot=no

# 2) SSH 进 builder,装工具 + 取 qcow2 到 /work
cgcloud compute ssh tlinux-img-builder-v9 --zone=us-central1-a --project=tencent-gcp-taiji-poc
sudo dnf install -y -q qemu-img gdisk dosfstools xfsprogs rsync git wget tar curl
sudo mkdir -p /work && sudo gcloud storage cp \
  gs://hzchen-diagnostics-bucket/images/TencentOS-Server-4.6-6.6.119-49.101.nvidia-20260604-Tencent-aarch64.qcow2 \
  /work/

2. 关键设计决策与坑总表

决策 / 坑 做法 为什么 脚本位置
保留原 UUIDmkfs.xfs -m uuid=<原>、mkfs.vfat -i <原> 强制保留原 grub.cfg 用 search --fs-uuid、fstab 用 UUID;保留即可零改 grub/fstab[1]
XFS 重复 UUID构建期 mount -o nouuid目标盘与已挂的原盘同 UUID,XFS 默认拒挂;真机只有一个,不受影响[2]
UEFI removable fallbackcp grubaa64.efi → /EFI/BOOT/BOOTAA64.EFIGB300 裸金属 NVRAM 丢失时回退 removable 路径引导[2]
去 module.sig_enforce=1三处 cmdline 同步 sed否则自编译无签名 nvidia/idpf 模块加载失败(module verification failed)[4]
不写 hugepagescmdline 不加任何 hugepages=64K 页平台启动预留大页会吃掉大量可用内存[4]
net.ifnames=0原 qcow2 自带,保留不改控制网卡因此是 eth0/eth1(非 enp*),网络 profile 按此名 pin[4]/[6]
guest-agent 依赖不能软链注入原版 boost-regex 1.75/libicu 67/jq/oniguruma(rpm -ivh --force --nodeps / rpm2cpio)软链接 ABI 不兼容 → google_oslogin_nss_cache exit 127 → 阻断 IAP 登录[7]
chroot 内 uname -r 是宿主机内核所有编译显式传 $KVER / BUILD_KERNEL=$KVER否则驱动编到错误内核目录[9][10][12]
网络确定性(致命关)按名 pin gcp-eth0/eth1(单连+autoconnect+v4/v6 DHCP)+ gpu*rdma* unmanaged早期通用 match-device 单 profile 只连 eth1、eth0 掉线[6]
IMEX 默认不崩不自启NVreg_CreateImexChannel0=1 + nodes_config=127.0.0.1 + ConditionPathExists=/proc/driver/nvidia + systemctl disable空 nodes_config 会 crash-loop;条件化避免非 GPU 机 failed;默认关按客户要求[11]
禁 cloud-init / firewalldmask/disable腾讯云 metadata 169.254.0.23 干扰;firewalld 挡 RDMA[12]
memlock unlimitedlimits.d/rdma.confRDMA 必须[12]
清 netdiag.servicedisable+mask+rm(兜底)v17 遗留的排障调试服务,交付镜像不需要[12]
卸载顺序先子后父 umount(efivars→sys→proc→dev→boot/efi→根)避免 busy[13]

3. 分步流程(对应 build-gb-image-v17.sh)

以下每步与脚本 [N] 段一一对应,只列要点与关键命令;完整可执行版见脚本。

gcloud compute images create tlinux-gb-unified-ipv6-dual-50gb-v17 \
  --project=tencent-gcp-taiji-poc --source-disk=tlinux-v9-target --source-disk-zone=us-central1-a --force \
  --guest-os-features="UEFI_COMPATIBLE,GVNIC,IDPF" --architecture=ARM64 \
  --storage-location=us --family=tlinux-gb-unified

从未挂载的目标数据盘直接建(不经快照)。脚本默认只打印此命令,DO_IMAGE_CREATE=1 才执行; 从本地工作站发则把 gcloud 换成 cgcloud。再次构建请自增版本号。


4. 验收

可用测试资源:GB200 reservation 的最后 2 个 subblock 已预留给我们(优先在此测)。 需要 GB300 机器时告诉用户去找(裸金属消毒陷阱:建好保持 RUNNING,别乱关/删;避开坏块 0002/0006/0009)。

用该镜像分别开 GB200(a4x-highgpu-4g)与 GB300(a4x-maxgpu-4g-metal)各 1 台(create 参数见 deploy/gb200-a4x-deployment-guide.md / gb300-a4x-max-deployment-guide.md,startup 用统一版 scripts/tlinux4-customer-init-universal.sh),逐项核对:

  1. 启动:GB300 裸金属经 UEFI removable fallback → kernel 6.6.119-...nvidia.tl4 起来(串口 log)。
  2. 登录:外网 22 与 56000 都通;sshd 双栈(0.0.0.0+[::] 各 22/56000)。
  3. GPU/驱动:nvidia-smi -L(4× GPU,driver 580.159.04);modinfo idpf(GB300)/在位 mlx5。
  4. 网络:ip -brief addr → eth0/eth1(GB300 是 idpf)拿到 DHCP v4(+v6);rdma link show 8×(GB300)/4×(GB200)。
  5. 服务:google-guest-agent active;nvidia-imex is-enabled=disabled、手动 start→active 不崩; getenforce=Disabled;firewalld inactive;无 netdiag.service。

(详细期望值见 scratch state.md 的 GB200/GB300 验收结果;HTML §13 也有一份 A4X 实测清单。)

4.1 实测记录(2026-07-29,GB300 裸金属,已验证 ✅)

用本脚本端到端重建镜像 tlinux-gb-unified-ipv6-dual-50gb-v18test(内容 = v17,仅换测试名保护生产 v17),在 tencent-gcp-taiji-poc 用 a4x-maxgpu-4g-metal + reservation nvidia-gb300-dxkhoz4ypk4mh subblock-0017(空域)+ 现成 gb300-subblock-0017-policy 开 1 台(create 脚本 scripts/create-gb300-v18test-boot.sh),逐项 PASS:

GB200 侧未做真机 boot:该 reservation 当时几乎占满(288 用 280,8 个零散单槽,无完整空 subblock), 1x72 collocation policy 无法落位;GB300 有空 subblock 故改用 GB300 验证。GB200 与 GB300 共用同一份 镜像,GB300 裸金属路径(UEFI fallback + IDPF + 8×mlx5)比 GB200 更严苛,已足以证明镜像正确。


5. 本 v17 与官方 HTML 指南(v5.3)的差异对照

项 官方 HTML(v5.3 输出镜像) 本 v17 说明
gve编 OOT 1.4.10(podman+Fedora+coccinelle)in-tree(未换)HTML 告警针对更旧客户内核;GB300 不用 gve,GB200 tl4 in-tree 实测可用
控制网卡命名net.ifnames=1 → enp0s3(GB200 参考镜像)net.ifnames=0 → eth0/eth1源 qcow2 自带 ifnames=0,与 GB300 参考镜像一致
NM profilepin enp0s3-gvnicpin gcp-eth0+gcp-eth1 + gpu*rdma* unmanaged按实际网卡名
gdrdrv装(GDRCopy v2.6)不装v17 未含;如需见 §7
Lustre clientHTML 有 DKMS 章节镜像内不烤,交给 startup/运行时按交付形态
封装snapshot → images create直接 --source-disk少一步中转

结论:以 v17(生产验证)为交付基线;HTML 是权威工艺参考,上表差异是我们针对本源镜像/机型有意的取舍。


6. 镜像内做什么 vs startup script 运行时做什么

阶段 镜像内(本文 build) 运行时(tlinux4-customer-init-universal.sh,已定稿,勿改)
驱动nvidia/idpf 编译、in-tree gve/mlx5、IMEX 装好默认关—
引导/内核cmdline、UEFI fallback、initramfs—
网络按名 pin eth0/eth1、RDMA unmanaged网卡改名 bond0..N(遍历自动探测)、RDMA IP、host route(可开关)
存储—系统盘分区(p3=/usr/local、p4=/data)、本地 SSD RAID0→/mnt/stateful_partition
ssh双栈 22/56000—

分工原则:镜像 = 确定性的驱动/引导/最小网络可达;startup script = 机型自适应的改名/存储/RDMA。


7. 已知空缺 / 可选增强(非 v17 现状)


附:相关文件