从 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. 适用范围与方法论
- 产物:GCE 自定义镜像,ARM64,
--guest-os-features=UEFI_COMPATIBLE,GVNIC,IDPF, familytlinux-gb-unified。一份镜像 VM/裸金属通吃(GB200 用 GVNIC、GB300 用 IDPF,靠 guest-os-features 与 GPU 条件化服务共存)。 - 为什么不用
gcloud compute images import/ daisy:客户 qcow2 通常单分区、无 UEFI ESP、缺 GRUB/cloud 配置,images create --source-uri(tar.gz 内含 disk.raw)那条路无法满足;故用"builder 挂盘 + 分区 + rsync + chroot 修复"完全掌控分区布局、引导链、驱动版本。(依据:HTML「概述与架构」info 段) - v17 基线的关键事实(经全量构建 transcript + 脚本正文核实):
- gve = 内核 in-tree(未编译/替换 OOT 1.4.10)。GB300 管理网卡走 idpf、不用 gve;GB200 的 tl4 内核 in-tree gve 生产实测可用。
- ⚠️ 旧
build-image-v9.sh头部注释、及旧 scratch 笔记曾称"换 OOT 1.4.10 / 拷 v8 .ko",系当时推测, 实际从未执行,已在本文与脚本更正。〔"in-tree 够用"是事实(生产验证);它与 HTML「gve 过旧致命」告警 的调和(告警针对更旧客户内核、且 GB300 不用 gve)属合理推断,非逐字实测。〕
- ⚠️ 旧
- 无 gdrdrv(v17 不含 GPUDirect RDMA 内核模块;如需见 §7)。
- 源镜像:
TencentOS-Server-4.6-6.6.119-49.101.nvidia-20260604-Tencent-aarch64.qcow2, 内核6.6.119-49.101.nvidia.tl4.aarch64,原 grub 自带net.ifnames=0(→ 控制网卡 eth0/eth1)。
- gve = 内核 in-tree(未编译/替换 OOT 1.4.10)。GB300 管理网卡走 idpf、不用 gve;GB200 的 tl4 内核 in-tree gve 生产实测可用。
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/
- 目标盘在 builder 内是
/dev/nvme0n2(device-name=target);boot 盘/dev/nvme0n1。用lsblk确认。 - builder 无需 GPU(只做转换/编译/chroot)。
--scopes=cloud-platform让 builder 上可直接gcloud在 poc 内建镜像(§3 步骤 [14])。
2. 关键设计决策与坑总表
| 决策 / 坑 | 做法 | 为什么 | 脚本位置 |
|---|---|---|---|
| 保留原 UUID | mkfs.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 fallback | cp grubaa64.efi → /EFI/BOOT/BOOTAA64.EFI | GB300 裸金属 NVRAM 丢失时回退 removable 路径引导 | [2] |
去 module.sig_enforce=1 | 三处 cmdline 同步 sed | 否则自编译无签名 nvidia/idpf 模块加载失败(module verification failed) | [4] |
| 不写 hugepages | cmdline 不加任何 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 / firewalld | mask/disable | 腾讯云 metadata 169.254.0.23 干扰;firewalld 挡 RDMA | [12] |
| memlock unlimited | limits.d/rdma.conf | RDMA 必须 | [12] |
| 清 netdiag.service | disable+mask+rm(兜底) | v17 遗留的排障调试服务,交付镜像不需要 | [12] |
| 卸载顺序 | 先子后父 umount(efivars→sys→proc→dev→boot/efi→根) | 避免 busy | [13] |
3. 分步流程(对应 build-gb-image-v17.sh)
以下每步与脚本
[N]段一一对应,只列要点与关键命令;完整可执行版见脚本。
- [0] 准备:
qemu-img convert -f qcow2 -O raw→losetup -fP→ 挂p2(rootfs)/p1(ESP);KVER=$(ls $QROOT/lib/modules)探测内核版本(后续编译全用它)。buildersetenforce 0(rsync xattr)。 - [1] 目标盘分区:
sgdisk --zap-all→ GPT,p1 ESP(1–513MiB,fat32,esp on)、p2 root(xfs);mkfs.vfat -i $EFI_UUID/mkfs.xfs -m uuid=$ROOT_UUID保留原 UUID。 - [2] 灌系统:
mount -o nouuid目标 p2、ESP 挂boot/efi;rsync -aHAx --numeric-ids(不带-X);cp -r $QESP/EFI;cp grubaa64.efi → /EFI/BOOT/BOOTAA64.EFI(裸金属兜底)。 - [3] chroot 前置:bind
dev/dev-pts/proc/sys+efivars;拷resolv.conf;禁 TencentOS*.repo(→.disabled)。 - [4] cmdline:三处(
grub.cfg/etc/default/grub/loader/entries/*.conf)sed去module.sig_enforce=1、 加rd.driver.blacklist=nouveau modprobe.blacklist=nouveau nvme_core.io_timeout=255;不加 hugepages; net.ifnames=0 保留。⚠️ glob 须在 root 上下文(目录 700)。 - [5] sshd 双栈:
sshd_config.d/00-gb-dualstack.conf→Port 22+Port 56000+AddressFamily any。 - [6] 网络(v17 定案):写
system-connections/gcp-eth0.nmconnection+gcp-eth1.nmconnection(interface-name=eth0/eth1、autoconnect、v4+v6method=auto);写conf.d/99-unmanaged-devices.conf→unmanaged-devices=interface-name:gpu*rdma*;清理旧通用 profile。 - [7] guest-agent 依赖注入:
dnf downloadboost-regex/libicu(rpm2cpio取.so.67*)/jq/oniguruma → 注入 chroot。 - [8] guest-agent:写
google-cloud.repo→dnf install google-compute-engine google-guest-agent google-osconfig-agent→systemctl enable NetworkManager sshd google-guest-agent google-startup-scripts google-shutdown-scripts google-osconfig-agent。 - [9] NVIDIA 580.159.04 open:
nvidia.run --silent --kernel-module-type=open --kernel-name=$KVER(Blackwell 必须 open 类型)。 - [10] IDPF v1.0.11:Intel tar → chroot 内根目录 make(
TARGETS := idpf auxiliary)make -j BUILD_KERNEL=$KVER && make install ... && depmod -a $KVER(GB300 管理网卡)。 - [11] IMEX:装
nvidia-modprobe+nvidia-imexrpm;NVreg_CreateImexChannel0=1;nodes_config=127.0.0.1;ConditionPathExists=/proc/driver/nvidiadrop-in;systemctl disable(默认关)。 - [12] 收尾:
depmod -a $KVER→dracut --force --kver $KVER(纳入自编 nvidia/idpf;gve 未换无需换出); 禁 cloud-init(5 unit +network:{config:disabled});mask firewalld;limits.d/rdma.confmemlock unlimited; 清 netdiag.service;打印自检。 - [13] 卸载:删 resolv.conf、还原 repo 名、删 google-cloud.repo;先子后父 umount。
- [14] 封装镜像:
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),逐项核对:
- 启动:GB300 裸金属经 UEFI removable fallback → kernel
6.6.119-...nvidia.tl4起来(串口 log)。 - 登录:外网 22 与 56000 都通;sshd 双栈(
0.0.0.0+[::]各 22/56000)。 - GPU/驱动:
nvidia-smi -L(4× GPU,driver 580.159.04);modinfo idpf(GB300)/在位 mlx5。 - 网络:
ip -brief addr→ eth0/eth1(GB300 是 idpf)拿到 DHCP v4(+v6);rdma link show8×(GB300)/4×(GB200)。 - 服务:
google-guest-agentactive;nvidia-imexis-enabled=disabled、手动start→active 不崩;getenforce=Disabled;firewalldinactive;无 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:
- 启动:UEFI → GRUB 2.12 → kernel
6.6.119-49.101.nvidia.tl4.aarch64(串口确认;bli.mod not found是无害 grub cosmetic 警告)。 - 登录:外网 22 直连 SSH 通;guest-agent 注入 SSH key 成功(证明 boost-regex/libicu 依赖注入有效)。
- GPU/驱动:
nvidia-smi→ 4× NVIDIA GB300,driver 580.159.04(镜像内编译的 open 驱动加载 OK)。 - 网络:in-tree
mlx5_core+mlx5_ib加载;rdma dev8× RoCE(ibdev 改名 bond2..bond9);IDPF mgmt/lustre → bond0/bond1;gpu*rdma*netdev DOWN 待运行时setup_rdma_ips配 IP(符合镜像99-unmanaged-devices设计,非缺陷)。 - 磁盘:p1(ESP,
/boot/efi)/ p2(xfs/49.5G,保留 UUID)/ startup 加 p3(/usr/local20G)/ p4(/data930G);net.ifnames=0、无sig_enforce。 - 服务:
nvidia-imex=disabled;firewalld=masked;netdiag=not-found(已清);sshd 22+56000; startup 脚本google-startup-scriptsstatus=0/SUCCESS(Customer Initialization Complete)。
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 profile | pin enp0s3-gvnic | pin gcp-eth0+gcp-eth1 + gpu*rdma* unmanaged | 按实际网卡名 |
| gdrdrv | 装(GDRCopy v2.6) | 不装 | v17 未含;如需见 §7 |
| Lustre client | HTML 有 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 现状)
- gdrdrv(GPUDirect RDMA 内核模块):v17 不含。若生产确需,在 chroot 内
git clone --branch v2.6 gdrcopy→make CUDA=<path> KVER=$KVER→echo gdrdrv > /etc/modules-load.d/gdrdrv.conf+ 装gdrcopy.service(GPU 条件化),之后dracut --force。(工艺参考 HTML §8/§10) - gve OOT 1.4.10:仅当换用更旧客户内核、in-tree gve 与 GVNIC 握手失败(
AQ commands timed out)时才需要; 需 podman+Fedora 容器 + coccinelle 打补丁(HTML §6b)。当前 tl4 内核不需要。 - nvidia-persistenced:HTML v5.3 有增量构建加它(GPU 条件化);v17 未含,如需可仿 HTML §12b 增量加。
附:相关文件
- 构建脚本(本文):
deploy/scripts/build-gb-image-v17.sh - 旧版脚本(保留参考,头部 gve OOT 注释已知有误):
deploy/scripts/build-image-v9.sh、continue-v9.sh - 权威工艺指南:
deploy/tlinux_image_guide-v2.html - 统一 startup script(已定稿):
deploy/scripts/tlinux4-customer-init-universal.sh - 机型部署参数:
deploy/gb200-a4x-deployment-guide.md、deploy/gb300-a4x-max-deployment-guide.md - 验收现场记录:
deploy/.claude/scratch/state.md