GB300 / GB200 运维速查手册
面向 A4X Max(GB300,裸金属)与 A4X(GB200,VM)集群日常运维。命令以客户自有项目权限直接 gcloud 执行;变量用 <...> 占位。每节末尾附对应官方文档,完整链接见附录 E。
0. 环境对照
| 项 | GB200(A4X) | GB300(A4X Max) |
|---|---|---|
| 机型 | a4x-highgpu-4g | a4x-maxgpu-4g-metal |
| 形态 | VM | 裸金属(bare metal) |
| GPU / 节点 | 4 | 4 |
| 网卡 | 2×GVNIC + 4×MRDMA | 2×IDPF + 8×MRDMA(RDMA 为 IPv6-only) |
| 消毒(sanitization) | 无 | stop/delete 触发该 host 约 1h 消毒 |
| 主机维护 | 停机后同实例原地重启(automaticRestart) | 停机后同实例原地重启(automaticRestart,Local SSD 数据保留) |
| 恢复设备状态 | reset / delete / 重建皆可 | 优先 reset(不消毒);stop/delete 触发消毒 |
| 镜像 | --image-family=tlinux-gb200(HEAD=v19dot1) | 显式 --image=tlinux-gb300-ipv6-dual-50gb-v22(v22 未设 family,--image-family 取不到) |
| 系统盘 | 1000GB hyperdisk-balanced | 200GB hyperdisk-balanced |
| 初始化脚本 | tlinux4-customer-init-universal.sh(v6.x,配 v19 镜像) | tlinux4-customer-init-universal-v7dot1.sh(v7.1,配 v22 镜像) |
1. 必须知道的信息
1.1 GB300 消毒(sanitization)
GB300 是裸金属。任一台 stop 或 delete 会使该物理 host 进入约 1 小时消毒(NVMe 深度擦除、固件刷新、断电重启、安全启动验证),期间该 host 被锁、不可分配给新建机请求。
| 结论 | 说明 |
|---|---|
| 时长 | 实测一次 delete,sub-block 健康计数完全回基线约 67 分钟 |
| 不锁整域 | 消毒只锁那一台 host;同 sub-block 仍有健康空槽即可照常建新机(约 3.5 分钟 RUNNING) |
| stop = delete | 裸金属唯一可行的是 stop --discard-local-ssd=true,host 照样释放并消毒,并不比 delete 安全 |
| 无优雅关机 | stop 保盘(--discard-local-ssd=false)本项目不支持,只能丢盘 |
| 标记滞后 | 命令返回后 degraded 计数不立刻变,实测 +24~31 分钟才标记;计数没动不等于没进消毒 |
| 判是否在消毒 | degradedHostCount 仅为辅助 / 滞后信号(聚合计数,不区分哪台、也不分消毒型或硬件型);权威判法是自行记账被 stop/delete 的实例与时间,按“约 1h 后回落基线”核对。官方无 per-host 消毒状态 API |
| 自动恢复 | 约 1h 后 degraded 计数自动回落基线,逐台错峰放回 |
恢复设备状态首选 reset(热重启、保盘),不触发消毒;只有 stop/delete 才触发。GB200 是 VM,无消毒问题,可正常 reset/delete/重建。
约 1h 消毒时长为我方实测经验值,GCP 未公开成文;官方侧证:本地 SSD 在实例 stop 后数据被丢弃、重建得到空白未格式化盘(When you stop ... Compute Engine discards the data of any Local SSD disks ... all Local SSD disks ... are blank),report faulty 停机页也明确“无法恢复 Local SSD 数据”,故裸金属停机=物理层重置。
参考:Local SSD:停机即丢数据(概念) · report faulty host(含 Local SSD 清空警告) · A4X Max 建机(termination-action 语义)
1.2 最新镜像与初始化脚本(镜像与 startup 强配对)
GB200 与 GB300 使用两套不同的镜像与 startup script,不能混用或交叉配对。GB300 因 RDMA(IPv6-only)与网卡改名需求存在较多历史问题,现已将网卡改名、hugepages、sshd、内核模块等固化进镜像、由镜像内的 systemd service 完成,startup script 相应精简为仅做校验的瘦脚本;GB200 仍沿用经验证的厚脚本(每台开机自行完成配置)。
| 机型 | 镜像 | 配套 startup script | 脚本形态 |
|---|---|---|---|
| GB200 | --image-family=tlinux-gb200(HEAD=v19dot1) | tlinux4-customer-init-universal.sh(v6.x) | 厚:分区 / sshd / 网卡改名 / lnet 全在脚本做 |
| GB300 | 显式 --image=tlinux-gb300-ipv6-dual-50gb-v22(推荐) | tlinux4-customer-init-universal-v7dot1.sh(v7.1) | 瘦:改名/hugepages/sshd 烤进镜像,脚本只校验 + 注入 Lustre 策略 |
| GB300(备选) | 显式 --image=tlinux-gb300-ipv6-dual-50gb-v21 | tlinux4-customer-init-universal-v7dot0.sh(v7.0) | v7.0 仍由脚本改名(约 130s);v21/v22 是并行选项,非新旧关系 |
配对为硬约束,配错后故障静默、外部难以察觉。GB300 的 v21 与 v22 为并行选项:v21 由 startup 改名(配 v7.0),v22 由镜像内 udev
76-规则改名(配 v7.1)。若 v21 配 v7.1(或旧镜像配 v7.x),镜像内缺76-改名规则、而 v7.1 已移除改名逻辑,网卡将停留在eth*/gpu*rdma*,无法匹配镜像内的10-bond1..9NM keyfile,导致 8 张 RDMA 全部 DOWN、Lustre 无法挂载;此时机器仍为 RUNNING、SSH 可通、nvidia-smi正常,仅rdma link show可观测到异常。
镜像取用两点(GB300):
- GB300 的 v21/v22 未挂 image family,
--image-family=tlinux-gb300无法取得,建机须指定--image=<完整镜像名>(镜像升级时,所有硬编码镜像名之处需同步修改)。 --boot-disk-size必须 ≥ 200GB(镜像名里的50gb是镜像自身大小,50GB 盘拿不到独立/usr/local、/data分区)。- 旧
tlinux-gb-unifiedfamily 已弃用,勿再用它取 HEAD(会误取到混机型镜像)。
startup script 做的事(均不含 k8s):
- GB200 v6.x(厚):① 系统盘分区(p3=+20G→
/usr/local,p4=剩余→/data,xfs nofail);② sshd 加 Port 22+56000;③ 遍历/sys/class/net与rdma dev自动探测、网卡改名bond*(mgmt 改名带自愈看门狗,元数据不可达自动 revert);④ lnet 绑 bond1(PSA 路由 / 挂载交推送脚本或 metadata)。 - GB300 v7.1(瘦):分区同上;网卡改名 / hugepages(CPU NUMA 各 4096=8192,GPU NUMA 置 0)/ sshd 56000 / Calico 模块均由镜像内 service 完成,脚本仅做校验;并从 metadata(
lustre-mgs-nid/lustre-mountpoint/lustre-peering-cidr)读取 Lustre 策略、首启自动挂载(缺 MGS 或挂载点时整段跳过,非故障)。
交付前必须重启复验(建议 3 轮)。网卡改名 / hugepages / ACS / RDMA 均为每 boot 重放,单次成功不代表持久;持久化的唯一判据是重启后仍正常。建机后 2~4 分钟的最小确认与一键体检见 §3 Pre-flight 检查。
完整脚本见附录:G.1 GB200 v6.0 · G.2 GB300 v7.1 · G.3 GB300 v7.0(备选)(本地权威副本:GB200 deploy/scripts/tlinux4-customer-init-universal.sh;GB300 deploy/tlinux4-customer-init-universal-v7dot1.sh / ...-v7dot0.sh)。
1.3 Scheduled maintenance
GB300/GB200 GPU 主机不支持热迁移,维护即停机(--on-host-maintenance=TERMINATE)。A4X / A4X Max 官方提前量(以 AI Hypercomputer 专页为准):
| 类型 | 官方提前量 | 说明 |
|---|---|---|
| 计划维护(scheduled) | 约 90 天预告 | upcoming-maintenance 提前查到窗口(window_start_time),can_reschedule 指可否手动提前 |
| 紧急维护(emergency,非计划) | 约 7 天(本项目预留已启用紧急维护通知,enableEmergentMaintenance=true,无需手动开启) | 尽快排空 |
| 临停终态信号 | 真正停机前约 1 小时 | metadata maintenance-event 变为 TERMINATE_ON_HOST_MAINTENANCE,为最后窗口,应主动处置 |
如何接收通知(事件驱动,别用常驻轮询)
计划维护会作为 system event 写进 Cloud Audit Logs,官方推荐用 log-based alerting policy 订阅日志直接推通知,而不是常驻轮询 metadata:
- 首选:建日志告警(零轮询)。对下列日志建 log-based alerting policy 并绑定通知渠道(邮件 / Pub/Sub / Slack)。A4X / A4X Max 专页按阶段给的 filter 原文:
# 已排期(scheduled)
protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "scheduled"
# 维护开始
protoPayload.methodName="compute.instance.terminateOnHostMaintenance" severity>=DEFAULT
# 已完成
protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "completed"
- Logs Explorer 手查(通用写法):
operation.producer="compute.instances.upcomingMaintenance" OR "compute.instances.terminateOnHostMaintenance" OR "compute.instances.migrateOnHostMaintenance";按机型过滤加protoPayload.metadata.machineType:"a4x-highgpu-4g"。upcoming-maintenance字段(以 AI Hypercomputer host-events 页为准):type=SCHEDULED、maintenance_status(PENDING/ONGOING)、window_start_time/window_end_time、maintenance_reasons(如PLANNED_UPDATE)。 - 要程序化自动化(自动开 case / 自动触发 checkpoint):建 log sink 把上面日志导到 Pub/Sub,再由 Cloud Run function 消费触发(通用 Logging 能力,filter 同上)。
- 即时查单台窗口:
gcloud compute instances describe <VM> --zone=<ZONE> --format='yaml(resourceStatus.upcomingMaintenance)',字段含canReschedule/maintenanceStatus/windowStartTime/latestWindowStartTime。 - 紧急 / 约 1h 终态信号(计划外,来不及进告警链):实例内用 hanging GET 阻塞监听(值变才返回,非忙轮询):
curl -H 'Metadata-Flavor: Google' \
"http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event?wait_for_change=true&last_etag=<ETAG>&timeout_sec=360"
变为 TERMINATE_ON_HOST_MAINTENANCE 即进入 §4.3 的自动 cordon/drain;upcoming-maintenance?alt=json 同理可 hanging GET 拿更早窗口。
收到通知后的处置(按业务排期人工处理,不自动执行维护)
现实做法是收到通知后由人结合业务情况自行安排,而非让系统自动触发维护:
- 日志告警报
maintenanceStatus=PENDING(通常提前数天,计划维护可达 90 天),据此结合业务排期,自行决定在哪个维护窗口内处理。 - 处理前:训练侧在最近 checkpoint 边界优雅落盘(异步 checkpoint 优先;进程 / 容器 catch
SIGTERM触发存档);把 Local SSD 临时数据迁到 GCS / 持久盘。 - 摘节点并主动触发维护(推荐主流程):
kubectl cordon <NODE>+kubectl drain <NODE> --ignore-daemonsets --delete-emptydir-data,再在业务空闲窗口gcloud compute instances perform-maintenance <VM> --zone=<ZONE>立即开始维护,不必被动等windowStartTime自然到点。perform-maintenance语义是立即开始、不是推后;canReschedule=true指“可手动提前”而非“可延后”,官方无把维护推迟到窗口之外的机制。 - 维护完成后加回集群:GB200(VM)与 GB300(裸金属)均为同实例原地恢复——本项目每台
automaticRestart=true,主机维护为TERMINATE+ Local SSD 数据保留,维护结束后同实例自动重启回来(GB300 可能落到不同物理 host)、boot 持久盘与 Local SSD 数据均在,直接kubectl uncordon <NODE>重新纳入调度,无需重新初始化或重建。只有用户主动stop/delete或确诊硬件故障 report-faulty 送修才触发消毒 / 重建(§1.1 / §2.3 / §4.1),与“主机维护”是两回事。
紧急维护提前量较短(本项目已开启通知,约 7 天;临停终态信号约 1 小时)、可能无人值守,可用 §4.3 的自建 k8s DIY 完整闭环(轮询 metadata → 训练侧 SIGTERM 存 checkpoint → cordon/drain 节点 → 维护后 JobSet/Kueue 自动从最近 checkpoint 续训),复刻 GKE maintenance-handler 范式;仅自动摘节点与续训,不自动执行维护本身。
参考:A4X 维护事件 + 建日志告警(概念/操作,filter 原文) · 查看维护日志 + 建告警(UI+CLI) · 维护状态字段语义(canReschedule 等) · log-based 告警(概念) · 日志路由到 Pub/Sub(概念) · 主动提前触发维护(操作,start early) · perform-maintenance CLI · GPU 1h 提前量 + maintenance-event(概念) · wait_for_change hanging GET(概念)
1.4 VM 内设备与 Lustre 故障识别
本节说明如何识别故障(设备与 Lustre 存储 / 存储网络)。识别后一律走 §2.2 统一升级路径处理(先软后硬:可 reset 恢复的先 reset,确诊不可恢复的硬件故障才报障),不在本步直接决定下线或报障。仅看状态位会漏判,须结合下列决定性信号。
本节仅说明识别信号;可直接使用的检测脚本见 §3 Pre-flight 检查,
lustre-preflight.sh已覆盖下列全部信号,无需自行编写。
设备类:
| 部件 | 决定性信号(判故障) |
|---|---|
| NIC 假活 | link 仍 ACTIVE/400Gb/s,但 dmesg 出现 mlx5_core ... device's health compromised - reached miss count(固件心跳丢失)。仅统计运行时事件,开机 300s 内为良性自检须排除 |
| RDMA 链路 | rdma link show 出现非 state ACTIVE(GB200 4 张 / GB300 8 张) |
| GPU | dmesg NVRM: Xid 或 fallen off the bus;Xid 79/140、remap 耗尽为不可恢复(分级见附录 D) |
| GPU 计数 | nvidia-smi -L 超时=掉总线,数量 <4 = 掉卡;remapped_rows.failure>0 = remap 失败 |
辅助信号:RoCE packet_seq_err(/sys/class/infiniband/mlx5_*/ports/1/hw_counters/packet_seq_err)是自 boot 累计值,持续暴涨才是恶化信号。
Lustre 类(存储失联是 GB300/GB200 训练卡顿/停摆的高频真因,且状态位极易误判,须看下列决定性信号):
| 环节 | 决定性信号(判故障) |
|---|---|
| LNet NID | lctl list_nids 无 @tcp = LNet 未起或 NI 已拆除(boot-race:bond1 就绪前被消费,socklnd 拆除全部 NI 且不自愈)。lnetctl health_check / systemctl is-active lnet 会误报为健康(镜像用 modprobe 非 lnet.service,健康节点也常为 inactive/disabled),不能当判活依据 |
| 挂载僵尸 | /proc/mounts 有 lustre 条目,但 timeout 15 stat <挂载点> hang = 僵尸挂载(mounted=YES 但传输已死);mount 显示 YES 为假阳性 |
| 服务端路由 | 服务端网段(如 /21)未走 bond1,则包从 bond0 出被反欺骗丢弃,SYN-SENT 挂死、I/O 卡死。查 ip route get <服务端IP> 是否 dev bond1 |
| 服务端可达 | lctl ping <服务端NID> 逐个探(NID 取自 osc.*.ost_conn_uuid / mdc.*.mds_conn_uuid,IDLE 也在);不可达 ≥3 个 distinct 服务端 = 整组失联。被动看 dmesg/日志有 workload 依赖:空闲机 osc import 处 IDLE 不发保活,真断路在训练前不进日志,预检误判为正常,必须主动 lctl ping |
辅助信号:dmesg LustreError / mount 返回 rc=-22(boot-race 无 NID 的恢复失败)/ -108(连接被对端断)。Lustre 失联多为共因(同一 host/网络路径下多台同时对整组服务端失联),排查须对多台同域机器横向对账,不能只看单机。
参考:GPU 故障排查(概念,含 XID 处置) · 监控 GPU(UI 操作) · NVIDIA Xid errors · Lustre 运维手册(lctl / lnetctl 命令参考)
1.5 VM degraded 与恢复
查 sub-block 健康:
gcloud beta compute reservations sub-blocks describe <RESERVATION> \
--block-name=<BLOCK> --sub-block-name=<SUBBLOCK> --zone=<ZONE> \
--full-view=SUB_BLOCK_VIEW_FULL | grep -iE 'count|inUse|health|degraded|status'
- 关键字段:
healthStatus、healthyHostCount、degradedHostCount、inUseHostCount。 - 能否建新机:
healthyHostCount − inUseHostCount > 0(有健康空槽)。 start后 STAGING 又回滚 TERMINATED,说明落到 degraded/消毒中的 host,换有健康空槽的 sub-block 重试。- 识别某 host 在消毒:
degradedHostCount只是辅助 / 滞后信号(聚合计数,标记滞后 24~31 分钟,不区分消毒型与硬件故障型 degraded);权威判法是自行记录被stop/delete的实例与时间戳,按“约 1h 后回落基线”核对(见 §1.1)。官方无 per-host 消毒状态 API,消毒型(约 1h 自愈)与硬件型(不自愈)须隔约 1h 复查区分。 - 识别整域被 Google 维护占用(会致 stockout):
gcloud compute reservations describe <RESERVATION> --zone=<ZONE>看顶层maintenanceOngoingCount/upcomingGroupMaintenance.maintenanceStatus;子块maintenanceStatus=PENDING/ONGOING时,即使healthStatus=HEALTHY、健康计数全绿,也可能冻结该子块可订性。 - 可订性最终判据(成本最低的探针):健康计数无法保证可订出——直接建一台测试,若回滚并报
ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS+reason: stockout即为不可订;探测实例仅到 PROVISIONING、未落 host,不触发消毒。已实测:某子块 18/18 健康但maintenanceStatus=PENDING时,MIG 与单机建机均 stockout。 - 每域 ≤2/18 degraded 属正常(16/18 SLA)。
- 恢复时长:消毒类 degraded 约 1h 自动回;真硬件报障(report-host-as-faulty)修复通常 3~14 天。
- 恢复后重建须按完全相同的拓扑参数(命名序列、reservation sub-block 全路径、
--resource-policies、网络接口),否则拓扑不匹配将导致 NCCL 严重降速;镜像与 startup 也须按 §1.2 的配对(GB300=v22+v7.1),配错将导致 8 张 RDMA 全部 DOWN 且外部难以察觉。
参考:预留总览(概念) · 集群 / 预留健康监控(UI 操作) · sub-blocks describe CLI · reservations describe CLI
1.6 Domain 全挂(NVLink 交换机 / 同域多主机故障)
sub-block 级 = 一个 NVL72 NVLink domain。
如何判断是“交换机 / 整域故障”而非“单 GPU 故障”(GB200/GB300 属 Blackwell 世代,判据已变):
- 旧世代判据不适用:A100/H100 上用 Xid 74 / NVSwitch SXid 判交换机的做法在 Blackwell 上失效——NVIDIA XID 目录明确 Xid 74
Applies to GB200: NO;NVSwitch 的 SXid fatal/non-fatal 报错在 B200/B300 已弃用,改由 DCGM 经 NVSDM(NVSwitch Device Monitoring)读 NVSwitch port/ASIC 计数;Blackwell 上 NVLink/NVSwitch 相关错误码另有更新(如 Xid 145 = NVLINK RLW Error、Xid 149 = NVLINK NETIR Error),判读以 DCGM/NVSDM 读取的 NVSwitch 计数为准,不再依赖经典 dmesg 抓取。GCP 排障页仍把 Xid 74/79/140 列为高概率硬件故障,故 GB300 上“没有 Xid 74”不等于“交换机没坏”,以机内实际现象为准。 - 单 GPU 故障:错误收敛到同一 GPU 索引 / 同一 PCI BDF,
nvidia-smi -r复位该 GPU 或 reboot 节点即可清除,按单机report-host-as-faulty处理(§2.2)。 - 交换机 / 整域故障:① 多张 GPU、多台 host 同步报 NVLink 类错,共同点为连到同一 switch / 同一 sub-block,且逐台 reset/reboot 均无法清除;② Blackwell 世代首选用 DCGM /
dcgmi或 NVSDM 查看某 NVSwitch ASIC/port 计数异常(经典 dmesgnvidia-nvswitchX: SXid ... Fatal在本世代未必出现),确认后再走下述域级report-subblock-as-faulty。
报障会立即中断该 domain 内所有 VM,须先整域撤空再报:
gcloud beta compute reservations sub-blocks report-subblock-as-faulty <RESERVATION> \
--project=<P> --zone=<ZONE> --block-name=<BLOCK> --sub-block-name=<SUBBLOCK> \
--disruption-schedule=IMMEDIATE \
--failure-component=NVLINK_SWITCH \
--fault-reasons="behavior=SWITCH_FAILURE,description=<文本>"
--disruption-schedule仅IMMEDIATE。--failure-component:NVLINK_SWITCH或MULTIPLE_FAULTY_HOSTS。behavior:PERFORMANCE/SWITCH_FAILURE/GPU_ERROR。- 与单机
report-host-as-faulty(§2.2)的区别:后者作用单实例,前者作用整域。只有 sub-block 级有 report faulty,block 级和顶层 reservation 没有。
参考:报障步骤(概念 / 操作指南) · 故障主机 API 排障(概念) · report-subblock-as-faulty CLI(域级暂无独立 UI 页) · NVIDIA Xid Catalog(含 Applies to GB200 列,可核实 Xid 74/145/149)
2. 运维常用命令
2.1 批量建机(bulk create,消费共享预留)
命名与参数按生产环境的固定模式:worker <PREFIX>-d<DDDD>-w<0..17>、policy <PREFIX>-nvl72-policy-<DDDD>、网络 <PREFIX>-*-net;<...> 为敏感项(项目号、reservation 全名)占位,其余按机型如实给出。
前置(一次性,仅首次交付):下列建机命令引用的 VPC / 子网 / RDMA network profile / placement policy 均为一次性资源,首次交付创建一次,之后每次开机 / 扩容只重复本节命令并引用它们。若环境已预置(如本项目 sub-block 的 placement policy 已由平台预设),核实存在后直接引用,不要重复创建。GB200 与 GB300 的前置资源有差异,完整创建步骤、各资源作用与官方文档链接见附录 H:首次交付一次性前置资源。
GB300(us-central1-b,PREFIX=gb300-central):
PROJECT=<项目号>; RES=<reservation 全名> # 敏感,占位
ZONE=us-central1-b; d=<DDDD> # subblock 4 位号,如 0019
BLOCK=${RES}-block-0001; SUBBLK=${BLOCK}-subblock-${d}
RES_PATH="projects/${PROJECT}/reservations/${RES}/reservationBlocks/${BLOCK}/reservationSubBlocks/${SUBBLK}"
NAMES=$(seq 0 17 | sed "s/^/gb300-central-d${d}-w/" | paste -sd,)
# SSH 公钥:GCE 把 metadata ssh-keys 写入对应用户的 ~/.ssh/authorized_keys;
# 格式“登录用户名:公钥内容”,多把 key 换行分隔。替换为贵方公钥。
SSH_KEYS="<登录用户名>:<客户公钥>"
# Lustre:startup v7.1 从下面三个 metadata 读取并写 /etc/sysconfig/lustre-client + fstab。
# 缺 lustre-mgs-nid 或 lustre-mountpoint ⇒ 本机不挂 lustre(什么都不写)。按目标 Lustre 部署填写。
LUSTRE_MGS=<MGS_NID,如 44.10.26.7@tcp:/lustrefs>
LUSTRE_MP=<挂载点,如 /apdcephfs_wzaz>
LUSTRE_CIDR=<lustre 网段,如 44.10.24.0/21>
METADATA="serial-port-enable=true,ssh-keys=${SSH_KEYS},lustre-mgs-nid=${LUSTRE_MGS},lustre-mountpoint=${LUSTRE_MP},lustre-peering-cidr=${LUSTRE_CIDR}"
gcloud beta compute instances bulk create \
--project=$PROJECT --zone=$ZONE \
--predefined-names="${NAMES}" \
--count=18 --min-count=16 \
--machine-type=a4x-maxgpu-4g-metal \
--image=tlinux-gb300-ipv6-dual-50gb-v22 --image-project=$PROJECT \
--boot-disk-size=200GB --boot-disk-type=hyperdisk-balanced \
--scopes=cloud-platform \
--reservation-affinity=specific --reservation=${RES_PATH} \
--provisioning-model=RESERVATION_BOUND \
--instance-termination-action=STOP \
--on-host-maintenance=TERMINATE --restart-on-failure \
--resource-policies=gb300-central-nvl72-policy-${d} \
--network-interface=nic-type=IDPF,network=gb300-central-mgmt-net,subnet=gb300-central-mgmt-sub \
--network-interface=nic-type=IDPF,network=gb300-central-lustre-net,subnet=gb300-central-gvnic1-sub,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
--metadata="${METADATA}" \
--metadata-from-file=startup-script=tlinux4-customer-init-universal-v7dot1.sh \
--async
# 网卡共 10 张:2×IDPF(mgmt/lustre)+ 8×MRDMA(RDMA,IPv6-only)。
# 注1:startup v7.1 必须配 v21 及以后的镜像(此处 v22 已内置 lustre-lnet.service);
# 在 v19/v20 镜像上跑会写出指向不存在服务的 fstab 行导致挂载失败,老镜像请改用 v6.x startup。
# 注2:bulk create 的 --count=18/--min-count=16 允许最多 2 台 degraded;写 18 则任一台报修整条命令被拒。
GB200(us-east1-d,PREFIX=gb200-east):
GB200 与 GB300 的镜像 / startup 组合不同,不能混用。v7.1 startup 依赖 v21+ 镜像内置的
lustre-lnet.service,而 GB200 目前只有 v19 镜像(tlinux-gb200family HEAD),故 GB200 配 v6.x 通用 startup(镜像层自行modprobe lustre),GB300 才用 v22 + v7.1。若 GB200 误用 v7.1,会写出指向不存在服务的 fstab 行,导致挂载失败。
PROJECT=<项目号>; RES=<reservation 全名>
ZONE=us-east1-d; d=<DDDD> # 如 0015 / 0016
BLOCK=${RES}-block-0001; SUBBLK=${BLOCK}-subblock-${d}
RES_PATH="projects/${PROJECT}/reservations/${RES}/reservationBlocks/${BLOCK}/reservationSubBlocks/${SUBBLK}"
NAMES=$(seq 0 17 | sed "s/^/gb200-east-d${d}-w/" | paste -sd,)
# SSH 公钥:格式“登录用户名:公钥内容”,多把 key 换行分隔。替换为贵方公钥。
SSH_KEYS="<登录用户名>:<客户公钥>"
# GB200 v19 镜像烤入的 dispatcher 会读 lustre-peering-cidr 补 lustre 服务器 /21 路由。
LUSTRE_CIDR=<lustre 网段,如 44.10.8.0/21>
METADATA="serial-port-enable=true,ssh-keys=${SSH_KEYS},lustre-peering-cidr=${LUSTRE_CIDR}"
gcloud beta compute instances bulk create \
--project=$PROJECT --zone=$ZONE \
--predefined-names="${NAMES}" \
--count=18 --min-count=16 \
--machine-type=a4x-highgpu-4g \
--image-family=tlinux-gb200 --image-project=$PROJECT \
--boot-disk-size=1000GB --boot-disk-type=hyperdisk-balanced \
--scopes=cloud-platform \
--reservation-affinity=specific --reservation=${RES_PATH} \
--provisioning-model=RESERVATION_BOUND \
--instance-termination-action=STOP \
--on-host-maintenance=TERMINATE --restart-on-failure \
--resource-policies=gb200-east-nvl72-policy-${d} \
--network-interface=nic-type=GVNIC,network=gb200-east-gvnic-net-0,subnet=gb200-east-gvnic-sub-0 \
--network-interface=nic-type=GVNIC,network=gb200-east-gvnic-net-1,subnet=gb200-east-gvnic1-sub,no-address \
--network-interface=nic-type=MRDMA,network=gb200-east-rdma-net,subnet=gb200-east-rdma-net-sub-0,no-address \
--network-interface=nic-type=MRDMA,network=gb200-east-rdma-net,subnet=gb200-east-rdma-net-sub-1,no-address \
--network-interface=nic-type=MRDMA,network=gb200-east-rdma-net,subnet=gb200-east-rdma-net-sub-2,no-address \
--network-interface=nic-type=MRDMA,network=gb200-east-rdma-net,subnet=gb200-east-rdma-net-sub-3,no-address \
--metadata="${METADATA}" \
--metadata-from-file=startup-script=tlinux4-customer-init-universal.sh \
--async
# 网卡共 6 张:2×GVNIC + 4×MRDMA。nic1 子网是 gb200-east-gvnic1-sub(非 gvnic-sub-1)。
关键约束:
- 预留必须精确到 sub-block 全路径,并带
RESERVATION_BOUND,否则落 on-demand 导致 stockout(即使 subblock 有健康空槽)。 - 用
--min-count=16(允许最多 2 台 degraded);写 18 则任一台报修整条命令被拒。 - 补建缺口:修好后重跑 bulk create 只传缺的名字(见 §2.3),且必须同 Policy + 同 Subblock,否则报
PLACEMENT_POLICY_CONSTRAINTS_INFEASIBLE。 <项目号>/<reservation 全名>为敏感项,按自有环境替换。
参考:A4X Max 批量建机(UI 操作) · 批量创建概念 · bulk create CLI · placement policy(概念) · resource-policies CLI
2.2 故障处理与升级路径
处理原则:尽量避免停机,先软后硬,report faulty 为最后手段。
| 步骤 | 动作 | 何时用 |
|---|---|---|
| 1 | 定位:NCCL 自检失败 / busBW<600 / #wrong≠0,或 §3 pre-flight FAIL | 发现异常 |
| 2 | nvidia-smi -r 复位 GPU(需无进程占用),恢复后重跑自检 | 可恢复 GPU 状态,如 Xid 48/63/64 |
| 3 | gcloud compute instances reset <VM> --zone=<ZONE>(先 sync) | GPU reset 无效或整机异常。GB300 reset 不消毒,是首选;GB200 同样可 reset |
| 4 | 下架该节点(kubectl cordon / drain),停止把坏机带进作业 | reset 仍不恢复 |
| 5 | report-host-as-faulty(送修,不可逆) | 确诊真硬件故障:NIC 心跳丢、GPU 掉总线、remap 耗尽、不可恢复 Xid(79/140) |
| 6 | 整域撤空后 report-subblock-as-faulty(§1.6) | 同域多台同时故障 / NVLink switch 故障 |
reset 前先执行 sync:硬重启会截断未落盘的写。
单实例报障(会停机,主机修复通常 3~14 天):
gcloud compute instances report-host-as-faulty <INSTANCE> \
--project=<P> --zone=<ZONE> \
--disruption-schedule=IMMEDIATE \
--fault-reasons="behavior=UNRECOVERABLE_GPU_ERROR,description=<如 Xid 79 on GPU2>"
--disruption-schedule:IMMEDIATE或FUTURE。behavior:PERFORMANCE/SILENT_DATA_CORRUPTION/UNRECOVERABLE_GPU_ERROR/CHIP_ERROR。
参考:报障步骤(概念 / 操作指南) · report-host-as-faulty CLI · 重启实例(UI 操作) · instances reset CLI · 需人工支持见 §2.4
2.3 从 degraded host 恢复机器(当前 bulk create 场景)
未使用 MIG 时,恢复为人工重建。原则:先按 §2.2 判定——GB300 原机仍可 reset 的优先 reset(不消毒),仅当 host 已 degraded / 无法 reset 时才重建。重建即按缺失编号、以完全相同的拓扑参数逐台补回。
以下为可直接使用的缺口补建脚本:以 subblock 当前健康主机数为目标,算出缺失编号,再用单条 bulk create 补齐(优于逐台 create:原子提交、--min-count 容缺、拓扑一次校验)。默认 DRY_RUN=1 仅打印,确认后置 DRY_RUN=0 执行。GB300 版:
#!/usr/bin/env bash
# 从 degraded host 恢复:查健康主机数 → 算缺失编号 → 一条 bulk create 补齐
set -u
PROJECT=<项目号>; RES=<reservation 全名> # 敏感,占位
ZONE=us-central1-b; d=<DDDD> # 目标 subblock,如 0019
PREFIX=gb300-central # GB200 改 gb200-east(见下)
DRY_RUN=${DRY_RUN:-1}
BLOCK=${RES}-block-0001; SUBBLK=${BLOCK}-subblock-${d}
RES_PATH="projects/${PROJECT}/reservations/${RES}/reservationBlocks/${BLOCK}/reservationSubBlocks/${SUBBLK}"
# 1) 该 subblock 健康主机数(目标台数)
HEALTHY=$(gcloud beta compute reservations sub-blocks describe "$RES" \
--block-name="$BLOCK" --sub-block-name="$SUBBLK" --zone="$ZONE" --project="$PROJECT" \
--full-view=SUB_BLOCK_VIEW_FULL --format="value(healthInfo.healthyHostCount)")
# 2) 现存 VM 的 w 编号 → 与 0..17 取差集,拼出缺失名字
mapfile -t EXIST < <(gcloud compute instances list --project="$PROJECT" \
--filter="name~^${PREFIX}-d${d}-w[0-9]+$" --format="value(name)" \
| sed -E "s/.*-w([0-9]+)$/\1/" | sort -n)
MISSING=()
for n in $(seq 0 17); do
printf '%s\n' "${EXIST[@]}" | grep -qx "$n" || MISSING+=("${PREFIX}-d${d}-w${n}")
done
NEED=$(( HEALTHY - ${#EXIST[@]} )); [ "$NEED" -lt 0 ] && NEED=0
NAMES=$(printf '%s\n' "${MISSING[@]:0:$NEED}" | paste -sd,)
echo "healthy=$HEALTHY exist=${#EXIST[@]} need=$NEED names=$NAMES"
[ "$NEED" -le 0 ] && { echo "无需补建"; exit 0; }
[ "$DRY_RUN" = 1 ] && { echo "[dry-run] 将 bulk create: $NAMES"; exit 0; }
# 3) 一条 bulk create 补齐(机型/镜像/预留/policy/网卡与 §2.1 GB300 完全一致,含完整 8×MRDMA)
# METADATA(serial-port-enable + ssh-keys + lustre-*)同 §2.1 GB300 块定义
gcloud beta compute instances bulk create \
--project="$PROJECT" --zone="$ZONE" \
--predefined-names="$NAMES" --count="$NEED" --min-count=1 \
--machine-type=a4x-maxgpu-4g-metal \
--image=tlinux-gb300-ipv6-dual-50gb-v22 --image-project="$PROJECT" \
--boot-disk-size=200GB --boot-disk-type=hyperdisk-balanced --scopes=cloud-platform \
--reservation-affinity=specific --reservation="$RES_PATH" \
--provisioning-model=RESERVATION_BOUND --instance-termination-action=STOP \
--on-host-maintenance=TERMINATE --restart-on-failure \
--resource-policies="gb300-central-nvl72-policy-${d}" \
--network-interface=nic-type=IDPF,network=gb300-central-mgmt-net,subnet=gb300-central-mgmt-sub \
--network-interface=nic-type=IDPF,network=gb300-central-lustre-net,subnet=gb300-central-gvnic1-sub,no-address \
--network-interface=nic-type=MRDMA,network=gb300-central-rdma-net,subnet=default-subnet-1-gb300-central-rdma-net,stack-type=IPV6_ONLY,no-address \
`# ↑ MRDMA 共 8 张,完整 8 行见 §2.1 GB300 块,此处照抄` \
--metadata="${METADATA}" \
--metadata-from-file=startup-script=tlinux4-customer-init-universal-v7dot1.sh --async
--min-count容缺(官方语义):实际成功建出的实例数 ≥--min-count时,保留已建出的实例、命令返回成功;不足--min-count才整批回滚删除已建实例。故个别缺失编号对应的物理 host 仍 degraded 时,bulk create会建出其余健康主机、部分成功(等效于逐台 create“单台失败不影响其它”的容错);--min-count=1表示只要有一台成功即不回滚。
GB200 用同一套缺口补建逻辑,差异仅一处:GB200 是 VM(无消毒),故障机可直接 delete 后重建,无需先 reset、无需等待约 1h 消毒。将脚本头部改为 ZONE=us-east1-d; PREFIX=gb200-east,bulk create 段按 §2.1 GB200 块替换(a4x-highgpu-4g / --image-family=tlinux-gb200 / 1000GB 盘 / gb200-east-nvl72-policy-${d} / 2×GVNIC+4×MRDMA / v6.x startup)。其余(同 Policy + 同 Subblock 全路径 + 相同命名序列 + RESERVATION_BOUND)完全一致。
要点:
- 重建必须同 Policy + 同 Subblock + 相同命名序列(否则报
PLACEMENT_POLICY_CONSTRAINTS_INFEASIBLE或拓扑不匹配致 NCCL 降速)。 - 建机后个别实例 STAGING 又回滚 TERMINATED,表示该编号落到 degraded/消毒中的 host(健康计数为聚合值,不等于每台均可订);在同一 subblock 重试即可(
--min-count保证其余健康主机照常建出,缺口那台待故障 host 修复或让出空槽再补)。不要更换 subblock——更换子块即非回填,且会破坏同 Policy / 同拓扑约束(见上条)。 - 恢复应使用 reset / 重建,不要使用
report-host-as-faulty(该操作为送修,主机将 degraded 数天);仅在确诊硬件故障时(§1.4、§2.2)才报障。MIG 场景下的自动 recreate 见 §4.1。
重建后:平台登记(必做)+ 打标签(自动化建议)
新建 / 重建的机器不会自动继承旧机的 label,平台侧亦需重新获取 VM 名 / ID / 内网 IP / 所属 sub-block、block 方能登记注册。
A. 采集平台登记字段(必做)
采集 VM 名 / ID / 机型 / 内网·公网 IP / sub-block·block,交平台登记——这是我方能确定、也必须交付的:
# 单台完整标识
gcloud compute instances describe "$NAME" --zone="$ZONE" --project="$PROJECT" \
--format='value(name,id,machineType.basename(),status,creationTimestamp,lastStartTimestamp)'
# 内网 IP(bond0,SSH 用)/ 公网 IP(走专线无外网 IP 者此列为空,属正常)
gcloud compute instances describe "$NAME" --zone="$ZONE" --project="$PROJECT" \
--format='value(networkInterfaces[0].networkIP,networkInterfaces[0].accessConfigs[0].natIP)'
# 所属 sub-block / block(physical topology,可读名;需实例 RUNNING)
gcloud compute instances describe "$NAME" --zone="$ZONE" --project="$PROJECT" \
--format='value(resourceStatus.physicalHostTopology.block,resourceStatus.physicalHostTopology.subblock)'
# 或一次性列出整批,导 CSV 交平台登记
gcloud compute instances list --project="$PROJECT" --zones="$ZONE" \
--filter="name~^${PREFIX}-d${d}-w[0-9]+$" \
--format="csv(name,id,machineType.basename(),status,networkInterfaces[0].networkIP,networkInterfaces[0].accessConfigs[0].natIP,resourceStatus.physicalHostTopology.subblock)"
VM 内部也可免鉴权从 metadata 拿拓扑哈希(同一 NVL72 domain 内所有 VM 相同,适合做 k8s 标签):curl -sf -H "Metadata-Flavor: Google" "http://metadata.google.internal/computeMetadata/v1/instance/attributes/physical_host_topology"。
B. 打标签(自动化建议)
打标的维度与命名由贵方按内部规范确定,本手册不代为给出具体方案,仅提供自动化建议:令机器在初始化时(startup script / DaemonSet)自行从 metadata 读取拓扑(physical_host_topology、sub-block 等)并写入 GCE / k8s label,免去逐台手动打标。示例:
# 建议在 startup/DaemonSet 里自取拓扑再打标(GCE 实例 label + k8s 节点 label 各按需)
TOPO=$(curl -sf -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/attributes/physical_host_topology")
# gcloud compute instances add-labels <NAME> --labels=<贵方维度>=<值>
# kubectl label node <NAME> <贵方维度>=<值> --overwrite # 同域调度可避免跨物理域 NCCL fallback 降速
建议全车队统一命名规则、单一来源写标,避免手动 / 自动两套值(如
domain-<编号>与domain-<哈希>)并存。
参考:A4X Max 建机(UI 操作) · instances create CLI · bulk create CLI
2.4 开 support case(升级到人工支持)
report-host-as-faulty(§2.2)与 report-subblock-as-faulty(§1.6)为自助报障路径;需要 Google 侧诊断、说明根因或加速修复队列时,再开 support case(人工)。三者相互独立:确诊单机故障用 report host faulty,同域多机 / switch 故障用 report subblock faulty,不确诊或需说明时开 case(可在描述中注明已执行的 report faulty)。
注:官方
report-host-as-faulty文档未要求必须配合 support case;开 case 加速修复队列为运营实践,非官方明文要求。
创建途径(官方无 gcloud 子命令):Console Support > Cases > Create case,或 Cloud Support API POST .../v2/{parent}/cases。开 case 前按官方“描述问题”六要素备齐信息(信息越具体,处理越快):
| 要素 | 内容 | 本环境取值 / 获取 |
|---|---|---|
| Time | 故障时间(ISO 8601 带时区,不用“昨天”这类相对时间) | 作业日志 / dmesg -T |
| Product | 具体产品 / 机型 | Compute Engine A4X(GB200)/ A4X Max(GB300) |
| Location | region + zone | us-east1-d(GB200)/ us-central1-b(GB300) |
| Identifiers | project ID/number、instance name/ID、故障设备 PCI | gcloud compute instances describe <VM> --zone=<ZONE> --format='value(id,name,zone,machineType,status)';PCI 从 lspci / dmesg |
| Artifacts | 串口输出、dmesg、nvidia-smi、诊断包 | 见下“报障诊断包”四件套 |
| Problem type | intermittent / transient / consistent(consistent 附复现步骤) | 据观察判断 |
优先级与目标初次响应(本项目为 Premium 支持):
| Priority | 目标初次响应(Premium) |
|---|---|
| P1(生产不可用,如整域宕) | 15 分钟 |
| P2(严重降级,多机故障) | 1 小时 |
| P3(局部,单机可迁移) | 4 小时 |
| P4(咨询) | 8 小时 |
- Premium 可开 P1,并可对已开 case 改优先级 / 升级(Escalate)。
- GB 系列建议:① degraded 跌破 16/18 且影响生产,则 report host faulty 后开 case 请求加速;② 整 sub-block 故障,则 report subblock faulty 的同时开 P1/P2 case;③ 不明原因维护 / 重启需查根因,则开 case 请 Google 提供主机事件与原因。case 描述附已做排查 + 诊断包。
报障诊断包(§3 pre-flight 脚本不足以当权威送修包,建议按类型搭配):
| 产物 | 采集命令 | 何时必带 |
|---|---|---|
nvidia-bug-report.log.gz | sudo nvidia-bug-report.sh(GPU/驱动纵深:ECC / retired-pages / XID / nvlink / /proc/driver/nvidia,顺带采 /sys/class/infiniband) | GPU 掉卡 / XID / RDMA 类必带 |
sosreport | sudo dnf install -y sos && sudo sos report --batch(OS 全景:systemd·journal / 存储 / 网络 / 内核参数 / Lustre 配置) | OS / Lustre / 存储疑难加带,与 nvidia-bug-report 互补 |
| 串口输出 | gcloud compute instances get-serial-port-output <VM> --zone=<ZONE> --port=1 | 开不了机 / panic / 启动异常 |
参考:创建 / 管理 case(UI + API) · case 优先级定义 · 描述问题最佳实践(六要素) · 目标响应时间(按 tier) · report faulty host(自助报障)
3. Pre-flight 检查(含 Lustre 稳定性)
训练前逐节点跑,纯只读零变更。首行 RESULT ... verdict=<PASS|WARN|FAIL>,退出码 0/1/2,便于编排层判读(见 §4.2)。
覆盖:LNet NID 存活 / 挂载可读 / 服务端 /21 路由走 bond1 / lctl ping 主动探每个 Lustre 服务端(空闲机也测得出,不依赖 workload)/ mlx5 NIC 固件健康(只算运行时)/ RDMA 链路 / GPU。
#!/usr/bin/env bash
# lustre-preflight.sh —— Lustre / NIC / GPU 训练前预检(纯只读)
# 用法: sudo bash lustre-preflight.sh ; 退出码 0=PASS 1=WARN 2=FAIL
set -u
PING_TIMEOUT="${PING_TIMEOUT:-4}"; NIC_BOOT_GRACE="${NIC_BOOT_GRACE:-300}"; WIN="${WIN:-900}"
host="$(hostname)"; UP=$(awk '{print int($1)}' /proc/uptime); UP="${UP:-0}"
reasons=""; warns=""; add_fail(){ reasons="${reasons:+$reasons,}$1"; }; add_warn(){ warns="${warns:+$warns,}$1"; }
DM=$(dmesg 2>/dev/null)
# 1. LNet NID 存活(唯一可靠信号;health_check/systemctl 会误判)
if lctl list_nids 2>/dev/null | grep -q '@tcp'; then nid=ok; else nid=no; add_fail nid_missing; fi
# 2. 挂载存在且可读(zombie mount: mounted=YES 但传输死,stat 会 hang)
MP=$(awk '$3=="lustre" && $2 !~ /kubelet/ {print $2; exit}' /proc/mounts)
[ -z "$MP" ] && MP=$(awk '$3=="lustre"{print $2; exit}' /proc/mounts)
if [ -z "$MP" ]; then mount=no; add_fail not_mounted
elif ! timeout 15 stat "$MP" >/dev/null 2>&1; then mount=hang; add_fail mount_hang
else mount=ok; fi
# 3. 服务端 /21 路由须走 bond1(缺它包从 bond0 出被反欺骗丢,I/O 卡死)
SRC=$(awk '$3=="lustre"{print $1; exit}' /proc/mounts); MGS=$(echo "$SRC" | sed 's/@.*//')
if [ -n "$MGS" ]; then
if ip route show | grep -qE '/21 .*dev bond1' || ip route get "$MGS" 2>/dev/null | grep -q 'dev bond1'
then route=ok; else route=no; add_fail route_missing; fi
else route=na; fi
# 4. 主动 lctl ping 逐个服务端(取自 osc/mdc conn_uuid,IDLE 也在;不可达 >=3=FAIL,1~2=WARN)
ping_tot=0; ping_ok=0; ping_bad=0; ping_bad_srv="-"
if command -v lctl >/dev/null 2>&1; then
NIDS=$(lctl get_param -n osc.*.ost_conn_uuid mdc.*.mds_conn_uuid 2>/dev/null \
| grep -oE '[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+@tcp' | sort -u)
if [ -n "$NIDS" ]; then
ptd=$(mktemp -d)
for n in $NIDS; do
( timeout "$PING_TIMEOUT" lctl ping "$n" >/dev/null 2>&1 && echo ok || echo "bad ${n%@tcp}" ) \
> "$ptd/$(echo "$n" | tr './@:' '____')" &
done; wait
ping_tot=$(cat "$ptd"/* 2>/dev/null | wc -l)
ping_ok=$(cat "$ptd"/* 2>/dev/null | grep -c '^ok$')
ping_bad=$((ping_tot - ping_ok))
ping_bad_srv=$(cat "$ptd"/* 2>/dev/null | awk '/^bad /{print $2}' | sort -u | tr '\n' ';' | sed 's/;$//')
[ -z "$ping_bad_srv" ] && ping_bad_srv="-"; rm -rf "$ptd"
if [ "${ping_bad:-0}" -ge 3 ]; then add_fail "lctl_ping_unreach(${ping_bad}/${ping_tot})"
elif [ "${ping_bad:-0}" -ge 1 ]; then add_warn "lctl_ping_unreach(${ping_bad}/${ping_tot})"; fi
fi
fi
# 5. mlx5 NIC 健康(link ACTIVE 但固件心跳丢失;只算运行时事件)
nic_health=$(echo "$DM" | grep -iE "device's health compromised" \
| sed -nE 's/^\[[[:space:]]*([0-9]+)\.[0-9]+\].*/\1/p' \
| awk -v up="$UP" -v g="$NIC_BOOT_GRACE" '{ts=$1; if(up-ts<0)next; if(ts<=g)next; rt++} END{print rt+0}')
[ "${nic_health:-0}" -gt 0 ] && add_fail "nic_health($nic_health)"
# 6. RDMA 链路(全 ACTIVE;GB200=4 / GB300=8,只判 down)
rdma_dev=0; rdma_down=0
if command -v rdma >/dev/null 2>&1; then
rl=$(timeout 10 rdma link show 2>/dev/null)
rdma_dev=$(echo "$rl" | grep -c 'link ')
rdma_down=$(echo "$rl" | awk '/link /{if($0 !~ /state ACTIVE/)d++} END{print d+0}')
fi
[ "${rdma_down:-0}" -gt 0 ] && add_fail "rdma_down($rdma_down)"
# 7. GPU 快检(nvidia-smi 只读;不跑 NCCL)
gpu=na
if command -v nvidia-smi >/dev/null 2>&1; then
L=$(timeout 15 nvidia-smi -L 2>/dev/null); grc=$?
if [ "$grc" -eq 124 ]; then gpu=hang; add_fail gpu_hang
elif [ "$grc" -ne 0 ]; then gpu=err; add_fail gpu_err
else
gpu=$(echo "$L" | grep -c '^GPU ')
[ "${gpu:-0}" -lt 4 ] && add_fail "gpu_count($gpu)"
smi=$(timeout 15 nvidia-smi --query-gpu=ecc.errors.uncorrected.aggregate.total,remapped_rows.failure \
--format=csv,noheader,nounits 2>/dev/null)
echo "$smi" | awk -F, '{if($2+0>0)e=1}END{exit !e}' && add_fail gpu_remap_fail
echo "$smi" | awk -F, '{s+=$1}END{exit !(s>0)}' && add_warn gpu_ecc_uncorr
fi
else gpu=nosmi; add_warn gpu_nosmi; fi
gpu_xid=$(echo "$DM" | grep -iE 'NVRM: Xid|fallen off the bus' \
| sed -nE 's/^\[[[:space:]]*([0-9]+)\..*/\1/p' \
| awk -v up="$UP" -v w="$WIN" '{if(up-$1<=w)c++} END{print c+0}')
[ "${gpu_xid:-0}" -gt 0 ] && add_fail "gpu_xid_recent($gpu_xid)"
# 裁决
if [ -n "$reasons" ]; then verdict=FAIL; rc=2
elif [ -n "$warns" ]; then verdict=WARN; rc=1
else verdict=PASS; rc=0; fi
allr="$reasons"; [ -n "$warns" ] && allr="${allr:+$allr,}$warns"; [ -z "$allr" ] && allr="-"
echo "RESULT host=$host verdict=$verdict reasons=$allr uptime_s=$UP nid=$nid mount=$mount route=$route \
ping_ok=${ping_ok}/${ping_tot} ping_bad=${ping_bad} ping_bad_srv=${ping_bad_srv} \
nic_health=${nic_health:-0} rdma_dev=${rdma_dev} rdma_down=${rdma_down} gpu=${gpu} gpu_xid=${gpu_xid:-0}"
exit $rc
- FAIL:NID 丢失 / 未挂载 / mount hang / 缺 /21 路由 / lctl ping 不可达 ≥3 服务端 / NIC 运行时 health / RDMA down / GPU hang·err·数不足·Xid·remap fail。
- WARN:lctl ping 不可达 1~2 / GPU ECC / 无 nvidia-smi。
- 隔 SSH 跑长检用
sudo systemd-run --unit=preflight --collect bash lustre-preflight.sh(SSH 断开时 logind 会杀 user session,nohup 挡不住)。
4. 推荐自动化方案(最简)
上架自动化使用 startup script,恢复自动化主推 stateful MIG(§4.1)。§4.2–4.4 为配套 / 备选方案,仅给出关键步骤与参考链接供选型讨论,最终采用方案由贵方按现网技术栈确定。
4.1 Stateful MIG + startup script
- 建机改为 stateful MIG:
--stateful-internal-ip=interface-name=nic0,auto-delete=never保留 nic0 内网 IP,--default-action-on-vm-failure=repair在判定故障时自动 recreate,实例名与 nic0 内网 IP 均完整保留(已实测:主动recreate-instances与直接instances delete均被 MIG 自动拉回同名同 IP,无需人工补机)。 - 上架(分区 / 网卡改名 / sshd)全部交给 startup script(GB300 用
tlinux4-customer-init-universal-v7dot1.sh,配 v22 镜像),template 中以--metadata-from-file=startup-script=...注入,新机开机即自动完成,无需人工登录操作。
恢复主推 stateful MIG 的原因(已实测):价值在于自愈与保态。
--default-action-on-vm-failure=repair在判定故障时自动 recreate,--stateful-internal-ip保留实例名与 nic0 内网 IP(实测 recreate/delete 均被拉回同名同 IP,无需人工补机)。MIG 绑定 workload policy(accelerator-topology=1x72,type=high-throughput),--size设为当前健康台数(如 16)先行拉起,故障 host 修复后 resize 至 18,第 18 台由 MIG 自动补齐。单机与bulk create --min-count=N亦可在缺若干台的子块上按健康台数部分建起(成功数不低于阈值即保留),但无自愈、无保态,故恢复自动化主推 MIG。可订性闸门(预留可订容量与maintenanceStatus)对 MIG 与单机一致(见下文与 §2.3)。
两套 policy 的分工(建机绑哪个):
| 维度 | Placement Policy(紧凑放置) | Workload Policy(工作负载) |
|---|---|---|
| 用于 | 单机 / bulk create | 托管实例组 MIG(及 GKE 节点池) |
| 关键参数 | --gpu-topology=1x72、--collocation=COLLOCATED | --accelerator-topology=1x72、--type=high-throughput |
| 生效周期 | 一次性:仅建机瞬间做拓扑摆放校验 | 全生命周期:建机 / 自愈 / 保 IP / 滚动更新持续维持拓扑 |
| 部分出让 | bulk create --min-count=16(成功数≥阈值即保留) | --size=16 弹性,故障时按健康台数拉起 |
| 故障恢复 | 无自愈,需人工重跑 create | MIG 自愈:自动重建并补齐节点 |
- Placement Policy 解决“此刻能否把这些机器放进同一 1x72 NVLink 域”(静态一次性);Workload Policy 解决“建机 / 自愈 / 保 IP / 伸缩全周期内持续维持 1x72 拓扑”(动态长效)。故批量上架(§2.1)用现成的 placement policy,自动恢复(MIG)用 workload policy。
# 1) workload policy(A4X Max MIG 需 workload 类型,COLLOCATED 复用不了)
gcloud compute resource-policies create workload-policy <POLICY> \
--type=high-throughput --accelerator-topology=1x72 --region=<REGION> --project=<P>
# 2) instance-template(MIG 场景 termination-action 用 DELETE)
gcloud compute instance-templates create <TMPL> --project=<P> \
--machine-type=a4x-maxgpu-4g-metal \
--image=tlinux-gb300-ipv6-dual-50gb-v22 --image-project=<IMG_PROJ> --scopes=cloud-platform \
--reservation-affinity=specific --reservation=<RES_SUBBLOCK_全路径> \
--provisioning-model=RESERVATION_BOUND \
--instance-termination-action=DELETE --maintenance-policy=TERMINATE --restart-on-failure \
--metadata="${METADATA}" \
--metadata-from-file=startup-script=tlinux4-customer-init-universal-v7dot1.sh \
--network-interface=subnet=<MGMT_全路径>,nic-type=IDPF # 完整 10 网卡按 §2.1 追加
# METADATA(serial-port-enable + ssh-keys + lustre-*)同 §2.1 GB300;v7.1 须配 v21+ 镜像(此处 v22)
# 3) stateful MIG(保命名/nic0 IP + 绑机架 + 自动修复);--size 先取当前健康台数(如 16)
gcloud compute instance-groups managed create <MIG> --zone=<ZONE> --project=<P> \
--template=<TMPL> --size=16 \
--workload-policy="projects/<P>/regions/<REGION>/resourcePolicies/<POLICY>" \
--stateful-internal-ip=interface-name=nic0,auto-delete=never \
--default-action-on-vm-failure=repair \
--update-policy-replacement-method=recreate --update-policy-max-surge=0
# 4) 健康台数恢复到 18 后扩到满域(第 18 台待故障 host 修好由 MIG 自动补齐,同命名规则)
gcloud compute instance-groups managed resize <MIG> --zone=<ZONE> --size=18
# 5)(可选,仅展示我方做法、贵方已有监控可略)health-check 自愈补"存活但卡死"(SSH/驱动 hang)层;裸金属起得慢,initial-delay 给 1200s
gcloud compute health-checks create tcp <HC> --port=22 \
--check-interval=30 --timeout=10 --healthy-threshold=2 --unhealthy-threshold=3
gcloud compute instance-groups managed update <MIG> --zone=<ZONE> \
--health-check=<HC> --initial-delay=1200
- 实例命名:MIG 建出的机器名 =
--base-instance-name+-<随机 4 字符>(如gb300-mig-a1b2);未设--base-instance-name时默认取 MIG 名前缀。stateful MIG 下 recreate / autoheal 保持同名(与 stateful IP 一并复用)。需注意:MIG 不支持像 §2.3bulk create --predefined-names那样逐台指定固定序列名(-0001..0018),只能是“base 加随机后缀、此后保持不变”;若命名须与 bulk 序列对齐,MIG 无法满足。 - MIG 场景
--instance-termination-action=DELETE(与单机/bulk 的 STOP 不同;RESERVATION_BOUND的 MIG 只支持 DELETE)。 --default-action-on-vm-failure=repair只在 VM 本身失败/被删时触发;"存活但卡死"的机器要靠第 5 步 health-check 才能自愈。- 手动触发单台重建:
gcloud compute instance-groups managed recreate-instances <MIG> --zone=<ZONE> --instances=<INSTANCE_NAME>(实测重建后同名同 IP)。 - MIG 上 recreate / health-check 自愈 / resize 缩容均等同于 delete,GB300 每台约 1h 消毒,批量操作成本高;health-check 阈值不宜过于敏感。
- 可订性闸门:即使子块"既空又健康",若
maintenanceStatus=PENDING(未计划维护锁)仍可能 stockout。已实测:某子块 18/18 健康但处 PENDING 时,MIG 与单机双双 stockout;另一子块maintenanceStatus=NONE(17 健康 1 降级)MIG--size=16建机成功。建机前最便宜的可订性探针 = 单机create试一次(回滚不落 host、不消毒)。
MIG 下“表面 healthy、内部故障”的处理(勿直接 delete 单台):
手工 delete/stop MIG 中的单台实例时,配置了 --default-action-on-vm-failure=repair 的 MIG 会将其判为“非 MIG 发起的失败”,自动按模板 recreate 一台同名实例(stateful 下同 IP/盘);但 recreate 走 RESERVATION_BOUND + 同 subblock,故障 host 未被隔离,可能再次落回该 host,或因无“既空又健康”槽而 stockout。使故障 host 真正下线的是 report-host-as-faulty,而非 MIG recreate。三个 MIG 动作的语义:
| 动作 | 语义 | 适用 |
|---|---|---|
abandon-instances | 不重启不删 VM,仅移出 MIG 管理 + targetSize−1 | 推荐:移出故障机交人工 / 送修(VM 保活,可 SSH 诊断与报障,MIG 不再自动补) |
delete-instances | 永久删除 VM + 缩容(丢失 stateful 态) | 不适用:硬件故障时不用 |
recreate-instances | 按模板删除后重建(stateful 保 name/IP/盘) | 不适用:硬件故障时重建仍落回故障 host,无意义 |
推荐流程:① k8s 层 cordon + drain 摘业务;② SSH 人工诊断,可逆先试 nvidia-smi -r / reset(GB300 裸金属 reset 不消毒是首选、stop/delete 才消毒);③ 确诊不可恢复时,先 abandon-instances 把该台移出 MIG(避免报障与 recreate 互相干扰),保持 RUNNING 对它 report-host-as-faulty(A4X Max 属 All Capacity Mode:报障后有富余容量则迁到健康 host、实例全程 RUNNING、name/IP/disk 不变;报障进行中删除实例会导致报障失败,勿先 stop 再报障);④ 需补充算力时,在同 subblock 选健康槽另开新机并加回 MIG。
顺序依据(官方语义):
abandon-instances明确“不重启、不删除底层实例,仅把实例移出组、减小 targetSize”。故先 abandon 把坏机摘出组外,可避免 MIG 误判去 recreate;VM 本身仍在、仍能正常report-host-as-faulty。
参考:A4X Max MIG 创建(UI 操作) · Stateful MIG 总览(概念) · 配置 stateful MIG(含 stateful IP) · MIG autohealing(概念) · placement policy(概念) · workload policy 概览(概念) · managed create CLI · group-placement policy CLI
4.2 Pre-flight 到自动 cordon / drain / report faulty(参考)
关键机制(决定方案设计):只有 taint 能真正阻挡调度——自定义 NodeCondition、Pod 的 readinessGates 均不影响节点调度;节点可用 kubelet registerWithTaints 带 taint 加入,但移除 taint 的逻辑需自建;预检 DaemonSet 必须显式 tolerate 自定义 taint,否则自锁。
关键步骤(推荐 (a)+(b),(c) 可选):
- (a) 调度前闸门:节点带
preflight/pending:NoSchedule加入,预检通过前业务不会被调度到该节点(无竞态)。 - (b) 首检 + 移除 + 巡检 DaemonSet:privileged / hostNetwork、显式 tolerate 该 taint;首启运行 §3 preflight,通过则移除 taint,之后周期巡检,按退出码动作(FAIL 时 cordon+drain,WARN 时 cordon 待人工)。仅 (b) 无 (a) 存在时序问题(首检可能晚于业务 Pod 落节点),故须与 (a) 组合。
- (c) 运行期自愈(可选):将 preflight 封装为 Node Problem Detector(NPD)custom-plugin-monitor 上报 NodeCondition(NPD 与 GKE node auto-repair 检测层同款、开源活跃,仅检测上报、不执行 cordon/drain)。自愈执行组件本手册不做单一背书,由贵方按现网栈自选。
巡检 DaemonSet 按 §3 preflight 退出码动作:FAIL(rc=2)执行 cordon + drain;WARN(rc=1)仅 cordon 待人工复核;仅在确诊硬件故障(NIC 心跳丢失 / GPU Xid、remap)时才 report-host-as-faulty(不可逆送修),软故障(lustre 失联 / 路由丢失)先 reset 热重启复检,不立即报障。
参考:Node Problem Detector · 节点 taint 与调度 · 安全 drain 节点 · report faulty host
4.3 自建 k8s:紧急维护自动 cordon / drain / 续训(参考)
对应 §1.3 紧急维护(提前量短、可能无人值守):自建 DaemonSet 自动 cordon/drain(drain 向训练 Pod 发 SIGTERM 触发 checkpoint),仅摘除节点、不执行维护本身。GKE 提供托管 maintenance-handler(闭源,新版默认关闭);cordon/drain/SIGTERM 均为通用 k8s 原语、自建可完整复刻,需自行实现的仅为“监听 metadata 维护信号的循环”(约 30 行 shell)。
关键步骤:
- 每节点一个 DaemonSet Pod(
hostNetwork: true、downward API 取 nodeName):hanging GET 监听maintenance-event→cordon+drain --grace-period=<按 1h 提前量倒推>→ 维护后节点原地回来(GB200/GB300 均 automaticRestart)→uncordon复用。 - 训练侧闭环另一半:Pod 设足够长的
terminationGracePeriodSeconds(须 < 1h 提前量)+ 捕获SIGTERM异步存 checkpoint(NeMo/Megatron→nvidia-resiliency-ext,JAX→Orbax);用 JobSet(failurePolicy.maxRestarts)+ Kueue 做 job 级整体重启、从最近 checkpoint 续跑。
注意事项:① terminationGracePeriodSeconds 在 k8s 侧无硬上限,但有效上限为 1h 维护提前量(到点强制停机),须按提前量倒推设值;② 维护过程中 metadata 可能返回 HTTP 503,循环需容错重试,不应视为“维护取消”;③ 存在 PDB 时须走 kubectl drain(Eviction API)而非直接 delete pod;④ 容器镜像需同时包含 kubectl 与 curl。
参考:GKE 处理 GPU/TPU 中断 · metadata hanging GET + 503 重试 · k8s Pod 终止(SIGTERM→grace→SIGKILL) · JobSet failurePolicy · Kueue · nvidia-resiliency-ext · Orbax 异步 checkpoint
4.4 无 stateful MIG 条件时:事件驱动自愈(备选)
不具备迁移 stateful MIG 条件、又需在现有 bulk create + Reservation SubBlock 上实现自动补机时,可用 GCE 原生日志事件搭建一套等价自愈:子块内主机故障 / 修复(包括实例未运行、空置时的物理故障)会在 Reservation SubBlock 维度产生系统级审计日志,监听该日志即可自动补机。
关键步骤:
- 监听 Cloud Audit
system_event两个 methodName(本项目实测存在):compute.reservations.subblock.unusedmachinerepair—— 闲置主机变 degraded、送修(对应 degraded count +1)。compute.reservations.subblock.unusedmachinerepaircomplete—— 主机修复归还、卡槽恢复可用(degraded count 归零)。
- 自愈架构:Cloud Logging(sink 按上述 methodName 过滤)→ Pub/Sub → Cloud Function;函数收到
unusedmachinerepaircomplete即发起gcloud compute instances bulk create ...(§2.3 命令),把刚修好的底层资源即时补回训练网络。 - 配套:实例挂起时先用自建脚本
delete异常 VM(§1.4 / §2.3),再由上述事件驱动补建,无需常驻轮询。
事件关键字段(生产 tencent-gcp-taiji 实测,供设计处理逻辑):
| 字段 | 值 / 用途 |
|---|---|
logName | projects/<P>/logs/cloudaudit.googleapis.com%2Fsystem_event(sink 从此日志取) |
protoPayload.methodName | …unusedmachinerepair(降级送修)/ …unusedmachinerepaircomplete(修复归还)——sink 过滤键 |
protoPayload.resourceName | 事件所在子块全路径 projects/…/reservations/<RES>/reservationBlocks/<BLOCK>/reservationSubBlocks/<SUBBLOCK>——直接喂给 bulk create --reservation=<全路径> 补机 |
resource.labels.location | zone(如 us-central1-b);resource.labels.method=ReservationSubBlockMaintenance |
protoPayload.status.message | 人读说明(如 "An unused machine in this subblock has been repaired and returned to service.") |
timestamp / severity | 事件时间 / INFO;authenticationInfo.principalEmail=system@google.com |
字段局限:protoPayload.metadata 为空 {},事件不含具体故障 host 的 ID,也不含 count 数值,仅到子块粒度。需确定该子块当前健康 / 空闲台数时,须再 describe 子块(§1.1)后决定补建数量。
参考:Cloud Logging → Pub/Sub sink · Pub/Sub 触发 Cloud Functions · bulk create CLI
5. 常用运维操作
- 查日志(Cloud Logging):
gcloud logging read 'resource.type=gce_instance AND resource.labels.instance_id=<ID>' \
--limit=100 --freshness=1h --format='value(timestamp,textPayload)'
- 串口输出(排查开不了机 / 无网络):
gcloud compute instances get-serial-port-output <VM> --zone=<ZONE> --port=1
# 交互式串口控制台:
gcloud compute connect-to-serial-port <VM> --zone=<ZONE>
建机时须带 --metadata=serial-port-enable=true。
- 热重启(保盘,不触发消毒,恢复设备状态首选):
gcloud compute instances reset <VM> --zone=<ZONE>(先sync)。 - 查健康 / 占用:见 §1.5 sub-block describe。
- 查即将到来的维护:
gcloud compute instances describe <VM> --format='value(upcomingMaintenance)'。
参考:串口控制台:启用并连接(概念 / UI) · get-serial-port-output CLI · connect-to-serial-port CLI · 重启实例(UI 操作) · Cloud Logging 查询(概念 / UI) · logging read CLI
6. 后续 debug 需授予我方的 IAM role
不需要 editor。分两档按需授予:
只读排查(零风险,建议默认给这四个):
| Role | 作用 |
|---|---|
roles/compute.viewer | 查看所有 Compute 资源(实例、reservation sub-block health、串口输出) |
roles/logging.viewer | 查看 Cloud Logging 日志 |
roles/iap.tunnelResourceAccessor | 经 IAP 隧道访问 VM(SSH/TCP 前置) |
roles/compute.osLogin | 经 OS Login 以普通用户 SSH 登录 |
需动手修时再加(仍远低于 editor):
| Role | 作用 |
|---|---|
roles/compute.instanceAdmin.v1 | 实例生命周期与配置:setMetadata / reset / start / stop / 读串口 / setServiceAccount;不含网络、防火墙、项目级配置 |
roles/iam.serviceAccountUser | 配合 setServiceAccount 使用(两者需同时具备才生效) |
roles/compute.osAdminLogin | 需 root/sudo 排查或 live-fix 时,替代 osLogin |
compute.instanceAdmin.v1是能改但不到 editor 的最小操作 role,单它即覆盖我方全部变更类操作。- 只读阶段用第一档即可,不需要 instanceAdmin。
参考:授予角色(Console 操作步骤) · 授予 / 变更 / 撤销访问(概念) · add-iam-policy-binding CLI · Compute IAM roles · IAP TCP 转发所需角色(操作) · IAP 访问管理(UI 操作) · OS Login:授予所需角色
附录
A. IMEX(NVL72 跨节点 GPU 内存互通)
IMEX(NVIDIA Internode Memory Exchange)是 NVL72 架构下 K8s 里跨节点组建 MNNVL/IMEX 网络的守护进程,让同一 NVLink domain 内多机 GPU 共享内存互通。已启用官方 GPU Operator DRA(computedomains.dra.nvidia.com)的集群由官方组件管理,不需额外部署;尚未启用的集群可由我方提供的容器化 DaemonSet 补充(检测到官方 DRA 时自动避让)。具体方案联系我方。
B. GB300 k8s 需额外装 asapd-lite DaemonSet
- 是什么:
asapd-lite,DaemonSet 部署,负责 GB300 RDMA 数据面初始化(网卡编址、静态网关邻居、PCC 拥塞控制、MTU)。 - 何时需要:单机 / 同 domain 内不需要(走 NVLink,不碰 RoCE);跨机多节点 IPv6-only RoCE 才需要。
- 排障线索:k8s 跨域 RoCE QP
INIT→RTR超时(errno 110),多为 asapd-lite 没把网关邻居装稳。GB200 不需要这套(IPv4,走 guest-agent 编址)。
C. gIB / NCCL 使用要点
- 镜像已内置(v18dot2 起):Google NCCL/gIB 烤进宿主机
/var/lib/gib(/usr/local/gib是兼容软链)。用户 Pod 不再需要 nccl-gib initContainer,可移除。 - 三步启用:① hostPath 挂宿主机
/var/lib/gib到容器/usr/local/gib(ro);② envLD_LIBRARY_PATH=/usr/local/gib/lib64:$LD_LIBRARY_PATH加NCCL_ENV_PLUGIN=gcp(平台按机型自动套 GB300 的nccl.a4xmax.conf/ GB200 的nccl.a4x.conf);③ RDMA 接入(/dev/infiniband加IPC_LOCK,或 CNI RDMA device plugin)。 - 路径注意:宿主机侧一律为
/var/lib/gib,容器内 mountPath 仍为/usr/local/gib。 - 成功标志:
NCCL_DEBUG=INFO出现NCCL INFO Using network gIB且走NET/IB ... mlx5;若见Using network Socket说明退化成 TCP,查LD_LIBRARY_PATH/ RDMA 权限。 - VM 上
docker run:-v /var/lib/gib:/usr/local/gib:ro -e LD_LIBRARY_PATH=/usr/local/gib/lib64 -e NCCL_ENV_PLUGIN=gcp --device /dev/infiniband --cap-add IPC_LOCK --network host --ipc host --gpus all。
D. XID 分级速查
| XID | 类别 | 处置 |
|---|---|---|
| 13, 31, 94, 95, 137 | 应用 / 软件类 | 不换机,应用侧修 |
| 48, 63, 64 | ECC / 行重映射 | nvidia-smi -r 或 reset 清状态可恢复;48 升级为 63/64 是恶化信号,留意 |
| 79 | GPU 掉总线(fallen off the bus) | 不可恢复,reset 无效,下架加报障 |
| 64(remap 耗尽)、140 | 行重映射失败 / 不可纠正 ECC | 不可恢复,下架加报障 |
参考:GCP XID handling · NVIDIA Xid Catalog(含 Applies to GB200 列)
E. 官方文档与 CLI 链接
每项尽量给“概念 / UI 操作”+“CLI 参数”两类,便于同时查界面做法与命令参数。
建机 / 预留 / placement:
- 概念 / UI:A4X Max 建机 · A4X Max 批量建机 · 批量创建概念 · placement policy · 预留总览 · bare metal 实例 · Local SSD:停机丢数据
- CLI:instances create · bulk create · resource-policies · group-placement policy · sub-blocks describe
维护 / 报障:
- 概念 / UI:A4X 维护事件处理(90/7 天) · 主机维护总览(紧急/突发维护) · GPU 主机维护(1 小时 + metadata) · 查看即将维护 · 主动触发维护 · metadata 值参考 · 报障步骤 · 故障主机 API 排障
- CLI:perform-maintenance · report-host-as-faulty · report-subblock-as-faulty
支持 / 开 case:
- 概念 / UI:创建 / 管理 case · case 优先级定义 · 描述问题最佳实践(六要素) · 目标响应时间(按 tier)
实例操作 / 日志 / 串口:
- 概念 / UI:重启实例 · 串口控制台:启用并连接 · Cloud Logging 查询
- CLI:instances reset · get-serial-port-output · connect-to-serial-port · logging read
自动化 / MIG:
- 概念 / UI:A4X Max MIG 创建 · Stateful MIG 总览 · 配置 stateful MIG · MIG autohealing
- CLI:instance-groups managed create · health-checks create tcp · managed update
NCCL / GPU:
- 概念 / UI:NCCL / gIB 安装 · 监控 GPU · GPU 故障排查 / XID · NVIDIA NCCL 安装指南 · NVIDIA Xid errors
IAM / 访问:
- 概念 / UI:授予角色(Console 步骤) · 授予 / 变更 / 撤销访问 · Compute IAM roles · IAP TCP 转发所需角色 · IAP 访问管理 · OS Login:授予所需角色
- CLI:add-iam-policy-binding · start-iap-tunnel · os-login ssh-keys add
F. 维护 / 中断处置参考实现
面向 §1.3(通知接收)与 §4.3(自建 k8s 自动处置),可参考的官方 / 半官方实现。
DaemonSet / 节点处置骨架:
- GoogleCloudPlatform/k8s-node-termination-handler(GCE 自建 k8s 可用的 DaemonSet;hanging GET 监听 metadata → cordon/evict) —— 已于 2023-03 归档、且只监听
maintenance-event(无法获取 1 小时提前量),仅作骨架参考,监听端点需自行升级为upcoming-maintenance。 - GKE:处理 GPU/TPU 中断(自动 cordon/drain + 宽限期 SIGTERM) —— GKE-only 闭源,自建 k8s 不能直接用,仅复刻其处置逻辑。
- Node Problem Detector(自定义 plugin 监听 metadata → 上报 NodeCondition;只上报不处置)
- Kubernetes Pod 终止(SIGTERM→grace→SIGKILL,terminationGracePeriodSeconds / preStop)
- Kubernetes Graceful Node Shutdown(关机优雅处理)
Checkpoint / 中断度量:
- nvidia-resiliency-ext(async/local checkpoint + in-process restart;NeMo/Megatron)
- NVIDIA Megatron Bridge Resiliency(SIGTERM 优雅退出前存 checkpoint + 异步 checkpoint)
- Orbax(JAX/MaxText 的 async / emergency checkpoint)
- Checkpoint Replicator / Multi-Tier Checkpointing(GoogleCloudPlatform,支持 NeMo GPU)
- ML Goodput Measurement(AI-Hypercomputer,量化中断/checkpoint 对训练效率影响)
官方未提供“仍在维护、原生支持 GCP 维护信号、面向自建 k8s”的现成 maintenance handler:
k8s-node-termination-handler已归档,GKE handler 是 GKE-only 闭源,aws-node-termination-handler(仍维护)仅支持 AWS metadata,medik8s/node-maintenance-operator 只做执行层不感知云信号。故 §4.3 提供一个极简 shell DaemonSet 自建实现(可运行版deploy/scripts/gce-maint-handler.{sh,yaml})。训练侧 SIGTERM 异步 checkpoint:NeMo/Megatron 用 nvidia-resiliency-ext,JAX 用 Orbax。
G. 客户初始化脚本全文
三套脚本全文见下,按机型 + 镜像选(强配对见 §1.2,勿交叉):
- G.1 GB200 v6.0(配 v19 镜像,厚脚本) —— 每台开机自己做分区 / sshd / 网卡改名 / lnet。本地权威副本
deploy/scripts/tlinux4-customer-init-universal.sh。 - G.2 GB300 v7.1(配 v22 镜像,瘦脚本) —— 网卡改名 / hugepages / sshd / 内核模块烤进镜像、由 systemd service 完成,脚本只“校验”+ 从 metadata 注入 Lustre 策略首启自动挂载。本地权威副本
deploy/tlinux4-customer-init-universal-v7dot1.sh。 - G.3 GB300 v7.0(配 v21 镜像,备选) —— v21/v22 为并行选项(非新旧);v7.0 仍由脚本改名(约 130s)。本地权威副本
deploy/tlinux4-customer-init-universal-v7dot0.sh。
G.1 GB200 v6.0(配 v19 镜像)
功能概述见 §1.2。
#!/bin/bash
# TLinux 4 (TencentOS Server 4.0) — Universal Startup Script (Customer) — v6.0
# Compatible with: A4X/GB200 (VM), A4X MAX/GB300 (Bare Metal)
#
# 一份通吃:自动探测适配 GB200(GVNIC / 4 RDMA)与 GB300(IDPF eth0/eth1 / 8 RDMA),
# 无需判镜像版本,同时兼容生产存量 v17 与 v18/v19 镜像。做四类事(不含 k8s):
# [2] 系统盘分区:p3=+20G 挂 /usr/local、p4=剩余挂 /data(xfs,nofail)
# [4] NUMA 对齐 2MB Hugepages(GB300/ASAPD 用) [6] sshd 加 Port 22 + 56000
# [1] 每 boot 末尾按拓扑自动把网卡改名 bond*:mgmt→bond0/bond1(带自愈看门狗——
# 改名后 metadata 不可达即自动 revert,裸金属无需关机、不触发消毒);全部 RDMA→bond2..N
# [5] lustre lnet 绑定 bond1(通用,无网段;PSA 路由/mount 交 mount-lustre.sh)
# [3] 本地 SSD RAID0 已按客户要求停用(改由客户自行初始化,保留为注释参考)
# 拆出:GPU 持久化/超时·MDS 防护·MRDMA host route → gb-gcp-hardening.sh / gb-host-rdma-route.sh。
set -euo pipefail
exec > >(tee /var/log/tlinux4-customer-init.log) 2>&1
INIT_STAMP=/etc/.customer-init-done
# --- v6.0 可调参数(有安全默认值,不填即与 v5.9 行为一致)-------------------
RDMA_WAIT_MAX="${RDMA_WAIT_MAX:-180}" # [1a] 等待 RDMA 注册的硬上限(秒)
echo "=== Disable SELinux ==="
setenforce 0 || true
if [ -f /etc/selinux/config ]; then
sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config || true
fi
###############################################################################
# ONE-TIME setup (disk / RAID / hugepages / sshd / host-route / modules).
# Gated by INIT_STAMP. Network is intentionally NOT touched here — NIC rename
# is deferred to the END of every boot (see bottom) so all prerequisites are
# in place and persisted before we risk the management interface.
###############################################################################
if [ ! -f "$INIT_STAMP" ]; then
echo "================================================================"
echo " TLinux 4 v6.0 — Startup Script (Universal Customer) — one-time setup"
echo " $(date)"
echo "================================================================"
#############################################################################
# [2] Boot disk partitioning: /usr/local (20G) + /data (remaining)
#############################################################################
echo "=== [2] Boot disk partitioning ==="
BOOT_DEV=$(findmnt -n -o SOURCE / | sed 's/p[0-9]*$//')
PARTITION_STAMP=/etc/.partitions-created
if [ ! -f "$PARTITION_STAMP" ]; then
echo "--- Creating boot disk partitions ---"
sgdisk -e "$BOOT_DEV" 2>/dev/null || true
sgdisk -n 3:0:+20G -t 3:8300 "$BOOT_DEV"
sgdisk -n 4:0:0 -t 4:8300 "$BOOT_DEV"
partprobe "$BOOT_DEV" 2>/dev/null || true
sleep 2
mkfs.xfs -f "${BOOT_DEV}p3"
mkfs.xfs -f "${BOOT_DEV}p4"
TMPMNT=$(mktemp -d)
mount "${BOOT_DEV}p3" "$TMPMNT"
cp -a /usr/local/. "$TMPMNT/" 2>/dev/null || true
umount "$TMPMNT"
rmdir "$TMPMNT"
mount "${BOOT_DEV}p3" /usr/local
mkdir -p /data
mount "${BOOT_DEV}p4" /data
P3_UUID=$(blkid -s UUID -o value "${BOOT_DEV}p3")
P4_UUID=$(blkid -s UUID -o value "${BOOT_DEV}p4")
if [ -n "$P3_UUID" ] && ! grep -q "$P3_UUID" /etc/fstab; then
echo "UUID=$P3_UUID /usr/local xfs defaults,nofail 0 2" >> /etc/fstab
fi
if [ -n "$P4_UUID" ] && ! grep -q "$P4_UUID" /etc/fstab; then
echo "UUID=$P4_UUID /data xfs defaults,nofail 0 2" >> /etc/fstab
fi
touch "$PARTITION_STAMP"
echo "Boot disk partitioned: p3=/usr/local(20G) p4=/data(remaining)"
fi
#############################################################################
# [3] Local SSD RAID0 setup —— 【已按客户要求停用,仅作参考,不实际执行】
#############################################################################
# 客户自行初始化本地 SSD(RAID/文件系统/挂载),故本段不再执行。
# 如需由 startup-script 接管,取消下方整段注释即可(4×2.9T 本地 SSD → RAID0
# → /mnt/stateful_partition;注意首启 mkfs.xfs 对 11.7T 阵列约需 ~88s)。
echo "=== [3] Local SSD RAID0 setup —— SKIPPED (customer-managed) ==="
# --- BEGIN reference (disabled) ------------------------------------------
# SSD_DEVICES=()
# for disk in /dev/nvme*n1; do
# [ -b "$disk" ] || continue
# PART_COUNT=$(lsblk -n -o NAME "$disk" 2>/dev/null | wc -l)
# if [ "$PART_COUNT" -le 1 ]; then
# SSD_DEVICES+=("$disk")
# echo " Detected local SSD: $disk ($(lsblk -n -d -o SIZE "$disk"))"
# fi
# done
#
# NUM_SSDS=${#SSD_DEVICES[@]}
# echo " Found $NUM_SSDS local SSD device(s)"
# if [ "$NUM_SSDS" -gt 0 ]; then
# MOUNT_POINT="/mnt/stateful_partition"
# mkdir -p "$MOUNT_POINT"
# if [ "$NUM_SSDS" -eq 1 ]; then
# TARGET_DEV="${SSD_DEVICES[0]}"
# mkfs.xfs -f "$TARGET_DEV"
# mount "$TARGET_DEV" "$MOUNT_POINT"
# DEV_UUID=$(blkid -s UUID -o value "$TARGET_DEV")
# if [ -n "$DEV_UUID" ] && ! grep -q "$DEV_UUID" /etc/fstab; then
# echo "UUID=$DEV_UUID $MOUNT_POINT xfs defaults,nofail 0 2" >> /etc/fstab
# fi
# else
# mdadm --stop /dev/md0 2>/dev/null || true
# mdadm --create /dev/md0 --level=0 --raid-devices="$NUM_SSDS" "${SSD_DEVICES[@]}" --force --run
# mkfs.xfs -f /dev/md0
# mount /dev/md0 "$MOUNT_POINT"
# mkdir -p /etc/mdadm
# mdadm --detail --scan >> /etc/mdadm/mdadm.conf
# DEV_UUID=$(blkid -s UUID -o value /dev/md0)
# if [ -n "$DEV_UUID" ] && ! grep -q "$DEV_UUID" /etc/fstab; then
# echo "UUID=$DEV_UUID $MOUNT_POINT xfs defaults,nofail 0 2" >> /etc/fstab
# fi
# fi
# mkdir -p "$MOUNT_POINT"/{gcsfuse-cache,scratch-data}
# echo "$MOUNT_POINT mounted (total: $(df -h "$MOUNT_POINT" | awk 'NR==2{print $2}'))"
# else
# echo "WARNING: No local SSD devices found"
# mkdir -p /mnt/stateful_partition
# fi
# --- END reference (disabled) --------------------------------------------
#############################################################################
# [4] Safe NUMA-aligned 2MB Hugepages allocation (for GB300/ASAPD)
#############################################################################
echo "=== [4] Safe Hugepages allocation ==="
for d in /sys/devices/system/node/node[0-9]*; do
if [ -d "$d/hugepages/hugepages-2048kB" ]; then
echo 4096 | tee "$d/hugepages/hugepages-2048kB/nr_hugepages"
fi
done
mkdir -p /dev/hugepages
mount -t hugetlbfs none /dev/hugepages 2>/dev/null || true
#############################################################################
# [6] sshd ports 22 + 56000
#############################################################################
echo "=== [6] sshd port 22 + 56000 ==="
SSHD_CHANGED=0
if ! grep -q '^Port 22' /etc/ssh/sshd_config; then
sed -i '1i Port 22' /etc/ssh/sshd_config
SSHD_CHANGED=1
fi
if ! grep -q '^Port 56000' /etc/ssh/sshd_config; then
sed -i '/^Port 22/a Port 56000' /etc/ssh/sshd_config
SSHD_CHANGED=1
fi
if grep -q '^AddressFamily inet6' /etc/ssh/sshd_config; then
sed -i 's/^AddressFamily inet6$/AddressFamily any/' /etc/ssh/sshd_config
SSHD_CHANGED=1
fi
if [ "$SSHD_CHANGED" -eq 1 ]; then
systemctl restart sshd
echo "sshd now listening on ports 22 and 56000 (AddressFamily set to any)"
else
echo "sshd ports 22 and 56000 already configured"
fi
# [7] Mellanox MRDMA host route —— 已抽出到 deploy/scripts/gb-host-rdma-route.sh
# (默认关,仅 host 直跑 NCCL 测试用;生产 TKE 由 pod/asapd-lite 负责,不需要)。
#############################################################################
# [6b] Load networking modules for Calico (VXLAN / IPIP)
#############################################################################
echo "=== [6b] Loading networking modules (Calico vxlan/ipip) ==="
modprobe vxlan || true
modprobe ipip || true
echo "vxlan" > /etc/modules-load.d/vxlan.conf
echo "ipip" > /etc/modules-load.d/ipip.conf
touch "$INIT_STAMP"
echo "=== One-time setup complete ==="
else
echo "One-time setup already completed. Proceeding to network rename."
fi
###############################################################################
# [1] Network interface rename (auto-detect) — EVERY BOOT, runs LAST.
# mgmt NICs → bond0/bond1 (with self-healing watchdog on the primary),
# all RDMA → bond2..bondN.
# set +e in this region: a stray failure must NOT abort before the
# watchdog/revert can run and keep the box reachable.
###############################################################################
set +e
###############################################################################
# [1a] 【v6.0 新增·A】等待 RDMA(mlx5_ib)注册完成,再进入下面的 gate。
#
# v17 镜像的 google-startup-scripts 在开机后 16.5–19.9 s 就跑到这里,而
# mlx5_ib 要到 ~19.5 s 才注册,导致 gate `rdma link show | grep -q .` 判空、
# 整个 [1] 段(含 mgmt 改名)被跳过。v18.1 在 125–141 s 才跑,天然赶得上。
# 本函数让脚本"等到 RDMA 就绪"——在 v18 上第一轮即命中、零开销;在 v17 上
# 等约 3 s。超时则原样放行,行为退化为 v5.9,不会更糟。
# gate 本身及其后的所有逻辑一行未改。
###############################################################################
wait_rdma_ready() {
local max="$RDMA_WAIT_MAX"
local expect=0 n=0 last=-1 stable=0 t=0 v
# 期望张数 = PCI 层枚举到的 Mellanox(vendor 0x15b3) function 数。
# PCI 枚举在开机 ~1 s 完成,远早于 mlx5_ib 注册(~19.5 s),脚本跑到时必已稳定。
for v in /sys/bus/pci/devices/*/vendor; do
[ -r "$v" ] || continue
[ "$(cat "$v" 2>/dev/null)" = "0x15b3" ] && expect=$((expect + 1))
done
while [ "$t" -lt "$max" ]; do
n=$(rdma link show 2>/dev/null | grep -c .)
# 命中期望张数 → 立刻返回(v18 走这条,t=0)
if [ "$expect" -gt 0 ] && [ "$n" -ge "$expect" ]; then
echo " [1a] RDMA 就绪: ${n}/${expect} 张 (PCI 期望 ${expect}),等待 ${t}s"
return 0
fi
# 本机没有 Mellanox 设备(CPU 机 / 非 RDMA 配置)→ 不空等
if [ "$expect" -eq 0 ] && [ "$n" -eq 0 ] && [ "$t" -ge 10 ]; then
echo " [1a] 未发现 Mellanox PCI 设备且 rdma link 为空,跳过等待"
return 1
fi
# 取不到 PCI 期望值,或掉卡永远凑不齐 → 数量连续 5 轮不变即视为就绪
if [ "$n" -gt 0 ] && [ "$n" -eq "$last" ]; then
stable=$((stable + 1))
if [ "$stable" -ge 5 ]; then
echo " [1a] RDMA 数量稳定于 ${n} 张 (PCI 期望 ${expect}),等待 ${t}s"
return 0
fi
else
stable=0
fi
last="$n"
sleep 1
t=$((t + 1))
done
echo " [1a] !! 等待 ${max}s 超时,当前 ${n} 张 (PCI 期望 ${expect}) —— 按现状继续"
return 1
}
echo "=== [1a] 等待 RDMA 注册就绪 (上限 ${RDMA_WAIT_MAX}s) ==="
wait_rdma_ready
if rdma link show 2>/dev/null | grep -q .; then
echo "=== [1] Network interface rename (auto-detect, deferred to end) ==="
# Remove legacy ifcfg files to prevent NetworkManager conflicts
rm -f /etc/sysconfig/network-scripts/ifcfg-eth* 2>/dev/null || true
BOND_IDX=0
PRIMARY_NIC=$(ip route show default 2>/dev/null | awk '{print $5}' | head -1)
# Health check: metadata server reachable ⇒ default route works
net_healthy() {
curl -sf -m 3 -H "Metadata-Flavor: Google" \
http://169.254.169.254/computeMetadata/v1/instance/id >/dev/null 2>&1
}
# Collect management NICs: has PCI device, not lo/bond*, not IB/RDMA, not USB.
# USB-bus NICs are the BMC/IPMI gadget (e.g. cdc_eem usb0 on some GB300 hosts);
# they are NOT real mgmt/data NICs. If counted, usb0 grabs bond2 and pushes the
# RDMA netdevs to bond3+ (off-by-one). Skip anything whose device bus is usb.
MGMT_NICS=()
for devpath in /sys/class/net/*/device; do
[ -e "$devpath" ] || continue
nic=$(basename "$(dirname "$devpath")")
[[ "$nic" == lo || "$nic" == bond* ]] && continue
[[ -d "/sys/class/net/$nic/device/infiniband" ]] && continue
bus=$(basename "$(readlink -f "/sys/class/net/$nic/device/subsystem" 2>/dev/null)" 2>/dev/null)
[[ "$bus" == "usb" ]] && continue
MGMT_NICS+=("$nic")
done
if [ ${#MGMT_NICS[@]} -gt 0 ]; then
# Order: primary (default-route) NIC → bond0, remaining by PCI addr.
ORDERED_MGMT=()
if [[ -n "$PRIMARY_NIC" ]] && ip link show "$PRIMARY_NIC" &>/dev/null; then
ORDERED_MGMT+=("$PRIMARY_NIC")
fi
while read -r nic; do
[[ -z "$nic" ]] && continue
[[ "$nic" == "$PRIMARY_NIC" ]] && continue
ORDERED_MGMT+=("$nic")
done < <(for n in "${MGMT_NICS[@]}"; do
[[ "$n" == "$PRIMARY_NIC" ]] && continue
pci=$(basename "$(readlink -f "/sys/class/net/$n/device")" 2>/dev/null || echo "zzzz")
echo "$pci $n"
done | sort | awk '{print $2}')
NM_DIR=/etc/NetworkManager/system-connections
RENAMED_PAIRS=() # "orig:new" pairs, for possible revert
for nic in "${ORDERED_MGMT[@]}"; do
newname="bond${BOND_IDX}"
if ip link show "$nic" &>/dev/null; then
# sync NM keyfile for EVERY renamed NIC BEFORE the rename
for nmf in "$NM_DIR"/*.nmconnection; do
[ -f "$nmf" ] || continue
if grep -q "^interface-name=${nic}$" "$nmf" 2>/dev/null; then
sed -i "s/^interface-name=${nic}$/interface-name=${newname}/" "$nmf"
echo " NM profile $(basename "$nmf"): interface-name ${nic} → ${newname}"
fi
done
ip link set dev "$nic" down
ip link set dev "$nic" name "$newname"
ip link set dev "$newname" up
RENAMED_PAIRS+=("${nic}:${newname}")
echo " $nic → $newname"
fi
BOND_IDX=$((BOND_IDX + 1))
done
nmcli connection reload 2>/dev/null || true
MGMT_COUNT=$BOND_IDX
# --- Self-healing watchdog: confirm network recovered, else REVERT ---
if [ ${#RENAMED_PAIRS[@]} -gt 0 ]; then
echo " Waiting for network to recover after mgmt rename (metadata probe)..."
healthy=0
for _try in $(seq 1 20); do
sleep 2
if net_healthy; then healthy=1; break; fi
nmcli device connect bond0 2>/dev/null || true
done
if [ "$healthy" -eq 1 ]; then
echo " Network healthy after rename (metadata reachable)."
# Persist mgmt names via udev (PCI slot → bondN) only on success
UDEV_RULE="/etc/udev/rules.d/70-a4x-bond-rename.rules"
if [ ! -f "$UDEV_RULE" ]; then
: > "$UDEV_RULE"
for bidx in $(seq 0 $((MGMT_COUNT - 1))); do
PCI=$(basename "$(readlink -f "/sys/class/net/bond${bidx}/device")" 2>/dev/null || true)
[ -n "$PCI" ] && echo "SUBSYSTEM==\"net\", ACTION==\"add\", KERNELS==\"$PCI\", NAME=\"bond${bidx}\"" >> "$UDEV_RULE"
done
echo " Persisted ${MGMT_COUNT} mgmt NIC names via udev."
fi
# First-boot nudge: 显式拉起 bond1,触发 50-lustre-psa-route dispatcher 补 /21 lustre 路由。
# 稳态 reboot 时 udev 已固化 bond1、keyfile 自动连,dispatcher 自然触发;首启因网卡改名
# 晚于 NM 首次 up、事件带旧名会漏加,故此处补一枪(dispatcher 由镜像烤入,读 metadata 网段)。
if ip link show bond1 &>/dev/null; then
nmcli connection up 10-bond1 2>/dev/null || nmcli device connect bond1 2>/dev/null || true
echo " fired bond1 up → 50-lustre-psa-route 补 lustre 路由(若 metadata 已设 lustre-peering-cidr)"
fi
else
echo " !!! Network DID NOT recover after mgmt rename — REVERTING to stay reachable !!!"
for pair in "${RENAMED_PAIRS[@]}"; do
orig="${pair%%:*}"; new="${pair##*:}"
for nmf in "$NM_DIR"/*.nmconnection; do
[ -f "$nmf" ] || continue
if grep -q "^interface-name=${new}$" "$nmf" 2>/dev/null; then
sed -i "s/^interface-name=${new}$/interface-name=${orig}/" "$nmf"
fi
done
if ip link show "$new" &>/dev/null; then
ip link set dev "$new" down 2>/dev/null || true
ip link set dev "$new" name "$orig" 2>/dev/null || true
ip link set dev "$orig" up 2>/dev/null || true
echo " reverted $new → $orig"
fi
done
nmcli connection reload 2>/dev/null || true
systemctl restart NetworkManager 2>/dev/null || true
MGMT_COUNT=0
echo " Revert done. mgmt NICs left at original names; investigate before retrying rename."
fi
fi
else
# mgmt already renamed by udev this boot. Count contiguous bond* that are real
# PCI mgmt NICs; stop at any usb-bus bond (stale BMC entry from an old udev rule)
# so RDMA numbering isn't pushed off-by-one.
while ip link show "bond${BOND_IDX}" &>/dev/null; do
bus=$(basename "$(readlink -f "/sys/class/net/bond${BOND_IDX}/device/subsystem" 2>/dev/null)" 2>/dev/null)
[[ "$bus" == "usb" ]] && { echo " WARN: bond${BOND_IDX} is a USB NIC (stale mgmt rename); not counting as mgmt"; break; }
BOND_IDX=$((BOND_IDX + 1))
done
[ $BOND_IDX -gt 0 ] && echo " Management NICs already renamed (bond0-bond$((BOND_IDX - 1)))"
MGMT_COUNT=$BOND_IDX
fi
# RDMA rename — rename the RDMA *netdev* (gpu*rdma* → bondN); leave the ibdev
# (mlx5_*) UNCHANGED. Customer-confirmed rule:
# gpu0rdma0→bond2, gpu1rdma0→bond3, ... ; ibdev mlx5_0..N stay as-is.
# NOTE for customer: this renames the RDMA *netdev*. Any component that keys on
# the netdev name (e.g. dranet / k8s device plugin) must be configured to
# accept bond*; the ibdev name (mlx5_*) is intentionally preserved per the
# requirement. If dranet must see gpu*rdma*, do NOT enable this rename.
# Re-applied every boot (NOT udev-persisted, unlike mgmt): a netdev rename
# carries no SSH / default route so it is safe to defer to here; on GB300 the
# dual-port CX-8 can put two netdevs behind one PCI slot, which would make a
# PCI-keyed udev NAME= rule collide — so we simply re-apply on each boot.
RDMA_NETDEVS=()
for devpath in /sys/class/net/*/device; do
[ -e "$devpath" ] || continue
nic=$(basename "$(dirname "$devpath")")
[[ "$nic" == bond* ]] && continue
[[ -d "/sys/class/net/$nic/device/infiniband" ]] || continue # RDMA netdev only
RDMA_NETDEVS+=("$nic")
done
# sort by name so gpu0rdma0 < gpu1rdma0 < ... → bond2, bond3, ...
IFS=$'\n' RDMA_NETDEVS=($(printf '%s\n' "${RDMA_NETDEVS[@]}" | sort)); unset IFS
for nic in "${RDMA_NETDEVS[@]}"; do
newname="bond${BOND_IDX}"
ip link show "$nic" &>/dev/null || continue
ip link set dev "$nic" down 2>/dev/null || true
if ip link set dev "$nic" name "$newname" 2>/dev/null; then
ip link set dev "$newname" up 2>/dev/null || true
echo " $nic → $newname (netdev; ibdev unchanged)"
BOND_IDX=$((BOND_IDX + 1))
else
ip link set dev "$nic" up 2>/dev/null || true
echo " WARN: failed to rename RDMA netdev $nic → $newname"
fi
done
RDMA_COUNT=$((BOND_IDX - MGMT_COUNT))
echo " --- Result: ${MGMT_COUNT} mgmt + ${RDMA_COUNT} RDMA = ${BOND_IDX} total ---"
ip -br link show type ether 2>/dev/null || true
rdma link show 2>/dev/null || true
fi
set -e
###############################################################################
# [5] Lustre storage network routing (needs bond1; runs AFTER rename)
###############################################################################
echo "=== [5] Lustre lnet 绑定 bond1(通用,无网段)==="
# lustre 一律走 bond1(MTU 8896 的 VPC 端口),永不走 bond0。startup 只做与环境
# 无关的通用准备:把 lnet 绑到 bond1。
# 【环境相关的部分——PSA 静态路由 + mount + 路由持久化——全部交给推送脚本
# deploy/scripts/mount-lustre.sh(env 驱动:LUSTRE_MGS_NID/LUSTRE_PEERING_CIDR/
# LUSTRE_MOUNT_POINT,无默认值)。原因:GB200 与 GB300 用不同 lustre 实例、不同
# VPC、不同 PSA 网段,但共用这一份 startup;任何网段/挂载点写进 startup 都会导致
# "网段一变就要改 startup"。故 startup 不含任何 lustre 环境参数。】
# 注:旧版曾在此清理遗留的 172.16.0.0/24 via 10.201.0.1 路由与 99-lustre-route
# dispatcher(来自更早的 startup);实测 v18dot1 镜像已无这些残留,故删除该清理。
if ip link show bond1 &>/dev/null; then
echo 'options lnet networks="tcp(bond1)"' > /etc/modprobe.d/lustre.conf
echo " lnet networks=tcp(bond1) 已设;PSA 路由与 mount 由 mount-lustre.sh 处理。"
else
echo "bond1 not found, skipping Lustre lnet config."
fi
# [7]/[8]/[9] 已从本脚本移出(见 v5.9 changelog):
# - [8] GPU 持久化+超时、[9] MDS 防护 → deploy/scripts/gb-gcp-hardening.sh
# (装一次即持久;存量车队 SSH 下发一次,并作为 v18 镜像烘焙清单)。
# - [7] MRDMA host route → deploy/scripts/gb-host-rdma-route.sh(host NCCL 测试用)。
echo "=== Customer Initialization Complete (v6.0 merged; [1a] absorbed, [1b] dropped; hardening split out) ==="
G.2 GB300 v7.1(配 v22 镜像)
功能概述见 §1.2。本地权威副本 deploy/tlinux4-customer-init-universal-v7dot1.sh。
#!/bin/bash
# TLinux 4 (TencentOS Server 4.0) — Universal Startup Script (Customer) — v7.1
#
###############################################################################
# ⚠️ 2026-08-09 【原地修订,版本号仍为 v7.1】(经确认不出 v7.2/v7.3,避免动
# v22 镜像版本戳里的 requires_customer_init 字段与 README 配对表)
#
# 改动仅一处:[5] 段在 daemon-reload 之后补 `systemctl start <挂载点>.automount`。
# 原因:daemon-reload 只让 generator【生成】 mount/automount 单元,不会启动它们,
# 于是首启后 lustre 挂不上、要等下次重启才自愈(v6dot2 起就有此缺陷)。
# 详见 [5] 段内注释。其余各段与修订前逐字节相同。
###############################################################################
#
###############################################################################
# ⚠️ 为什么跳到 v7.0 而不是 v6.2:仓库里【已经存在】另一份
# `scripts/tlinux4-customer-init-universal-v6.2.sh`(2026-08-04,把 [4] hugepages
# 改成每 boot 的 systemd service)。两条 v6.1 谱系并行演进、各带对方没有的修复:
# scripts/v6.2 → [4] hugepages 每 boot service(重启后不归零)
# build-scripts/v6dot1 → [2] 分区失败只记账、不打死整脚本
# 我最初从 build-scripts/v6dot1 分支,漏了前者 —— graceivy 首次重启后 hugepages=0
# 就是这么来的。v7.0 合并两边并加上 lustre 策略注入,终结这个分裂。
#
# v7.1 = v7.0 − [1] 网卡改名(改为只校验)。其余与 v7.0 逐字节相同。
# 配套 **v22 镜像**(76- udev 规则已在镜像里命名)。
# v7.0 = scripts/v6.2([4] hugepages service)
# + build-scripts/v6dot1([2] 分区容量前检 / 失败只记账)
# + [5] lustre 策略注入 + 显式 restart lustre-lnet.service(本版新增)
###############################################################################
#
###############################################################################
# v6.2 changelog(相对 v6.1)—— 配套 **v21 镜像**(tlinux-gb300-ipv6-dual-50gb-v21)
#
# 唯一改动:[5] 段整体重写。其余各段与 v6.1 逐字节相同(含 [1] 网卡改名)。
#
# [删除] 不再写 /etc/modprobe.d/lustre.conf。两个理由,都在真机上出过事:
# · 时序:本段在 boot +112~124s 执行,而 fstab 的 _netdev 挂载在 +6~10s 就可能
# 触发 modprobe lustre —— 那时 conf 还没写,lnet 拿不到 networks= 就永久失败。
# (2026-08-06 taiji `gb300-central-d0007-w16` 实测)
# · 覆写:`>` 会抹掉同文件里的 lnet_numa_range / ksocklnd 调优行。
# ⇒ 这件事已交给 v21 镜像里的 lustre-lnet.service + lustre-lnet-up.sh,
# 它在 bond1 的 .device 单元就绪后执行,且只替换 networks= 那一行。
#
# [新增] [5] 改为【只注入策略】:从 GCE metadata 读 lustre-mgs-nid /
# lustre-mountpoint / lustre-peering-cidr / lustre-nic,写
# /etc/sysconfig/lustre-client 与 fstab 行(带
# x-systemd.requires=lustre-lnet.service + x-systemd.automount)。
# MGS 或挂载点缺任一 ⇒ 本机不挂 lustre,什么都不写。
#
# ⚠️ 依赖:本版**必须配 v21 及以后的镜像**。在 v19/v20dot1 镜像上跑会写出一条
# 指向不存在的 lustre-lnet.service 的 fstab 行 —— 挂载会失败(Requires 不满足)。
# 老镜像请继续用 v6.1。
###############################################################################
#
# ⚠️ 本文件是 tlinux4-customer-init-universal-v6dot1.sh 的【副本 + 增量】,
# v6.1 与原 v6.0 文件均保持不动。
# v6.1 曾只改一次性段的失败处理,不改任何业务逻辑。
# 合并版基线(我方 + 前线共同迭代):= v5.9 + 前线 universal_v1 的 [1a] wait_rdma_ready
# (兼容生产存量 v17 机器);前线 [1b](RDMA udev 固化)按用户决策未纳入,守决策 #2。
# Compatible with: A4X/GB200 (VM), A4X MAX/GB300 (Bare Metal), H100, CPU
# 同时通吃 v17 与 v18/v18.1 镜像 —— 无论哪个镜像,开机后网卡名都正确。
#
# 一份通吃:自动探测适配 GB200(GVNIC/4 RDMA)与 GB300(IDPF eth0/eth1/8 RDMA)。
# 命名:管理网卡按序 → bond0/bond1;全部 RDMA(rdma dev 全遍历,4 或 8 张)→ bond2..bondN。
#
# v5.6 changelog(相对 v5.5):
# 1. [安全] 网卡改名整体挪到脚本【最后】,在磁盘/RAID/sshd 等前置全部完成并持久化之后才动网络。
# 2. [安全] mgmt(承载默认路由的网卡)改名带【自愈看门狗】:改名后轮询 GCP 元数据服务器可达性,
# 失败则自动 revert(还原网卡名 + NM profile),机器退回「可达但未改名」——裸金属无需关机、
# 不触发消毒。因此可直接在 GB300(IDPF)真机验证 mgmt 改名。
# 3. [顺序] [5] Lustre 路由依赖 bond1,移动到改名之后执行。
# 4. 承接 v5.5:NM profile 对每个改名网卡同步;RDMA rdma dev 全遍历(GB300 8 张全覆盖);
# [7] host route 默认关(仅 metadata enable-rdma-host-route=true 才配),且用 env 传 JSON。
#
# v5.7 changelog(相对 v5.6):
# 5. [客户要求] [3] 本地 SSD RAID0 段【停用】,仅保留为注释参考;本地 SSD 由客户自行初始化。
#
# v5.8 changelog(相对 v5.7):
# 6. [修复] RDMA 改名改的是 *netdev*(gpu*rdma*→bond2..N),ibdev(mlx5_*)保持不动
# (客户确认规则;旧版 v5.3/v5.7 用 `rdma dev set` 改的是 ibdev,方向反了)。
# netdev 改名不承载 SSH,每 boot 重放、不做 udev(避 CX-8 双口单 PCI 的 NAME= 冲突)。
# 7. [新增] [8] GPU 持久化(enable nvidia-persistenced)+ google-shutdown-scripts /
# nvidia-persistenced 的 TimeoutStopSec drop-in(20s/15s),避免关机卡 stop job。
# 8. [新增] [9] GCP MDS 防护:装 /usr/local/sbin/gcp-mds-protect.sh +
# kubelet.service.d/zz-gcp-mds-protect.conf drop-in,在客户 iptables.sh 之后
# 重压 169.254.169.254 RETURN(治 w3 病根,durable,不碰客户 iptables.sh);
# 并在当前 boot 立即 assert 一次。
#
# v5.9 changelog(相对 v5.8)—— 架构拆分,本脚本回归「客户镜像初始化」本职:
# 9. [拆出] [8] GPU 持久化+超时、[9] MDS 防护 → 移到独立加固包
# deploy/scripts/gb-gcp-hardening.sh(装一次即持久的 systemd 产物,由 rollout
# SSH 下发一次即可,且是 v18 镜像的烘焙清单)。本脚本不再含这两段。
# 10. [拆出] [7] MRDMA host route(默认关,仅 host 直跑 NCCL 测试用)→ 独立脚本
# deploy/scripts/gb-host-rdma-route.sh,测试者按需手动运行。
# 11. [重构] [5] Lustre:startup 只保留通用的 `lnet networks="tcp(bond1)"`(无网段)。
# 环境相关的 PSA 静态路由 + mount + 路由持久化 → 全部移到推送脚本
# deploy/scripts/mount-lustre.sh(env 驱动、无默认值),因 GB200/GB300 用不同
# lustre/VPC/PSA 但共用本 startup。同时删除旧的死代码清理(172.16.0.0/24 via
# 10.201.0.1 + 99-lustre-route dispatcher)——实测 v18dot1 镜像已无这些残留。
# 本脚本现仅含:一次性(磁盘/sshd/hugepages/Calico模块)+ 每boot netdev 改名 + lustre lnet conf。
#
###############################################################################
# v6.0 changelog(我方合并版,基于前线 universal_v1,相对 v5.9)
# —— 让 [1] 段在【生产存量 v17 镜像的机器】上也能生效,同时守住决策 #2。
#
# [吸收] 前线 universal_v1 的 [1a] wait_rdma_ready()(见 12);
# [去除] 前线 universal_v1 的 [1b] RDMA udev 固化(见 13,按用户决策不引入)。
#
# 12. [修复·A / 已吸收] 新增 wait_rdma_ready(),在 [1] 段的 gate
# `if rdma link show 2>/dev/null | grep -q .` 之前调用。gate 本身不动。
# 这是让本脚本【兼容生产存量 v17 机器】的关键修复。
#
# ── 为什么需要 ──
# v17 与 v18 镜像上 [1] 段的代码完全相同,差异只在【它跑得多早】:
#
# 镜像 google-startup-scripts 启动时刻 mlx5_ib 注册时刻 gate 判定
# v17 开机后 16.5 – 19.9 s ~19.5 s 多数判空 → 整段跳过
# v18.1 开机后 125 – 141 s ~19.5 s 恒真 → 正常执行
#
# v17 抢在 IB 注册之前跑到 gate,`rdma link show` 输出为空 → 整个 [1] 段
# (含 mgmt 改名)被跳过。实测 172 台 v17 中 141 台(82%)如此;剩下 31 台
# 恰好 start 在 19.0–19.9 s 赶上了 IB 注册,所以"看起来是好的"。
# 这不是代码问题,是时序问题,因此修法是【等】而不是【改逻辑】。
#
# ── 为什么可以一份脚本通吃、不需要判镜像版本 ──
# "等待"在已经就绪的环境里自动退化为零成本:v18 跑到这里时 8 张 IB 早已注册,
# 第一轮轮询即命中并立刻返回,不增加任何开机时间。v17 则等约 3 s。
#
# ── 安全性 ──
# * 硬上限超时(RDMA_WAIT_MAX,默认 180 s),超时即放行、绝不阻塞开机;
# 超时后 gate 判空 → 行为与 v5.9 完全一致(安全降级,不会更糟)。
# * 判据不是"有 ≥1 张就过",而是与 PCI 层枚举到的 Mellanox function 数比对,
# 避免只注册了 3 张就往下跑、剩下 5 张漏改名。
# * PCI 期望数取不到时(非 Mellanox RDMA / 未来新卡)退回"数量连续 5 轮不变"。
# * 本机根本没有 Mellanox 设备(CPU 机 / H100 非 RDMA 配置):10 s 后即放弃等待。
# * 掉卡机(实到数永远凑不齐期望数):靠"稳定 5 轮"退出,约 6 s。
#
# 13. [新增·B / 已去除] 前线 universal_v1 曾含 [1b]:把 RDMA netdev 名固化到 udev
# (PCI 地址 → NAME=bondN),作为 [1a] 超时的兜底。经用户决策【不吸收】:
# * [1a] 已从根上修好"v17 改名不生效"的时序竞争,[1b] 边际价值≈0;
# * udev 映射一旦固化,后续开机只会盲目套用、不再校验;裸金属 GB300 拓扑
# 变化(换卡 / 掉卡 / 换 host)时可能把网卡命错 —— 这正是要主动规避的后续风险。
# 故守回决策 #2「RDMA netdev 每 boot 现场改名、不落 udev」,本脚本不含 [1b] 段,
# 也不含 PERSIST_RDMA_UDEV 参数。首启 /21 lustre 路由改用 [1] 段末尾的显式
# `nmcli connection up 10-bond1` nudge 触发 dispatcher(见该处注释)。
###############################################################################
# v6.1 changelog(相对 v6.0)—— 只动「一次性段的失败处理」,业务逻辑零改动。
#
# 起因(2026-08-06,真机 hzchen-v20dd-gb300-0019,50GB boot disk):
# [2] 段 `sgdisk -n 3:0:+20G` 在盘放不下时返回 4,而脚本顶部 set -euo pipefail
# 把【整个 startup script】打死在这一行:
# Could not create partition 3 from 104855552 to 146798591
# Script "startup-script" failed with error: exit status 4
# 后果是 [4] hugepages、[6] sshd、[6b] Calico 模块、以及最关键的 [1] 网卡改名
# (bond0..bondN)全部不执行 —— 机器表面 RUNNING / SSH 通 / GPU 在,实际:
# 没有任何 bond*、HugePages_Total=0、/usr/local 还在 root 分区上,外部看不出坏了。
# 且 v6.0 失败时不落任何 stamp → 每次开机重试、每次都死在同一行。
#
# 14. [修复] [2] 增加【容量前检】:先算 GPT 尾部可用扇区,不够 (USRLOCAL_GB+MIN_DATA_GB)
# 就明确 SKIP 并打印需要多大的盘,不再让 sgdisk 去撞墙。
# 15. [修复] [2] 失败(含容量不足)只记账不终止;容量不足另落 /etc/.partitions-skipped,
# 避免每 boot 无效重试。
# ⚠️ 重跑要删【两个】标记:`rm -f /etc/.partitions-skipped /etc/.customer-init-done`
# —— [2] 整体在 INIT_STAMP 门内,只删 .partitions-skipped 不会有任何效果。
# 16. [加固] [4] hugepages 由 `echo | tee`(pipefail 下写失败即打死脚本)改为逐 NUMA 节点
# 写入 + 读回校验(请求 4096 实到多少要看得见),失败只记账。
# 19. [修正 16 的误报,2026-08-06 richivy 真机] 只对 **MemTotal>0** 的 NUMA 节点分配。
# GB300 实测 34 个 node 里只有 6 个有常规内存(node0/1/2/10/18/26),其余 28 个是
# GPU/HBM 侧节点,写 nr_hugepages 恒读回 0 —— 那不是失败,是本来就分不了。
# 不排除的话每台机都会误报「28 个节点未达标」。实际结果 6×4096=24576(48GiB),
# 与车队已知良好值一致。
# ⚠️ 汇总看 `/sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages`,**不要**看
# /proc/meminfo 的 HugePages_Total —— 后者只统计【默认大页尺寸】那个池,
# 本机 Hugepagesize=524288kB(512MB),2M 池不在里面,拿它判恒为 0。
# 17. [加固] [6] `systemctl restart sshd` 失败不再终止脚本,改为记账 + 打印 `sshd -t`。
# 18. [新增] 失败流水 /etc/.customer-init-failures —— 给巡检一个可 grep 的信号;
# 「脚本跑完了」不等于「每段都成功」,这个文件是二者的区分依据。
#
# ⚠️ 未改动:[1] 网卡改名段(它本来就在 `set +e` 区域内,自带 mgmt 自愈看门狗)。
# ⚠️ 建机要求(镜像本身 50GB):--boot-disk-size 必须 > 50 + USRLOCAL_GB + MIN_DATA_GB;
# 生产建议 ≥200GB。盘不放大时本脚本会跳过分区并继续,不会再连累其它段。
###############################################################################
#
# 真机验证(GB300 #3, hzchen-v17-gb300-startup-val-3, subblock-0004, 2026-07-27):
# 改名放最后 + mgmt 自愈看门狗全绿 —— eth0→bond0/eth1→bond1(两 NM profile 均同步)、
# Network healthy 无需 revert、mlx5_0..7→bond2..bond9(8 张全改)、default route on bond0(DHCP)、
# SSH 22 可达、IMEX disabled、4× GB300 GPU。即「从 idpf 到 rdma 连号 bond0..bond9」达成。
#
# 镜像已内置: NVIDIA driver, GVE/IDPF, IMEX, GDRCopy, nvidia-persistenced,
# SELinux/firewalld disabled, memlock unlimited, sudoers, SSH。
set -euo pipefail
exec > >(tee /var/log/tlinux4-customer-init.log) 2>&1
INIT_STAMP=/etc/.customer-init-done
# --- v6.0 可调参数(有安全默认值,不填即与 v5.9 行为一致)-------------------
RDMA_WAIT_MAX="${RDMA_WAIT_MAX:-180}" # [1a] 等待 RDMA 注册的硬上限(秒)
# --- v6.1 可调参数 ---------------------------------------------------------
USRLOCAL_GB="${USRLOCAL_GB:-20}" # [2] p3 = /usr/local 大小(GiB)
MIN_DATA_GB="${MIN_DATA_GB:-10}" # [2] p4 = /data 的最小可接受大小(GiB)
FAIL_LEDGER=/etc/.customer-init-failures # 各段失败流水,给巡检一个可 grep 的信号
# v6.1:一次性段里任何一段失败,都不该带走后面的段 —— 尤其不该带走 [1] 网卡改名
# (那是让机器有 bond0..bondN 的唯一途径)。失败记账 + 继续跑,而不是 set -e 直接死。
warn_section() { # $1=段名 $2=返回码
echo "!!! WARN: $1 未完成(rc=$2)—— 继续执行后续段,不终止脚本"
echo "$(date -Is) section=$1 rc=$2" >> "$FAIL_LEDGER" 2>/dev/null || true
}
echo "=== Disable SELinux ==="
setenforce 0 || true
if [ -f /etc/selinux/config ]; then
sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config || true
fi
###############################################################################
# ONE-TIME setup (disk / RAID / hugepages / sshd / host-route / modules).
# Gated by INIT_STAMP. Network is intentionally NOT touched here — NIC rename
# is deferred to the END of every boot (see bottom) so all prerequisites are
# in place and persisted before we risk the management interface.
###############################################################################
if [ ! -f "$INIT_STAMP" ]; then
echo "================================================================"
echo " TLinux 4 v6.1 — Startup Script (Universal Customer) — one-time setup"
echo " $(date)"
echo "================================================================"
#############################################################################
# [2] Boot disk partitioning: /usr/local (20G) + /data (remaining)
# v6.1: 容量前检 + 失败不终止整脚本 + 失败落状态文件(见文件头 v6.1 changelog 14/15)
#############################################################################
echo "=== [2] Boot disk partitioning ==="
BOOT_DEV=$(findmnt -n -o SOURCE / | sed 's/p[0-9]*$//')
PARTITION_STAMP=/etc/.partitions-created
PARTITION_SKIP_STAMP=/etc/.partitions-skipped
# 注意:本函数【不依赖 set -e】。实测 bash 在 `if ( set -e; ... )` / `... || rc=$?`
# 这两种上下文里都会把 -e 抑制掉(连子 shell 内部一起抑制),所以每一步必须显式判返回值,
# 否则「分区失败」会被静默当成成功。
do_partition() {
local sect last_usable last_end free_sect need_sect free_mib need_gib
local usrlocal_gb="${USRLOCAL_GB:-20}" min_data_gb="${MIN_DATA_GB:-10}"
command -v sgdisk >/dev/null || { echo " ERROR: 无 sgdisk"; return 1; }
# 备份 GPT 挪到盘尾,last-usable-sector 才是真值(盘被放大时尤其必要)
sgdisk -e "$BOOT_DEV" >/dev/null 2>&1 || true
sect=$(blockdev --getss "$BOOT_DEV" 2>/dev/null || echo 512)
last_usable=$(sgdisk -p "$BOOT_DEV" 2>/dev/null | sed -n 's/.*last usable sector is \([0-9]\+\).*/\1/p' | head -1)
last_end=$(sgdisk -p "$BOOT_DEV" 2>/dev/null | awk '$1 ~ /^[0-9]+$/ {print $3}' | sort -n | tail -1)
if [ -z "$last_usable" ] || [ -z "$last_end" ]; then
echo " ERROR: 读不出 GPT 布局(last_usable=[$last_usable] last_end=[$last_end])"; return 1
fi
free_sect=$(( last_usable - last_end ))
need_sect=$(( (usrlocal_gb + min_data_gb) * 1024 * 1024 * 1024 / sect ))
free_mib=$(( free_sect * sect / 1024 / 1024 ))
need_gib=$(( usrlocal_gb + min_data_gb ))
# ── 容量前检 ──
# 这是 v6.1 的主要修复点。v6.0 直接 `sgdisk -n 3:0:+20G`,盘不够大时 sgdisk 返回 4,
# 而脚本顶部的 set -euo pipefail 会把【整个 startup script】打死 —— 后面的 hugepages /
# sshd / Calico 模块 / 以及最关键的 [1] 网卡改名(bond0..bondN)全都不执行。
# 实测:hzchen-v20dd-gb300-0019(50GB boot disk)每次开机都死在这一行,
# 机器表面 RUNNING、SSH 通、GPU 在,但没有任何 bond*、HugePages_Total=0,外部看不出坏了。
if [ "$free_sect" -lt "$need_sect" ]; then
echo " SKIP: boot disk 可用尾部空间仅 ${free_mib} MiB,需要 ≥ ${need_gib} GiB"
echo " (p3=/usr/local ${usrlocal_gb}G + p4=/data 至少 ${min_data_gb}G)"
echo " → 建机时 --boot-disk-size 要大于镜像本身(50GB)+ ${need_gib}GB;生产建议 ≥200GB。"
echo " → /usr/local 与 /data 保持在 root 分区上,不影响开机与后续各段。"
return 2 # 2 = 容量不足(可预期),与 3 = 真的出错 区分开
fi
echo " 容量检查通过:尾部可用 ${free_mib} MiB ≥ 需要 ${need_gib} GiB"
echo "--- Creating boot disk partitions ---"
sgdisk -n "3:0:+${usrlocal_gb}G" -t 3:8300 "$BOOT_DEV" || { echo " ERROR: 创建 p3 失败"; return 3; }
sgdisk -n 4:0:0 -t 4:8300 "$BOOT_DEV" || { echo " ERROR: 创建 p4 失败"; return 3; }
partprobe "$BOOT_DEV" 2>/dev/null || true
sleep 2
mkfs.xfs -f "${BOOT_DEV}p3" || { echo " ERROR: mkfs p3 失败"; return 3; }
mkfs.xfs -f "${BOOT_DEV}p4" || { echo " ERROR: mkfs p4 失败"; return 3; }
local tmpmnt; tmpmnt=$(mktemp -d)
mount "${BOOT_DEV}p3" "$tmpmnt" || { echo " ERROR: 临时挂载 p3 失败"; rmdir "$tmpmnt"; return 3; }
cp -a /usr/local/. "$tmpmnt/" 2>/dev/null || true
umount "$tmpmnt" || { echo " ERROR: 卸载临时挂载点失败"; return 3; }
rmdir "$tmpmnt"
mount "${BOOT_DEV}p3" /usr/local || { echo " ERROR: 挂载 /usr/local 失败"; return 3; }
mkdir -p /data
mount "${BOOT_DEV}p4" /data || { echo " ERROR: 挂载 /data 失败"; return 3; }
local p3_uuid p4_uuid
p3_uuid=$(blkid -s UUID -o value "${BOOT_DEV}p3")
p4_uuid=$(blkid -s UUID -o value "${BOOT_DEV}p4")
if [ -n "$p3_uuid" ] && ! grep -q "$p3_uuid" /etc/fstab; then
echo "UUID=$p3_uuid /usr/local xfs defaults,nofail 0 2" >> /etc/fstab
fi
if [ -n "$p4_uuid" ] && ! grep -q "$p4_uuid" /etc/fstab; then
echo "UUID=$p4_uuid /data xfs defaults,nofail 0 2" >> /etc/fstab
fi
echo "Boot disk partitioned: p3=/usr/local(${usrlocal_gb}G) p4=/data(remaining)"
return 0
}
if [ -f "$PARTITION_STAMP" ]; then
echo " 已分区过($PARTITION_STAMP 存在),跳过"
elif [ -f "$PARTITION_SKIP_STAMP" ]; then
# 落 skip 标记的意义:v6.0 失败时不 touch 任何 stamp,于是【每次开机都重试、每次都死】。
# 盘的大小不会自己变大,重试没有意义,只会每 boot 都把后面的段一起带走。
# ⚠️ 重跑要删【两个】标记:本段整体在 INIT_STAMP 门内(见上面的 if),
# 只删 .partitions-skipped 不会有任何效果 —— 首启完成后一次性段根本不再进入。
echo " 上次因容量不足跳过($PARTITION_SKIP_STAMP),不再重试。"
echo " 放大盘后重跑分区:rm -f $PARTITION_SKIP_STAMP $INIT_STAMP && reboot"
echo " (会连带重跑整个一次性段;各段幂等,重复执行安全)"
cat "$PARTITION_SKIP_STAMP" 2>/dev/null || true
else
# ⚠️ 必须写成 `PART_RC=0; do_partition || PART_RC=$?`。
# 写成 `do_partition; PART_RC=$?` 会被 set -e 在函数返回非 0 的瞬间直接打死脚本
# (实测 exit=2,`PART_RC=$?` 那行根本执行不到)—— 那就等于把本次要修的 bug 原样重写一遍。
PART_RC=0; do_partition || PART_RC=$?
case "$PART_RC" in
0) touch "$PARTITION_STAMP" ;;
2) { echo "skipped=capacity date=$(date -Is) boot_dev=$BOOT_DEV"; } > "$PARTITION_SKIP_STAMP"
warn_section "[2] 分区(容量不足,已跳过)" 2 ;;
*) warn_section "[2] 分区" "$PART_RC" ;;
esac
fi
#############################################################################
# [3] Local SSD RAID0 setup —— 【已按客户要求停用,仅作参考,不实际执行】
#############################################################################
# 客户自行初始化本地 SSD(RAID/文件系统/挂载),故本段不再执行。
# 如需由 startup-script 接管,取消下方整段注释即可(4×2.9T 本地 SSD → RAID0
# → /mnt/stateful_partition;注意首启 mkfs.xfs 对 11.7T 阵列约需 ~88s)。
echo "=== [3] Local SSD RAID0 setup —— SKIPPED (customer-managed) ==="
# --- BEGIN reference (disabled) ------------------------------------------
# SSD_DEVICES=()
# for disk in /dev/nvme*n1; do
# [ -b "$disk" ] || continue
# PART_COUNT=$(lsblk -n -o NAME "$disk" 2>/dev/null | wc -l)
# if [ "$PART_COUNT" -le 1 ]; then
# SSD_DEVICES+=("$disk")
# echo " Detected local SSD: $disk ($(lsblk -n -d -o SIZE "$disk"))"
# fi
# done
#
# NUM_SSDS=${#SSD_DEVICES[@]}
# echo " Found $NUM_SSDS local SSD device(s)"
# if [ "$NUM_SSDS" -gt 0 ]; then
# MOUNT_POINT="/mnt/stateful_partition"
# mkdir -p "$MOUNT_POINT"
# if [ "$NUM_SSDS" -eq 1 ]; then
# TARGET_DEV="${SSD_DEVICES[0]}"
# mkfs.xfs -f "$TARGET_DEV"
# mount "$TARGET_DEV" "$MOUNT_POINT"
# DEV_UUID=$(blkid -s UUID -o value "$TARGET_DEV")
# if [ -n "$DEV_UUID" ] && ! grep -q "$DEV_UUID" /etc/fstab; then
# echo "UUID=$DEV_UUID $MOUNT_POINT xfs defaults,nofail 0 2" >> /etc/fstab
# fi
# else
# mdadm --stop /dev/md0 2>/dev/null || true
# mdadm --create /dev/md0 --level=0 --raid-devices="$NUM_SSDS" "${SSD_DEVICES[@]}" --force --run
# mkfs.xfs -f /dev/md0
# mount /dev/md0 "$MOUNT_POINT"
# mkdir -p /etc/mdadm
# mdadm --detail --scan >> /etc/mdadm/mdadm.conf
# DEV_UUID=$(blkid -s UUID -o value /dev/md0)
# if [ -n "$DEV_UUID" ] && ! grep -q "$DEV_UUID" /etc/fstab; then
# echo "UUID=$DEV_UUID $MOUNT_POINT xfs defaults,nofail 0 2" >> /etc/fstab
# fi
# fi
# mkdir -p "$MOUNT_POINT"/{gcsfuse-cache,scratch-data}
# echo "$MOUNT_POINT mounted (total: $(df -h "$MOUNT_POINT" | awk 'NR==2{print $2}'))"
# else
# echo "WARNING: No local SSD devices found"
# mkdir -p /mnt/stateful_partition
# fi
# --- END reference (disabled) --------------------------------------------
#############################################################################
touch "$INIT_STAMP"
echo "=== One-time setup complete ==="
else
echo "One-time setup already completed. Proceeding to network rename."
fi
###############################################################################
# [1] Network interface rename (auto-detect) — EVERY BOOT, runs LAST.
# mgmt NICs → bond0/bond1 (with self-healing watchdog on the primary),
# all RDMA → bond2..bondN.
# set +e in this region: a stray failure must NOT abort before the
# watchdog/revert can run and keep the box reachable.
###############################################################################
set +e
###############################################################################
# [1a] 【v6.0 新增·A】等待 RDMA(mlx5_ib)注册完成,再进入下面的 gate。
#
# v17 镜像的 google-startup-scripts 在开机后 16.5–19.9 s 就跑到这里,而
# mlx5_ib 要到 ~19.5 s 才注册,导致 gate `rdma link show | grep -q .` 判空、
# 整个 [1] 段(含 mgmt 改名)被跳过。v18.1 在 125–141 s 才跑,天然赶得上。
# 本函数让脚本"等到 RDMA 就绪"——在 v18 上第一轮即命中、零开销;在 v17 上
# 等约 3 s。超时则原样放行,行为退化为 v5.9,不会更糟。
# gate 本身及其后的所有逻辑一行未改。
###############################################################################
wait_rdma_ready() {
local max="$RDMA_WAIT_MAX"
local expect=0 n=0 last=-1 stable=0 t=0 v
# 期望张数 = PCI 层枚举到的 Mellanox(vendor 0x15b3) function 数。
# PCI 枚举在开机 ~1 s 完成,远早于 mlx5_ib 注册(~19.5 s),脚本跑到时必已稳定。
for v in /sys/bus/pci/devices/*/vendor; do
[ -r "$v" ] || continue
[ "$(cat "$v" 2>/dev/null)" = "0x15b3" ] && expect=$((expect + 1))
done
while [ "$t" -lt "$max" ]; do
n=$(rdma link show 2>/dev/null | grep -c .)
# 命中期望张数 → 立刻返回(v18 走这条,t=0)
if [ "$expect" -gt 0 ] && [ "$n" -ge "$expect" ]; then
echo " [1a] RDMA 就绪: ${n}/${expect} 张 (PCI 期望 ${expect}),等待 ${t}s"
return 0
fi
# 本机没有 Mellanox 设备(CPU 机 / 非 RDMA 配置)→ 不空等
if [ "$expect" -eq 0 ] && [ "$n" -eq 0 ] && [ "$t" -ge 10 ]; then
echo " [1a] 未发现 Mellanox PCI 设备且 rdma link 为空,跳过等待"
return 1
fi
# 取不到 PCI 期望值,或掉卡永远凑不齐 → 数量连续 5 轮不变即视为就绪
if [ "$n" -gt 0 ] && [ "$n" -eq "$last" ]; then
stable=$((stable + 1))
if [ "$stable" -ge 5 ]; then
echo " [1a] RDMA 数量稳定于 ${n} 张 (PCI 期望 ${expect}),等待 ${t}s"
return 0
fi
else
stable=0
fi
last="$n"
sleep 1
t=$((t + 1))
done
echo " [1a] !! 等待 ${max}s 超时,当前 ${n} 张 (PCI 期望 ${expect}) —— 按现状继续"
return 1
}
echo "=== [1a] 等待 RDMA 注册就绪 (上限 ${RDMA_WAIT_MAX}s) ==="
wait_rdma_ready
# ── v7.1:此处原为 [1] 网卡改名,已删除 ────────────────────────────────────
# v22 镜像用 /etc/udev/rules.d/76-gb300-nic-name.rules 在 udev add 阶段(~10-31s)
# 按 PCI function 命名,不再需要 startup script 改名。本段改为【只校验不动作】。
#
# 为什么连兜底改名都不留:v22 的目的就是验证「udev 命名能否独立成立」。留兜底就分不清
# 是 udev 成功还是兜底救了它 —— 判据必须能区分这两种情况。真要兜底应加在镜像里
# (有 systemd 依赖可用),而不是塞回 startup script。
# 校验失败【不终止脚本】,只把事实打进日志;报警由镜像里的 gb300-nic-verify.service 负责。
echo "=== [1] 网卡命名校验(v7.1:不改名,仅校验)==="
BONDS=$(ls /sys/class/net 2>/dev/null | grep -cE '^bond[0-9]+$')
GCENAMES=$(ls /sys/class/net 2>/dev/null | grep -cE '^(eth[0-9]+|gpu[0-9]+rdma[0-9]+)$')
echo " bond* 网卡数=$BONDS (期望 10) 残留 GCE 名(eth*/gpu*rdma*)=$GCENAMES (期望 0)"
ip -br link show 2>/dev/null | awk '$1 ~ /^(bond|eth|gpu)/ {printf " %-12s %s\n", $1, $2}'
if [ "$BONDS" -eq 10 ] && [ "$GCENAMES" -eq 0 ]; then
echo " OK udev 命名生效,10 张全部为 bond0-bond9"
else
echo " !! WARN 命名与期望不符 —— 镜像里的 76-gb300-nic-name.rules 可能未生效。"
echo " 后果:10-bond2..9 的 NM keyfile 匹配不上 → RDMA 链路 DOWN;lustre 也起不来。"
echo " 诊断:systemctl status gb300-nic-verify.service。⚠️ 【不要】用 udevadm test —— 它会真的改名。"
fi
DEFDEV=$(ip route show default 2>/dev/null | awk '{print $5; exit}')
echo " 默认路由在 ${DEFDEV:-<无>} (期望 bond0)"
set -e
###############################################################################
# [5] Lustre —— 【v6.2 重写】只注入策略,不碰 lnet 配置也不碰模块
###############################################################################
# ── 为什么 v6.1 的写法要改掉 ────────────────────────────────────────────────
# v6.1 这里做的是:
# echo 'options lnet networks="tcp(bond1)"' > /etc/modprobe.d/lustre.conf
# 两个问题,都在真机上出过事:
#
# 1. 【时序】写 conf 与 modprobe 必须原子发生。本段在 boot 的 +112~124s 才执行
# (google-startup-scripts 起得晚),而 fstab 的 _netdev 挂载在 +6~10s 就可能
# 触发 mount.lustre → modprobe lustre。那一刻 conf 还没写,lnet 拿不到
# networks=,退回自动枚举只看到 down 的 tunl0:
# LNetError: lnet: Can't find any usable interfaces, rc = -ENOENT
# 并回滚且【永不重试】;更糟的是 lnet 模块残留但无 NID,此后任何
# mount/modprobe 都返回 -22,必须 lustre_rmmod 才能恢复。
# (2026-08-06 在 taiji `gb300-central-d0007-w16` 实测,时间戳逐条对上。)
#
# 2. 【整文件覆写】`>` 会抹掉同文件里的调优行。车队机器上实际存在:
# options lnet networks="tcp(bond1)" lnet_numa_range=0
# options ksocklnd nscheds=16 peer_credits=32
# 覆写后 lnet_numa_range 与整个 ksocklnd 调优静默消失。
#
# ⇒ v21 镜像把「写 conf + modprobe + 校验 NID」合并进 /usr/local/sbin/lustre-lnet-up.sh,
# 由 lustre-lnet.service 在 bond1 的 .device 单元就绪后执行(声明式依赖,非轮询),
# 并且只替换 networks= 那一行、保留其它 options。
# 本段因此【不再碰 lustre.conf】,只负责注入本机的环境参数。
#
# ── 策略从 GCE metadata 读,镜像里零环境耦合 ─────────────────────────────────
# lustre-mgs-nid e.g. 44.10.26.7@tcp:/lustrefs
# lustre-mountpoint e.g. /apdcephfs_wzaz
# lustre-peering-cidr e.g. 44.10.24.0/21 (可选,给 50-lustre-psa-route 用)
# lustre-nic 默认 bond1 (可选)
# MGS 或挂载点缺任一 ⇒ 本机不挂 lustre,什么都不写(干净的开关)。
###############################################################################
echo "=== [5] Lustre 策略注入(v6.2:不再写 lustre.conf)==="
md_attr() { # $1=属性名;取不到返回空。
# 必须带 -f —— 不带时 404 会把 HTML 错误页当正文返回(实测 1614 字节),
# 使「未设就什么都不做」的保护恒真失效。
# 必须带 `|| true` —— curl -sf 在 404 时返回 22,而【赋值语句的退出码就是命令替换的
# 退出码】,此处 set -e 生效,`L_CIDR=$(md_attr ...)` 会直接打死整个 startup script。
# 2026-08-08 首次真机验证就栽在这:只注了 mgs-nid/mountpoint、没注 peering-cidr
# (本来就不需要,MGS 与 bond1 同 /21),结果脚本死在 [5] 段第三行。
# 同类坑:v6.1 里的 `do_partition; PART_RC=$?`。
curl -sf -m 3 -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/attributes/$1" 2>/dev/null || true
}
L_MGS=$(md_attr lustre-mgs-nid)
L_MP=$(md_attr lustre-mountpoint)
L_CIDR=$(md_attr lustre-peering-cidr)
L_NIC=$(md_attr lustre-nic); L_NIC="${L_NIC:-bond1}"
if [ -z "$L_MGS" ] || [ -z "$L_MP" ]; then
echo " metadata 未设 lustre-mgs-nid / lustre-mountpoint ⇒ 本机不挂 lustre,跳过"
echo " (镜像里的 lustre-lnet.service 会因 /etc/sysconfig/lustre-client 无挂载点而自行跳过,不加载任何模块)"
else
# 格式校验:纵深防御。metadata 返回了奇怪的东西时绝不往 fstab 里写。
case "$L_MGS" in
*@tcp:/*) ;;
*) echo " !! lustre-mgs-nid 格式不对(期望 <ip>@tcp:/<fsname>),跳过: $L_MGS"; L_MGS="" ;;
esac
case "$L_MP" in
/*) ;;
*) echo " !! lustre-mountpoint 不是绝对路径,跳过: $L_MP"; L_MGS="" ;;
esac
fi
if [ -n "$L_MGS" ] && [ -n "$L_MP" ]; then
echo " MGS=$L_MGS 挂载点=$L_MP 网卡=$L_NIC PSA网段=${L_CIDR:-<未设>}"
mkdir -p /etc/sysconfig "$L_MP"
{
echo "# 由 customer-init v6.2 于 $(date -Is) 从 GCE metadata 注入"
echo "LUSTRE_NIC=$L_NIC"
echo "LUSTRE_MOUNTPOINT=$L_MP"
[ -n "$L_CIDR" ] && echo "LUSTRE_PEERING_CIDR=$L_CIDR"
} > /etc/sysconfig/lustre-client
echo " 已写 /etc/sysconfig/lustre-client"
# fstab 行:挂载被钉在 lustre-lnet.service 之后(systemd 依赖,不是靠时间)
# x-systemd.requires= → 生成 Requires= + After=
# x-systemd.automount → 首次访问才挂,访问被 autofs 阻塞而不是失败
# device-timeout → 等 bond1 的 .device 单元的上限
FSTAB_OPTS="nofail,_netdev,x-systemd.requires=lustre-lnet.service,x-systemd.automount,x-systemd.mount-timeout=300,x-systemd.device-timeout=300"
FSTAB_LINE="$L_MGS $L_MP lustre $FSTAB_OPTS 0 0"
if grep -qE "^[^#]*[[:space:]]${L_MP}[[:space:]]+lustre[[:space:]]" /etc/fstab 2>/dev/null; then
CUR_LINE=$(grep -E "^[^#]*[[:space:]]${L_MP}[[:space:]]+lustre[[:space:]]" /etc/fstab | head -1)
if [ "$CUR_LINE" != "$FSTAB_LINE" ]; then
cp -a /etc/fstab "/etc/fstab.bak.customer-init.$(date +%Y%m%d-%H%M%S)"
# 用 awk 重写而不是 sed —— MGS NID 里有 @ 和 /,做 sed 替换串要转义,容易出错
awk -v mp="$L_MP" -v line="$FSTAB_LINE" \
'($2==mp && $3=="lustre"){print line; next} {print}' /etc/fstab > /etc/fstab.new \
&& [ -s /etc/fstab.new ] && mv /etc/fstab.new /etc/fstab
echo " 已更新 fstab 行(旧行已备份)"
else
echo " fstab 行已正确"
fi
else
echo "$FSTAB_LINE" >> /etc/fstab
echo " 已追加 fstab 行"
fi
systemctl daemon-reload 2>/dev/null || true
grep -n lustre /etc/fstab | sed 's/^/ /'
# ★ 必须显式让机制层重新评估 —— 这是【策略写在机制之后】的必然要求。
# 实测(2026-08-08 graceivy 首启):NM dispatcher 在 bond1 up 时(+131s)就触发了
# lustre-lnet.service,而本段要到 +137s 才写出 /etc/sysconfig/lustre-client。
# 机制层那时看到"未配 LUSTRE_MOUNTPOINT"就干净跳过,并因 RemainAfterExit=yes 标记成
# active —— 此后没有任何事件会再触发它,LNet 永远没有 NID,挂载必失败。
# 差的只有 5 秒,但这不是偶发竞态:dispatcher 由网卡就绪驱动,本段固定在 startup 末尾。
systemctl restart lustre-lnet.service 2>&1 | sed 's/^/ /' || true
sleep 2
NIDS=$(lctl list_nids 2>/dev/null | grep -v '^0@lo$' | tr '\n' ' ' || true)
if [ -n "$NIDS" ]; then
echo " LNet 已就绪: $NIDS"
else
echo " !! WARN LNet 仍无 NID —— 查 journalctl -u lustre-lnet.service"
fi
# ★ 2026-08-09 原地补:daemon-reload 只【生成】 mnt-xxx.{mount,automount} 单元,
# 【不会启动它们】。少这一步 automount 恒为 inactive dead(journal 里一条记录都没有),
# findmnt 查不到,要等【下一次 boot】由 local-fs.target 拉起才生效。
# 2026-08-08 在 graceivy-w1 / regalivy-w1 实测到该状态,两台重启后即自愈 ——
# 即「首启挂不上、重启才好」这个现象的真正原因,不是 LNet 也不是 fstab 写错。
#
# 位置在 restart lustre-lnet 之后:fstab 里有 x-systemd.requires=lustre-lnet.service,
# automount 依赖它,必须先起 LNet。
#
# 【只 start,不主动访问挂载点】:automount 是惰性的,start 完机制即就绪,
# 首次访问时自动挂。在 startup script 里主动 ls 会阻塞到真正挂完,
# 最坏等到 x-systemd.mount-timeout=300 秒,不值得拖慢开机。
AM_UNIT="$(systemd-escape -p --suffix=automount "$L_MP" 2>/dev/null || true)"
if [ -n "$AM_UNIT" ]; then
systemctl start "$AM_UNIT" 2>&1 | sed 's/^/ /' || true
echo " automount 单元 $AM_UNIT = $(systemctl is-active "$AM_UNIT" 2>/dev/null)"
else
echo " !! WARN 无法推导 automount 单元名(systemd-escape 不可用?)"
fi
fi
# [7]/[8]/[9] 已从本脚本移出(见 v5.9 changelog):
# - [8] GPU 持久化+超时、[9] MDS 防护 → deploy/scripts/gb-gcp-hardening.sh
# (装一次即持久;存量车队 SSH 下发一次,并作为 v18 镜像烘焙清单)。
# - [7] MRDMA host route → deploy/scripts/gb-host-rdma-route.sh(host NCCL 测试用)。
###############################################################################
# 开机校验区 —— 【2026-08-08 从一次性 gate 移出,改为每 boot 执行】
#
# 这三段(原 [4] / [6] / [6b])此前在 `if [ ! -f $INIT_STAMP ]` 内,只在首启跑一次。
# 移出的理由:首启校验只能发现【镜像配错】,发现不了【运行时退化】——
# 而 hugepages 恰恰是最容易退化的一项(生产 taiji 那批就是重启后归零,
# 见 2026-08-08 只读排查:service 因 /usr/local 挂载竞态 203/EXEC,重启即 0)。
#
# 三段都【只读】:不写任何配置、不装任何东西。缺失时 warn_section 记入
# /etc/.customer-init-failures 并继续,不终止脚本。
#
# ⚠️ 时序:本区在 startup script 末尾执行(约 boot +130s 之后)。
# configure-numa-hugepages.service 内部最多等 120s(等 GPU 显存 NUMA node 上线),
# 正常情况下此时已完成。若打印的页数偏低而 service 仍在 activating,不是故障 ——
# 以 systemctl 状态为准,或稍后重查。
###############################################################################
#############################################################################
# [4] 2MB Hugepages —— 【2026-08-08 起改为只校验,安装已烤入镜像】
#
# 安装动作搬到了 v21/v22 构建脚本的 [7e] 段(configure-numa-hugepages.sh +
# 同名 unit + 旧名 gb300-hugepages.sh 的 symlink)。本段不再安装,只核实镜像里有、
# 且 enabled、且旧名 symlink 有效。
#
# ⚠️ 本段同时是【新脚本配旧镜像】的错配检测器:配 2026-08-08 之前构建的 v21/v22
# (未烤入 [7e])会在这里报 MISSING —— 那种组合下 hugepages 恒 0,
# kubelet capacity=0 → asapd-lite 恒 Pending → 节点拿不到 GUA,而机器表面完全正常。
#
# 给存量机器补装用 scripts/install-hugepages-service.sh(运行时写文件 = 单副本,
# 没有镜像烤入那份的双副本保护 —— 理由见构建脚本 [7e] 段注释)。
#
# ↓↓↓ 原安装逻辑整段保留为注释:它是镜像里那份的【对照基准】,改镜像时要比对 ↓↓↓
#############################################################################
echo "=== [4] Hugepages 校验(安装已烤入镜像,本段不安装)==="
HP_UNIT=/etc/systemd/system/configure-numa-hugepages.service
HP_SH=/usr/local/sbin/configure-numa-hugepages.sh
if [ -f "$HP_UNIT" ] && [ -x "$HP_SH" ]; then
echo " OK 镜像已烤入 configure-numa-hugepages.service + configure-numa-hugepages.sh"
echo " enabled=$(systemctl is-enabled configure-numa-hugepages.service 2>&1) active=$(systemctl is-active configure-numa-hugepages.service 2>&1)"
# 旧名必须解析到真身。两边 unit 同名而 ExecStart 可能写不同文件名,谁后写谁生效 ——
# symlink 是防 203/EXEC 的那道保险,缺了不报错但会在别人推 unit 时静默归零。
if [ "$(readlink -f /usr/local/sbin/gb300-hugepages.sh 2>/dev/null)" = "$HP_SH" ]; then
echo " 旧名 symlink OK (gb300-hugepages.sh → configure-numa-hugepages.sh)"
else
echo " !! 旧名 symlink 缺失或指向别处 —— 若有人推同名 unit 会 203/EXEC"
warn_section "[4] hugepages 旧名 symlink" 1
fi
# 期望 8192 = 2 个【CPU】NUMA x 4096。GPU 显存 NUMA(node2/10/18/26)应为 0:
# 那 32 GiB 实测无人使用(used=0 / asapd-lite maps 无 hugetlbfs),白占每卡 8 GiB。
cat /sys/devices/system/node/node*/hugepages/hugepages-2048kB/nr_hugepages 2>/dev/null \
| awk '{s+=$1} END{print " 当前 2M 页总数="s+0" (期望 8192 = 2 CPU NUMA x 4096)"}' || true
else
echo " !! MISSING 镜像里没有 hugepages service"
echo " 本脚本(2026-08-08 起)必须配同日或之后【重建】的 v21/v22 镜像。"
echo " 后果:hugepages 恒 0 → kubelet capacity=0 → asapd-lite 恒 Pending、无 GUA。"
echo " 补救:sudo bash scripts/install-hugepages-service.sh"
warn_section "[4] hugepages(镜像未烤入 [7e])" 1
fi
# # [4] 2MB Hugepages —— 安装 systemd service(v6.2 改;分配动作交给它每 boot 执行)
# # 这里只做「安装 + enable + 首次 start」,属一次性动作,故仍在 one-time gate 内。
# # 为什么不能像 v6.1 那样直接写 nr_hugepages:见本文件 v6.2 changelog 第 15 条。
# # 2026-08-10 起脚本名统一为 configure-numa-hugepages.sh(与 unit 同名、与客户
# # 生产一致),旧名 gb300-hugepages.sh 留 symlink;分配范围改为只给 CPU NUMA。
# #############################################################################
# echo "=== [4] Hugepages: 安装 configure-numa-hugepages.service ==="
#
# cat >/usr/local/sbin/configure-numa-hugepages.sh <<'HPEOF'
# #!/bin/bash
# # 给每个【有 CPU 的】NUMA node 分配 2MB hugepages;GPU 显存 NUMA 显式清零。
# # 每 boot 由 configure-numa-hugepages.service 调用。
# #
# # GB300 上 34 个 NUMA node 里只有 6 个有内存:node0/node1 是 CPU 内存(各约 480 GB),
# # 另外 4 个各约 283 GB 是 GPU 显存(coherent memory),要等 nvidia 驱动加载后才上线。
# #
# # 2026-08-08 起【只给 CPU NUMA 分配】:GPU 显存上那 32 GiB 实测无人使用
# # (used=0 / Rsvd=0 / asapd-lite maps 无 hugetlbfs),而 8 张 CX-8 全挂在 CPU NUMA。
# # kubelet 未配 topologyManager ⇒ capacity 按全节点总和算,2×4096×2MiB=16 GiB
# # 仍是 asapd-lite 需求(8 GiB)的两倍。
# #
# # ⚠️ 仍然要等 NUMA 拓扑稳定:GPU node 上线晚,不等的话【无法把它们显式清零】
# # (在线改配置的场景下它们可能还留着上一版的 4096)。
# # ⚠️ GPU NUMA 用【显式写 0】而不是 continue 跳过 —— 跳过的话存量分配不会被回收。
# # ⚠️ 判 CPU NUMA 必须用 `[ -n "$(cat cpulist)" ]`,不能用 `[ -s cpulist ]`:
# # sysfs 该文件 size 恒为 65536,与内容无关,用 -s 筛等于没筛。
# set -u
# PAGES="${HUGEPAGES_PER_NODE:-4096}"
# MAX="${HUGEPAGES_WAIT_MAX:-120}"
#
# mem_node_count() {
# local c=0 d m
# for d in /sys/devices/system/node/node[0-9]*; do
# [ -r "$d/meminfo" ] || continue
# m=$(awk '/MemTotal/{print $4; exit}' "$d/meminfo" 2>/dev/null)
# [ "${m:-0}" -gt 0 ] 2>/dev/null && c=$((c+1))
# done
# echo "$c"
# }
#
# prev=-1; stable=0; t=0; n=0
# while [ "$t" -lt "$MAX" ]; do
# n=$(mem_node_count)
# if [ "$n" = "$prev" ] && [ "$n" -gt 0 ]; then
# stable=$((stable+1)); [ "$stable" -ge 3 ] && break
# else
# stable=0
# fi
# prev="$n"; sleep 2; t=$((t+2))
# done
# echo "有内存的 NUMA node: ${n} 个(等待 ${t}s,上限 ${MAX}s)"
#
# ok=0; bad=0; zeroed=0
# for d in /sys/devices/system/node/node[0-9]*; do
# f="$d/hugepages/hugepages-2048kB/nr_hugepages"
# [ -w "$f" ] || continue
# m=$(awk '/MemTotal/{print $4; exit}' "$d/meminfo" 2>/dev/null)
# [ "${m:-0}" -gt 0 ] 2>/dev/null || continue
# if [ -n "$(cat "$d/cpulist" 2>/dev/null)" ]; then want="$PAGES"; else want=0; fi
# cur=$(cat "$f" 2>/dev/null)
# [ "${cur:-0}" = "$want" ] || echo "$want" >"$f" 2>/dev/null
# # 内核对 nr_hugepages 是【尽力分配】:写入不报错,但实得可能少于请求,必须回读校验
# got=$(cat "$f" 2>/dev/null)
# if [ "${got:-0}" = "$want" ]; then
# if [ "$want" = "0" ]; then zeroed=$((zeroed+1)); else ok=$((ok+1)); fi
# else
# bad=$((bad+1)); echo " WARN $(basename "$d"): 请求 ${want} 实得 ${got:-0}"
# fi
# done
# total=$(cat /sys/devices/system/node/node*/hugepages/hugepages-2048kB/nr_hugepages 2>/dev/null | paste -sd+ - | bc)
# echo "结果:CPU NUMA ${ok} 个足额、GPU NUMA ${zeroed} 个已清零、${bad} 个不符,总计 ${total:-0} 页 ≈ $(( ${total:-0} * 2 / 1024 )) GiB"
#
# mkdir -p /dev/hugepages
# mountpoint -q /dev/hugepages || mount -t hugetlbfs none /dev/hugepages 2>/dev/null
# exit 0
# HPEOF
# chmod +x /usr/local/sbin/configure-numa-hugepages.sh
# ln -sfn /usr/local/sbin/configure-numa-hugepages.sh /usr/local/sbin/gb300-hugepages.sh
#
# cat >/etc/systemd/system/configure-numa-hugepages.service <<'UNITEOF'
# [Unit]
# Description=GB300 2MB hugepages allocation (per NUMA node)
# Documentation=file:///usr/local/sbin/configure-numa-hugepages.sh
# # GPU 显存作为 NUMA node 上线依赖 nvidia 驱动;脚本内部还会再轮询等待。
# After=local-fs.target nvidia-persistenced.service
# Wants=nvidia-persistenced.service
# # kubelet 只在启动时读一次 hugepages capacity 并上报。晚于它分配的话节点 capacity
# # 仍是 0,请求 hugepages 的 pod(如 asapd-lite limits.hugepages-2Mi=8Gi)照样调度不上。
# Before=kubelet.service containerd.service
#
# [Service]
# Type=oneshot
# RemainAfterExit=yes
# ExecStart=/usr/local/sbin/configure-numa-hugepages.sh
#
# [Install]
# WantedBy=multi-user.target
# UNITEOF
#
# systemctl daemon-reload
# systemctl enable configure-numa-hugepages.service >/dev/null 2>&1
# systemctl start configure-numa-hugepages.service || true
# echo " configure-numa-hugepages.service 已安装并启动:"
# systemctl is-enabled configure-numa-hugepages.service 2>/dev/null | sed 's/^/ enabled=/'
# cat /sys/devices/system/node/node*/hugepages/hugepages-2048kB/nr_hugepages 2>/dev/null \
# | paste -sd+ - | bc | sed 's/^/ 总页数=/'
#############################################################################
# [6] sshd 端口 —— 【2026-08-08 起改为只校验,不写任何配置】
#
# ⚠️ 2026-08-08 实测更正(mintivy-v21 / regalivy-v22 两台交叉验证):
# 镜像里的 /etc/ssh/sshd_config.d/00-gb-dualstack.conf 是【死文件】——
# TencentOS 的 /etc/ssh/sshd_config 【没有 Include 指令】(两台实测
# `grep -ci '^[[:space:]]*Include'` 均为 0),该 drop-in 从未被任何 daemon 读过。
#
# 22 / 56000 实际由【两个独立 daemon】提供:
# sshd.service 无 -f,读主文件 → 22(主文件无 Port 行时用 OpenSSH 默认 22)
# sshd-56000.service -f /etc/ssh/sshd_config.l → 56000
#
# ⇒ 本段往主文件插 Port 行在功能上确实【冗余】(端口本来就有 daemon 提供),
# 但此前注释里「因为 drop-in 已烤入所以冗余」这个【归因是错的】,已更正。
#
# ⚠️ 判据不能用 `sshd -T`:它只解析主文件(无 Include),【结构上永远看不到 56000】,
# 拿它判会恒假 —— 每 boot 往 FAIL_LEDGER 写一条假失败,淹没真信号。
# 改判「谁在监听」+「能否握手」,这两条与配置文件长什么样无关。
#
# ↓↓↓ 原写入逻辑整段保留为注释 ↓↓↓
#############################################################################
echo "=== [6] sshd 端口校验(由镜像内多个 sshd daemon 提供,本段不改配置)==="
SSHD_MISS=0
# 判据一:谁在监听。`:22[[:space:]]` 精确到端口,避免 5622 之类误匹配。
SSHD_LISTEN=$(ss -lntpH 2>/dev/null | grep sshd || true)
for p in 22 56000; do
if printf '%s\n' "$SSHD_LISTEN" | grep -qE ":${p}[[:space:]]"; then
echo " OK sshd 在监听 $p"
else
echo " !! MISSING 没有 sshd 在监听 $p"
SSHD_MISS=$((SSHD_MISS + 1))
fi
done
# 判据二:能否握手。banner 仅 ~21 字节,必须 `head -1` —— 用 `head -c N` 会等够 N 字节而阻塞。
for p in 22 56000; do
B=$(timeout 5 bash -c "exec 3<>/dev/tcp/127.0.0.1/$p && head -1 <&3" 2>/dev/null | tr -d '\r' || true)
case "$B" in
SSH-*) echo " OK $p 握手正常: $B" ;;
*) echo " !! $p 握手失败: ${B:-<无响应>}"; SSHD_MISS=$((SSHD_MISS + 1)) ;;
esac
done
echo " sshd 进程: $(pgrep -c sshd 2>/dev/null || echo 0) 个; units: $(systemctl list-units --type=service --no-legend 2>/dev/null | grep -ci ssh || echo 0)"
[ "$SSHD_MISS" -eq 0 ] || warn_section "[6] sshd 端口" "$SSHD_MISS"
# #############################################################################
# # [6] sshd ports 22 + 56000
# #############################################################################
# echo "=== [6] sshd port 22 + 56000 ==="
# SSHD_CHANGED=0
# if ! grep -q '^Port 22' /etc/ssh/sshd_config; then
# sed -i '1i Port 22' /etc/ssh/sshd_config
# SSHD_CHANGED=1
# fi
# if ! grep -q '^Port 56000' /etc/ssh/sshd_config; then
# sed -i '/^Port 22/a Port 56000' /etc/ssh/sshd_config
# SSHD_CHANGED=1
# fi
# if grep -q '^AddressFamily inet6' /etc/ssh/sshd_config; then
# sed -i 's/^AddressFamily inet6$/AddressFamily any/' /etc/ssh/sshd_config
# SSHD_CHANGED=1
# fi
# if [ "$SSHD_CHANGED" -eq 1 ]; then
# # v6.1: restart 失败不再打死脚本(否则后面的 Calico 模块 + [1] 网卡改名全不跑)。
# # 注意这里失败是有分量的:sshd 起不来会丢 SSH,所以要显式记账而不是 `|| true` 一笔带过。
# if systemctl restart sshd; then
# echo "sshd now listening on ports 22 and 56000 (AddressFamily set to any)"
# else
# warn_section "[6] sshd restart" "$?"
# sshd -t 2>&1 | head -5 || true
# fi
# else
# echo "sshd ports 22 and 56000 already configured"
# fi
# [7] Mellanox MRDMA host route —— 已抽出到 deploy/scripts/gb-host-rdma-route.sh
# (默认关,仅 host 直跑 NCCL 测试用;生产 TKE 由 pod/asapd-lite 负责,不需要)。
#############################################################################
# [6b] Calico 内核模块 —— 【2026-08-08 起改为只校验,已烤入镜像 [7e]】
# /etc/modules-load.d/{vxlan,ipip}.conf 由 v21/v22 镜像提供。
# 缺失【不就地补写】—— 那会把「镜像到底烤没烤」这个事实掩盖掉。
# ↓↓↓ 原逻辑保留为注释 ↓↓↓
#############################################################################
echo "=== [6b] Calico 内核模块校验(已烤入镜像,本段不写)==="
MISSING_MOD=0
for m in vxlan ipip; do
if [ -f "/etc/modules-load.d/$m.conf" ]; then
if lsmod | grep -qE "^$m "; then st="已加载"; else st="未加载(下次 boot 由 systemd-modules-load 加载)"; fi
echo " OK /etc/modules-load.d/$m.conf 存在,当前 $st"
else
echo " !! MISSING /etc/modules-load.d/$m.conf —— 镜像未烤入 [7e]"
MISSING_MOD=$((MISSING_MOD + 1))
fi
done
[ "$MISSING_MOD" -eq 0 ] || warn_section "[6b] Calico 模块(镜像未烤入 [7e])" "$MISSING_MOD"
# # [6b] Load networking modules for Calico (VXLAN / IPIP)
# #############################################################################
# echo "=== [6b] Loading networking modules (Calico vxlan/ipip) ==="
# modprobe vxlan || true
# modprobe ipip || true
# echo "vxlan" > /etc/modules-load.d/vxlan.conf
# echo "ipip" > /etc/modules-load.d/ipip.conf
echo "=== Customer Initialization Complete (v7.1: [1] 不改名(udev 已命名) + [5] 改为 metadata 策略注入,不再写 lustre.conf) ==="
G.3 GB300 v7.0(配 v21 镜像)
功能概述见 §1.2;与 v7.1 为并行选项(配 v21 镜像),仍由脚本自行改名(约 130s)。本地权威副本 deploy/tlinux4-customer-init-universal-v7dot0.sh。
#!/bin/bash
# TLinux 4 (TencentOS Server 4.0) — Universal Startup Script (Customer) — v7.0
#
###############################################################################
# ⚠️ 2026-08-09 【原地修订,版本号仍为 v7.0】(经确认不出 v7.2/v7.3,避免动
# v21 镜像版本戳里的 requires_customer_init 字段与 README 配对表)
#
# 改动仅一处:[5] 段在 daemon-reload 之后补 `systemctl start <挂载点>.automount`。
# 原因:daemon-reload 只让 generator【生成】 mount/automount 单元,不会启动它们,
# 于是首启后 lustre 挂不上、要等下次重启才自愈(v6dot2 起就有此缺陷)。
# 详见 [5] 段内注释。其余各段与修订前逐字节相同。
###############################################################################
#
###############################################################################
# ⚠️ 为什么跳到 v7.0 而不是 v6.2:仓库里【已经存在】另一份
# `scripts/tlinux4-customer-init-universal-v6.2.sh`(2026-08-04,把 [4] hugepages
# 改成每 boot 的 systemd service)。两条 v6.1 谱系并行演进、各带对方没有的修复:
# scripts/v6.2 → [4] hugepages 每 boot service(重启后不归零)
# build-scripts/v6dot1 → [2] 分区失败只记账、不打死整脚本
# 我最初从 build-scripts/v6dot1 分支,漏了前者 —— graceivy 首次重启后 hugepages=0
# 就是这么来的。v7.0 合并两边并加上 lustre 策略注入,终结这个分裂。
#
# v7.0 = scripts/v6.2([4] hugepages service)
# + build-scripts/v6dot1([2] 分区容量前检 / 失败只记账)
# + [5] lustre 策略注入 + 显式 restart lustre-lnet.service(本版新增)
###############################################################################
#
###############################################################################
# v6.2 changelog(相对 v6.1)—— 配套 **v21 镜像**(tlinux-gb300-ipv6-dual-50gb-v21)
#
# 唯一改动:[5] 段整体重写。其余各段与 v6.1 逐字节相同(含 [1] 网卡改名)。
#
# [删除] 不再写 /etc/modprobe.d/lustre.conf。两个理由,都在真机上出过事:
# · 时序:本段在 boot +112~124s 执行,而 fstab 的 _netdev 挂载在 +6~10s 就可能
# 触发 modprobe lustre —— 那时 conf 还没写,lnet 拿不到 networks= 就永久失败。
# (2026-08-06 taiji `gb300-central-d0007-w16` 实测)
# · 覆写:`>` 会抹掉同文件里的 lnet_numa_range / ksocklnd 调优行。
# ⇒ 这件事已交给 v21 镜像里的 lustre-lnet.service + lustre-lnet-up.sh,
# 它在 bond1 的 .device 单元就绪后执行,且只替换 networks= 那一行。
#
# [新增] [5] 改为【只注入策略】:从 GCE metadata 读 lustre-mgs-nid /
# lustre-mountpoint / lustre-peering-cidr / lustre-nic,写
# /etc/sysconfig/lustre-client 与 fstab 行(带
# x-systemd.requires=lustre-lnet.service + x-systemd.automount)。
# MGS 或挂载点缺任一 ⇒ 本机不挂 lustre,什么都不写。
#
# ⚠️ 依赖:本版**必须配 v21 及以后的镜像**。在 v19/v20dot1 镜像上跑会写出一条
# 指向不存在的 lustre-lnet.service 的 fstab 行 —— 挂载会失败(Requires 不满足)。
# 老镜像请继续用 v6.1。
###############################################################################
#
# ⚠️ 本文件是 tlinux4-customer-init-universal-v6dot1.sh 的【副本 + 增量】,
# v6.1 与原 v6.0 文件均保持不动。
# v6.1 曾只改一次性段的失败处理,不改任何业务逻辑。
# 合并版基线(我方 + 前线共同迭代):= v5.9 + 前线 universal_v1 的 [1a] wait_rdma_ready
# (兼容生产存量 v17 机器);前线 [1b](RDMA udev 固化)按用户决策未纳入,守决策 #2。
# Compatible with: A4X/GB200 (VM), A4X MAX/GB300 (Bare Metal), H100, CPU
# 同时通吃 v17 与 v18/v18.1 镜像 —— 无论哪个镜像,开机后网卡名都正确。
#
# 一份通吃:自动探测适配 GB200(GVNIC/4 RDMA)与 GB300(IDPF eth0/eth1/8 RDMA)。
# 命名:管理网卡按序 → bond0/bond1;全部 RDMA(rdma dev 全遍历,4 或 8 张)→ bond2..bondN。
#
# v5.6 changelog(相对 v5.5):
# 1. [安全] 网卡改名整体挪到脚本【最后】,在磁盘/RAID/sshd 等前置全部完成并持久化之后才动网络。
# 2. [安全] mgmt(承载默认路由的网卡)改名带【自愈看门狗】:改名后轮询 GCP 元数据服务器可达性,
# 失败则自动 revert(还原网卡名 + NM profile),机器退回「可达但未改名」——裸金属无需关机、
# 不触发消毒。因此可直接在 GB300(IDPF)真机验证 mgmt 改名。
# 3. [顺序] [5] Lustre 路由依赖 bond1,移动到改名之后执行。
# 4. 承接 v5.5:NM profile 对每个改名网卡同步;RDMA rdma dev 全遍历(GB300 8 张全覆盖);
# [7] host route 默认关(仅 metadata enable-rdma-host-route=true 才配),且用 env 传 JSON。
#
# v5.7 changelog(相对 v5.6):
# 5. [客户要求] [3] 本地 SSD RAID0 段【停用】,仅保留为注释参考;本地 SSD 由客户自行初始化。
#
# v5.8 changelog(相对 v5.7):
# 6. [修复] RDMA 改名改的是 *netdev*(gpu*rdma*→bond2..N),ibdev(mlx5_*)保持不动
# (客户确认规则;旧版 v5.3/v5.7 用 `rdma dev set` 改的是 ibdev,方向反了)。
# netdev 改名不承载 SSH,每 boot 重放、不做 udev(避 CX-8 双口单 PCI 的 NAME= 冲突)。
# 7. [新增] [8] GPU 持久化(enable nvidia-persistenced)+ google-shutdown-scripts /
# nvidia-persistenced 的 TimeoutStopSec drop-in(20s/15s),避免关机卡 stop job。
# 8. [新增] [9] GCP MDS 防护:装 /usr/local/sbin/gcp-mds-protect.sh +
# kubelet.service.d/zz-gcp-mds-protect.conf drop-in,在客户 iptables.sh 之后
# 重压 169.254.169.254 RETURN(治 w3 病根,durable,不碰客户 iptables.sh);
# 并在当前 boot 立即 assert 一次。
#
# v5.9 changelog(相对 v5.8)—— 架构拆分,本脚本回归「客户镜像初始化」本职:
# 9. [拆出] [8] GPU 持久化+超时、[9] MDS 防护 → 移到独立加固包
# deploy/scripts/gb-gcp-hardening.sh(装一次即持久的 systemd 产物,由 rollout
# SSH 下发一次即可,且是 v18 镜像的烘焙清单)。本脚本不再含这两段。
# 10. [拆出] [7] MRDMA host route(默认关,仅 host 直跑 NCCL 测试用)→ 独立脚本
# deploy/scripts/gb-host-rdma-route.sh,测试者按需手动运行。
# 11. [重构] [5] Lustre:startup 只保留通用的 `lnet networks="tcp(bond1)"`(无网段)。
# 环境相关的 PSA 静态路由 + mount + 路由持久化 → 全部移到推送脚本
# deploy/scripts/mount-lustre.sh(env 驱动、无默认值),因 GB200/GB300 用不同
# lustre/VPC/PSA 但共用本 startup。同时删除旧的死代码清理(172.16.0.0/24 via
# 10.201.0.1 + 99-lustre-route dispatcher)——实测 v18dot1 镜像已无这些残留。
# 本脚本现仅含:一次性(磁盘/sshd/hugepages/Calico模块)+ 每boot netdev 改名 + lustre lnet conf。
#
###############################################################################
# v6.0 changelog(我方合并版,基于前线 universal_v1,相对 v5.9)
# —— 让 [1] 段在【生产存量 v17 镜像的机器】上也能生效,同时守住决策 #2。
#
# [吸收] 前线 universal_v1 的 [1a] wait_rdma_ready()(见 12);
# [去除] 前线 universal_v1 的 [1b] RDMA udev 固化(见 13,按用户决策不引入)。
#
# 12. [修复·A / 已吸收] 新增 wait_rdma_ready(),在 [1] 段的 gate
# `if rdma link show 2>/dev/null | grep -q .` 之前调用。gate 本身不动。
# 这是让本脚本【兼容生产存量 v17 机器】的关键修复。
#
# ── 为什么需要 ──
# v17 与 v18 镜像上 [1] 段的代码完全相同,差异只在【它跑得多早】:
#
# 镜像 google-startup-scripts 启动时刻 mlx5_ib 注册时刻 gate 判定
# v17 开机后 16.5 – 19.9 s ~19.5 s 多数判空 → 整段跳过
# v18.1 开机后 125 – 141 s ~19.5 s 恒真 → 正常执行
#
# v17 抢在 IB 注册之前跑到 gate,`rdma link show` 输出为空 → 整个 [1] 段
# (含 mgmt 改名)被跳过。实测 172 台 v17 中 141 台(82%)如此;剩下 31 台
# 恰好 start 在 19.0–19.9 s 赶上了 IB 注册,所以"看起来是好的"。
# 这不是代码问题,是时序问题,因此修法是【等】而不是【改逻辑】。
#
# ── 为什么可以一份脚本通吃、不需要判镜像版本 ──
# "等待"在已经就绪的环境里自动退化为零成本:v18 跑到这里时 8 张 IB 早已注册,
# 第一轮轮询即命中并立刻返回,不增加任何开机时间。v17 则等约 3 s。
#
# ── 安全性 ──
# * 硬上限超时(RDMA_WAIT_MAX,默认 180 s),超时即放行、绝不阻塞开机;
# 超时后 gate 判空 → 行为与 v5.9 完全一致(安全降级,不会更糟)。
# * 判据不是"有 ≥1 张就过",而是与 PCI 层枚举到的 Mellanox function 数比对,
# 避免只注册了 3 张就往下跑、剩下 5 张漏改名。
# * PCI 期望数取不到时(非 Mellanox RDMA / 未来新卡)退回"数量连续 5 轮不变"。
# * 本机根本没有 Mellanox 设备(CPU 机 / H100 非 RDMA 配置):10 s 后即放弃等待。
# * 掉卡机(实到数永远凑不齐期望数):靠"稳定 5 轮"退出,约 6 s。
#
# 13. [新增·B / 已去除] 前线 universal_v1 曾含 [1b]:把 RDMA netdev 名固化到 udev
# (PCI 地址 → NAME=bondN),作为 [1a] 超时的兜底。经用户决策【不吸收】:
# * [1a] 已从根上修好"v17 改名不生效"的时序竞争,[1b] 边际价值≈0;
# * udev 映射一旦固化,后续开机只会盲目套用、不再校验;裸金属 GB300 拓扑
# 变化(换卡 / 掉卡 / 换 host)时可能把网卡命错 —— 这正是要主动规避的后续风险。
# 故守回决策 #2「RDMA netdev 每 boot 现场改名、不落 udev」,本脚本不含 [1b] 段,
# 也不含 PERSIST_RDMA_UDEV 参数。首启 /21 lustre 路由改用 [1] 段末尾的显式
# `nmcli connection up 10-bond1` nudge 触发 dispatcher(见该处注释)。
###############################################################################
# v6.1 changelog(相对 v6.0)—— 只动「一次性段的失败处理」,业务逻辑零改动。
#
# 起因(2026-08-06,真机 hzchen-v20dd-gb300-0019,50GB boot disk):
# [2] 段 `sgdisk -n 3:0:+20G` 在盘放不下时返回 4,而脚本顶部 set -euo pipefail
# 把【整个 startup script】打死在这一行:
# Could not create partition 3 from 104855552 to 146798591
# Script "startup-script" failed with error: exit status 4
# 后果是 [4] hugepages、[6] sshd、[6b] Calico 模块、以及最关键的 [1] 网卡改名
# (bond0..bondN)全部不执行 —— 机器表面 RUNNING / SSH 通 / GPU 在,实际:
# 没有任何 bond*、HugePages_Total=0、/usr/local 还在 root 分区上,外部看不出坏了。
# 且 v6.0 失败时不落任何 stamp → 每次开机重试、每次都死在同一行。
#
# 14. [修复] [2] 增加【容量前检】:先算 GPT 尾部可用扇区,不够 (USRLOCAL_GB+MIN_DATA_GB)
# 就明确 SKIP 并打印需要多大的盘,不再让 sgdisk 去撞墙。
# 15. [修复] [2] 失败(含容量不足)只记账不终止;容量不足另落 /etc/.partitions-skipped,
# 避免每 boot 无效重试。
# ⚠️ 重跑要删【两个】标记:`rm -f /etc/.partitions-skipped /etc/.customer-init-done`
# —— [2] 整体在 INIT_STAMP 门内,只删 .partitions-skipped 不会有任何效果。
# 16. [加固] [4] hugepages 由 `echo | tee`(pipefail 下写失败即打死脚本)改为逐 NUMA 节点
# 写入 + 读回校验(请求 4096 实到多少要看得见),失败只记账。
# 19. [修正 16 的误报,2026-08-06 richivy 真机] 只对 **MemTotal>0** 的 NUMA 节点分配。
# GB300 实测 34 个 node 里只有 6 个有常规内存(node0/1/2/10/18/26),其余 28 个是
# GPU/HBM 侧节点,写 nr_hugepages 恒读回 0 —— 那不是失败,是本来就分不了。
# 不排除的话每台机都会误报「28 个节点未达标」。实际结果 6×4096=24576(48GiB),
# 与车队已知良好值一致。
# ⚠️ 汇总看 `/sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages`,**不要**看
# /proc/meminfo 的 HugePages_Total —— 后者只统计【默认大页尺寸】那个池,
# 本机 Hugepagesize=524288kB(512MB),2M 池不在里面,拿它判恒为 0。
# 17. [加固] [6] `systemctl restart sshd` 失败不再终止脚本,改为记账 + 打印 `sshd -t`。
# 18. [新增] 失败流水 /etc/.customer-init-failures —— 给巡检一个可 grep 的信号;
# 「脚本跑完了」不等于「每段都成功」,这个文件是二者的区分依据。
#
# ⚠️ 未改动:[1] 网卡改名段(它本来就在 `set +e` 区域内,自带 mgmt 自愈看门狗)。
# ⚠️ 建机要求(镜像本身 50GB):--boot-disk-size 必须 > 50 + USRLOCAL_GB + MIN_DATA_GB;
# 生产建议 ≥200GB。盘不放大时本脚本会跳过分区并继续,不会再连累其它段。
###############################################################################
#
# 真机验证(GB300 #3, hzchen-v17-gb300-startup-val-3, subblock-0004, 2026-07-27):
# 改名放最后 + mgmt 自愈看门狗全绿 —— eth0→bond0/eth1→bond1(两 NM profile 均同步)、
# Network healthy 无需 revert、mlx5_0..7→bond2..bond9(8 张全改)、default route on bond0(DHCP)、
# SSH 22 可达、IMEX disabled、4× GB300 GPU。即「从 idpf 到 rdma 连号 bond0..bond9」达成。
#
# 镜像已内置: NVIDIA driver, GVE/IDPF, IMEX, GDRCopy, nvidia-persistenced,
# SELinux/firewalld disabled, memlock unlimited, sudoers, SSH。
set -euo pipefail
exec > >(tee /var/log/tlinux4-customer-init.log) 2>&1
INIT_STAMP=/etc/.customer-init-done
# --- v6.0 可调参数(有安全默认值,不填即与 v5.9 行为一致)-------------------
RDMA_WAIT_MAX="${RDMA_WAIT_MAX:-180}" # [1a] 等待 RDMA 注册的硬上限(秒)
# --- v6.1 可调参数 ---------------------------------------------------------
USRLOCAL_GB="${USRLOCAL_GB:-20}" # [2] p3 = /usr/local 大小(GiB)
MIN_DATA_GB="${MIN_DATA_GB:-10}" # [2] p4 = /data 的最小可接受大小(GiB)
FAIL_LEDGER=/etc/.customer-init-failures # 各段失败流水,给巡检一个可 grep 的信号
# v6.1:一次性段里任何一段失败,都不该带走后面的段 —— 尤其不该带走 [1] 网卡改名
# (那是让机器有 bond0..bondN 的唯一途径)。失败记账 + 继续跑,而不是 set -e 直接死。
warn_section() { # $1=段名 $2=返回码
echo "!!! WARN: $1 未完成(rc=$2)—— 继续执行后续段,不终止脚本"
echo "$(date -Is) section=$1 rc=$2" >> "$FAIL_LEDGER" 2>/dev/null || true
}
echo "=== Disable SELinux ==="
setenforce 0 || true
if [ -f /etc/selinux/config ]; then
sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config || true
fi
###############################################################################
# ONE-TIME setup (disk / RAID / hugepages / sshd / host-route / modules).
# Gated by INIT_STAMP. Network is intentionally NOT touched here — NIC rename
# is deferred to the END of every boot (see bottom) so all prerequisites are
# in place and persisted before we risk the management interface.
###############################################################################
if [ ! -f "$INIT_STAMP" ]; then
echo "================================================================"
echo " TLinux 4 v6.1 — Startup Script (Universal Customer) — one-time setup"
echo " $(date)"
echo "================================================================"
#############################################################################
# [2] Boot disk partitioning: /usr/local (20G) + /data (remaining)
# v6.1: 容量前检 + 失败不终止整脚本 + 失败落状态文件(见文件头 v6.1 changelog 14/15)
#############################################################################
echo "=== [2] Boot disk partitioning ==="
BOOT_DEV=$(findmnt -n -o SOURCE / | sed 's/p[0-9]*$//')
PARTITION_STAMP=/etc/.partitions-created
PARTITION_SKIP_STAMP=/etc/.partitions-skipped
# 注意:本函数【不依赖 set -e】。实测 bash 在 `if ( set -e; ... )` / `... || rc=$?`
# 这两种上下文里都会把 -e 抑制掉(连子 shell 内部一起抑制),所以每一步必须显式判返回值,
# 否则「分区失败」会被静默当成成功。
do_partition() {
local sect last_usable last_end free_sect need_sect free_mib need_gib
local usrlocal_gb="${USRLOCAL_GB:-20}" min_data_gb="${MIN_DATA_GB:-10}"
command -v sgdisk >/dev/null || { echo " ERROR: 无 sgdisk"; return 1; }
# 备份 GPT 挪到盘尾,last-usable-sector 才是真值(盘被放大时尤其必要)
sgdisk -e "$BOOT_DEV" >/dev/null 2>&1 || true
sect=$(blockdev --getss "$BOOT_DEV" 2>/dev/null || echo 512)
last_usable=$(sgdisk -p "$BOOT_DEV" 2>/dev/null | sed -n 's/.*last usable sector is \([0-9]\+\).*/\1/p' | head -1)
last_end=$(sgdisk -p "$BOOT_DEV" 2>/dev/null | awk '$1 ~ /^[0-9]+$/ {print $3}' | sort -n | tail -1)
if [ -z "$last_usable" ] || [ -z "$last_end" ]; then
echo " ERROR: 读不出 GPT 布局(last_usable=[$last_usable] last_end=[$last_end])"; return 1
fi
free_sect=$(( last_usable - last_end ))
need_sect=$(( (usrlocal_gb + min_data_gb) * 1024 * 1024 * 1024 / sect ))
free_mib=$(( free_sect * sect / 1024 / 1024 ))
need_gib=$(( usrlocal_gb + min_data_gb ))
# ── 容量前检 ──
# 这是 v6.1 的主要修复点。v6.0 直接 `sgdisk -n 3:0:+20G`,盘不够大时 sgdisk 返回 4,
# 而脚本顶部的 set -euo pipefail 会把【整个 startup script】打死 —— 后面的 hugepages /
# sshd / Calico 模块 / 以及最关键的 [1] 网卡改名(bond0..bondN)全都不执行。
# 实测:hzchen-v20dd-gb300-0019(50GB boot disk)每次开机都死在这一行,
# 机器表面 RUNNING、SSH 通、GPU 在,但没有任何 bond*、HugePages_Total=0,外部看不出坏了。
if [ "$free_sect" -lt "$need_sect" ]; then
echo " SKIP: boot disk 可用尾部空间仅 ${free_mib} MiB,需要 ≥ ${need_gib} GiB"
echo " (p3=/usr/local ${usrlocal_gb}G + p4=/data 至少 ${min_data_gb}G)"
echo " → 建机时 --boot-disk-size 要大于镜像本身(50GB)+ ${need_gib}GB;生产建议 ≥200GB。"
echo " → /usr/local 与 /data 保持在 root 分区上,不影响开机与后续各段。"
return 2 # 2 = 容量不足(可预期),与 3 = 真的出错 区分开
fi
echo " 容量检查通过:尾部可用 ${free_mib} MiB ≥ 需要 ${need_gib} GiB"
echo "--- Creating boot disk partitions ---"
sgdisk -n "3:0:+${usrlocal_gb}G" -t 3:8300 "$BOOT_DEV" || { echo " ERROR: 创建 p3 失败"; return 3; }
sgdisk -n 4:0:0 -t 4:8300 "$BOOT_DEV" || { echo " ERROR: 创建 p4 失败"; return 3; }
partprobe "$BOOT_DEV" 2>/dev/null || true
sleep 2
mkfs.xfs -f "${BOOT_DEV}p3" || { echo " ERROR: mkfs p3 失败"; return 3; }
mkfs.xfs -f "${BOOT_DEV}p4" || { echo " ERROR: mkfs p4 失败"; return 3; }
local tmpmnt; tmpmnt=$(mktemp -d)
mount "${BOOT_DEV}p3" "$tmpmnt" || { echo " ERROR: 临时挂载 p3 失败"; rmdir "$tmpmnt"; return 3; }
cp -a /usr/local/. "$tmpmnt/" 2>/dev/null || true
umount "$tmpmnt" || { echo " ERROR: 卸载临时挂载点失败"; return 3; }
rmdir "$tmpmnt"
mount "${BOOT_DEV}p3" /usr/local || { echo " ERROR: 挂载 /usr/local 失败"; return 3; }
mkdir -p /data
mount "${BOOT_DEV}p4" /data || { echo " ERROR: 挂载 /data 失败"; return 3; }
local p3_uuid p4_uuid
p3_uuid=$(blkid -s UUID -o value "${BOOT_DEV}p3")
p4_uuid=$(blkid -s UUID -o value "${BOOT_DEV}p4")
if [ -n "$p3_uuid" ] && ! grep -q "$p3_uuid" /etc/fstab; then
echo "UUID=$p3_uuid /usr/local xfs defaults,nofail 0 2" >> /etc/fstab
fi
if [ -n "$p4_uuid" ] && ! grep -q "$p4_uuid" /etc/fstab; then
echo "UUID=$p4_uuid /data xfs defaults,nofail 0 2" >> /etc/fstab
fi
echo "Boot disk partitioned: p3=/usr/local(${usrlocal_gb}G) p4=/data(remaining)"
return 0
}
if [ -f "$PARTITION_STAMP" ]; then
echo " 已分区过($PARTITION_STAMP 存在),跳过"
elif [ -f "$PARTITION_SKIP_STAMP" ]; then
# 落 skip 标记的意义:v6.0 失败时不 touch 任何 stamp,于是【每次开机都重试、每次都死】。
# 盘的大小不会自己变大,重试没有意义,只会每 boot 都把后面的段一起带走。
# ⚠️ 重跑要删【两个】标记:本段整体在 INIT_STAMP 门内(见上面的 if),
# 只删 .partitions-skipped 不会有任何效果 —— 首启完成后一次性段根本不再进入。
echo " 上次因容量不足跳过($PARTITION_SKIP_STAMP),不再重试。"
echo " 放大盘后重跑分区:rm -f $PARTITION_SKIP_STAMP $INIT_STAMP && reboot"
echo " (会连带重跑整个一次性段;各段幂等,重复执行安全)"
cat "$PARTITION_SKIP_STAMP" 2>/dev/null || true
else
# ⚠️ 必须写成 `PART_RC=0; do_partition || PART_RC=$?`。
# 写成 `do_partition; PART_RC=$?` 会被 set -e 在函数返回非 0 的瞬间直接打死脚本
# (实测 exit=2,`PART_RC=$?` 那行根本执行不到)—— 那就等于把本次要修的 bug 原样重写一遍。
PART_RC=0; do_partition || PART_RC=$?
case "$PART_RC" in
0) touch "$PARTITION_STAMP" ;;
2) { echo "skipped=capacity date=$(date -Is) boot_dev=$BOOT_DEV"; } > "$PARTITION_SKIP_STAMP"
warn_section "[2] 分区(容量不足,已跳过)" 2 ;;
*) warn_section "[2] 分区" "$PART_RC" ;;
esac
fi
#############################################################################
# [3] Local SSD RAID0 setup —— 【已按客户要求停用,仅作参考,不实际执行】
#############################################################################
# 客户自行初始化本地 SSD(RAID/文件系统/挂载),故本段不再执行。
# 如需由 startup-script 接管,取消下方整段注释即可(4×2.9T 本地 SSD → RAID0
# → /mnt/stateful_partition;注意首启 mkfs.xfs 对 11.7T 阵列约需 ~88s)。
echo "=== [3] Local SSD RAID0 setup —— SKIPPED (customer-managed) ==="
# --- BEGIN reference (disabled) ------------------------------------------
# SSD_DEVICES=()
# for disk in /dev/nvme*n1; do
# [ -b "$disk" ] || continue
# PART_COUNT=$(lsblk -n -o NAME "$disk" 2>/dev/null | wc -l)
# if [ "$PART_COUNT" -le 1 ]; then
# SSD_DEVICES+=("$disk")
# echo " Detected local SSD: $disk ($(lsblk -n -d -o SIZE "$disk"))"
# fi
# done
#
# NUM_SSDS=${#SSD_DEVICES[@]}
# echo " Found $NUM_SSDS local SSD device(s)"
# if [ "$NUM_SSDS" -gt 0 ]; then
# MOUNT_POINT="/mnt/stateful_partition"
# mkdir -p "$MOUNT_POINT"
# if [ "$NUM_SSDS" -eq 1 ]; then
# TARGET_DEV="${SSD_DEVICES[0]}"
# mkfs.xfs -f "$TARGET_DEV"
# mount "$TARGET_DEV" "$MOUNT_POINT"
# DEV_UUID=$(blkid -s UUID -o value "$TARGET_DEV")
# if [ -n "$DEV_UUID" ] && ! grep -q "$DEV_UUID" /etc/fstab; then
# echo "UUID=$DEV_UUID $MOUNT_POINT xfs defaults,nofail 0 2" >> /etc/fstab
# fi
# else
# mdadm --stop /dev/md0 2>/dev/null || true
# mdadm --create /dev/md0 --level=0 --raid-devices="$NUM_SSDS" "${SSD_DEVICES[@]}" --force --run
# mkfs.xfs -f /dev/md0
# mount /dev/md0 "$MOUNT_POINT"
# mkdir -p /etc/mdadm
# mdadm --detail --scan >> /etc/mdadm/mdadm.conf
# DEV_UUID=$(blkid -s UUID -o value /dev/md0)
# if [ -n "$DEV_UUID" ] && ! grep -q "$DEV_UUID" /etc/fstab; then
# echo "UUID=$DEV_UUID $MOUNT_POINT xfs defaults,nofail 0 2" >> /etc/fstab
# fi
# fi
# mkdir -p "$MOUNT_POINT"/{gcsfuse-cache,scratch-data}
# echo "$MOUNT_POINT mounted (total: $(df -h "$MOUNT_POINT" | awk 'NR==2{print $2}'))"
# else
# echo "WARNING: No local SSD devices found"
# mkdir -p /mnt/stateful_partition
# fi
# --- END reference (disabled) --------------------------------------------
#############################################################################
touch "$INIT_STAMP"
echo "=== One-time setup complete ==="
else
echo "One-time setup already completed. Proceeding to network rename."
fi
###############################################################################
# [1] Network interface rename (auto-detect) — EVERY BOOT, runs LAST.
# mgmt NICs → bond0/bond1 (with self-healing watchdog on the primary),
# all RDMA → bond2..bondN.
# set +e in this region: a stray failure must NOT abort before the
# watchdog/revert can run and keep the box reachable.
###############################################################################
set +e
###############################################################################
# [1a] 【v6.0 新增·A】等待 RDMA(mlx5_ib)注册完成,再进入下面的 gate。
#
# v17 镜像的 google-startup-scripts 在开机后 16.5–19.9 s 就跑到这里,而
# mlx5_ib 要到 ~19.5 s 才注册,导致 gate `rdma link show | grep -q .` 判空、
# 整个 [1] 段(含 mgmt 改名)被跳过。v18.1 在 125–141 s 才跑,天然赶得上。
# 本函数让脚本"等到 RDMA 就绪"——在 v18 上第一轮即命中、零开销;在 v17 上
# 等约 3 s。超时则原样放行,行为退化为 v5.9,不会更糟。
# gate 本身及其后的所有逻辑一行未改。
###############################################################################
wait_rdma_ready() {
local max="$RDMA_WAIT_MAX"
local expect=0 n=0 last=-1 stable=0 t=0 v
# 期望张数 = PCI 层枚举到的 Mellanox(vendor 0x15b3) function 数。
# PCI 枚举在开机 ~1 s 完成,远早于 mlx5_ib 注册(~19.5 s),脚本跑到时必已稳定。
for v in /sys/bus/pci/devices/*/vendor; do
[ -r "$v" ] || continue
[ "$(cat "$v" 2>/dev/null)" = "0x15b3" ] && expect=$((expect + 1))
done
while [ "$t" -lt "$max" ]; do
n=$(rdma link show 2>/dev/null | grep -c .)
# 命中期望张数 → 立刻返回(v18 走这条,t=0)
if [ "$expect" -gt 0 ] && [ "$n" -ge "$expect" ]; then
echo " [1a] RDMA 就绪: ${n}/${expect} 张 (PCI 期望 ${expect}),等待 ${t}s"
return 0
fi
# 本机没有 Mellanox 设备(CPU 机 / 非 RDMA 配置)→ 不空等
if [ "$expect" -eq 0 ] && [ "$n" -eq 0 ] && [ "$t" -ge 10 ]; then
echo " [1a] 未发现 Mellanox PCI 设备且 rdma link 为空,跳过等待"
return 1
fi
# 取不到 PCI 期望值,或掉卡永远凑不齐 → 数量连续 5 轮不变即视为就绪
if [ "$n" -gt 0 ] && [ "$n" -eq "$last" ]; then
stable=$((stable + 1))
if [ "$stable" -ge 5 ]; then
echo " [1a] RDMA 数量稳定于 ${n} 张 (PCI 期望 ${expect}),等待 ${t}s"
return 0
fi
else
stable=0
fi
last="$n"
sleep 1
t=$((t + 1))
done
echo " [1a] !! 等待 ${max}s 超时,当前 ${n} 张 (PCI 期望 ${expect}) —— 按现状继续"
return 1
}
echo "=== [1a] 等待 RDMA 注册就绪 (上限 ${RDMA_WAIT_MAX}s) ==="
wait_rdma_ready
if rdma link show 2>/dev/null | grep -q .; then
echo "=== [1] Network interface rename (auto-detect, deferred to end) ==="
# Remove legacy ifcfg files to prevent NetworkManager conflicts
rm -f /etc/sysconfig/network-scripts/ifcfg-eth* 2>/dev/null || true
BOND_IDX=0
PRIMARY_NIC=$(ip route show default 2>/dev/null | awk '{print $5}' | head -1)
# Health check: metadata server reachable ⇒ default route works
net_healthy() {
curl -sf -m 3 -H "Metadata-Flavor: Google" \
http://169.254.169.254/computeMetadata/v1/instance/id >/dev/null 2>&1
}
# Collect management NICs: has PCI device, not lo/bond*, not IB/RDMA, not USB.
# USB-bus NICs are the BMC/IPMI gadget (e.g. cdc_eem usb0 on some GB300 hosts);
# they are NOT real mgmt/data NICs. If counted, usb0 grabs bond2 and pushes the
# RDMA netdevs to bond3+ (off-by-one). Skip anything whose device bus is usb.
MGMT_NICS=()
for devpath in /sys/class/net/*/device; do
[ -e "$devpath" ] || continue
nic=$(basename "$(dirname "$devpath")")
[[ "$nic" == lo || "$nic" == bond* ]] && continue
[[ -d "/sys/class/net/$nic/device/infiniband" ]] && continue
bus=$(basename "$(readlink -f "/sys/class/net/$nic/device/subsystem" 2>/dev/null)" 2>/dev/null)
[[ "$bus" == "usb" ]] && continue
MGMT_NICS+=("$nic")
done
if [ ${#MGMT_NICS[@]} -gt 0 ]; then
# Order: primary (default-route) NIC → bond0, remaining by PCI addr.
ORDERED_MGMT=()
if [[ -n "$PRIMARY_NIC" ]] && ip link show "$PRIMARY_NIC" &>/dev/null; then
ORDERED_MGMT+=("$PRIMARY_NIC")
fi
while read -r nic; do
[[ -z "$nic" ]] && continue
[[ "$nic" == "$PRIMARY_NIC" ]] && continue
ORDERED_MGMT+=("$nic")
done < <(for n in "${MGMT_NICS[@]}"; do
[[ "$n" == "$PRIMARY_NIC" ]] && continue
pci=$(basename "$(readlink -f "/sys/class/net/$n/device")" 2>/dev/null || echo "zzzz")
echo "$pci $n"
done | sort | awk '{print $2}')
NM_DIR=/etc/NetworkManager/system-connections
RENAMED_PAIRS=() # "orig:new" pairs, for possible revert
for nic in "${ORDERED_MGMT[@]}"; do
newname="bond${BOND_IDX}"
if ip link show "$nic" &>/dev/null; then
# sync NM keyfile for EVERY renamed NIC BEFORE the rename
for nmf in "$NM_DIR"/*.nmconnection; do
[ -f "$nmf" ] || continue
if grep -q "^interface-name=${nic}$" "$nmf" 2>/dev/null; then
sed -i "s/^interface-name=${nic}$/interface-name=${newname}/" "$nmf"
echo " NM profile $(basename "$nmf"): interface-name ${nic} → ${newname}"
fi
done
ip link set dev "$nic" down
ip link set dev "$nic" name "$newname"
ip link set dev "$newname" up
RENAMED_PAIRS+=("${nic}:${newname}")
echo " $nic → $newname"
fi
BOND_IDX=$((BOND_IDX + 1))
done
nmcli connection reload 2>/dev/null || true
MGMT_COUNT=$BOND_IDX
# --- Self-healing watchdog: confirm network recovered, else REVERT ---
if [ ${#RENAMED_PAIRS[@]} -gt 0 ]; then
echo " Waiting for network to recover after mgmt rename (metadata probe)..."
healthy=0
for _try in $(seq 1 20); do
sleep 2
if net_healthy; then healthy=1; break; fi
nmcli device connect bond0 2>/dev/null || true
done
if [ "$healthy" -eq 1 ]; then
echo " Network healthy after rename (metadata reachable)."
# Persist mgmt names via udev (PCI slot → bondN) only on success
UDEV_RULE="/etc/udev/rules.d/70-a4x-bond-rename.rules"
if [ ! -f "$UDEV_RULE" ]; then
: > "$UDEV_RULE"
for bidx in $(seq 0 $((MGMT_COUNT - 1))); do
PCI=$(basename "$(readlink -f "/sys/class/net/bond${bidx}/device")" 2>/dev/null || true)
[ -n "$PCI" ] && echo "SUBSYSTEM==\"net\", ACTION==\"add\", KERNELS==\"$PCI\", NAME=\"bond${bidx}\"" >> "$UDEV_RULE"
done
echo " Persisted ${MGMT_COUNT} mgmt NIC names via udev."
fi
# First-boot nudge: 显式拉起 bond1,触发 50-lustre-psa-route dispatcher 补 /21 lustre 路由。
# 稳态 reboot 时 udev 已固化 bond1、keyfile 自动连,dispatcher 自然触发;首启因网卡改名
# 晚于 NM 首次 up、事件带旧名会漏加,故此处补一枪(dispatcher 由镜像烤入,读 metadata 网段)。
if ip link show bond1 &>/dev/null; then
nmcli connection up 10-bond1 2>/dev/null || nmcli device connect bond1 2>/dev/null || true
echo " fired bond1 up → 50-lustre-psa-route 补 lustre 路由(若 metadata 已设 lustre-peering-cidr)"
fi
else
echo " !!! Network DID NOT recover after mgmt rename — REVERTING to stay reachable !!!"
for pair in "${RENAMED_PAIRS[@]}"; do
orig="${pair%%:*}"; new="${pair##*:}"
for nmf in "$NM_DIR"/*.nmconnection; do
[ -f "$nmf" ] || continue
if grep -q "^interface-name=${new}$" "$nmf" 2>/dev/null; then
sed -i "s/^interface-name=${new}$/interface-name=${orig}/" "$nmf"
fi
done
if ip link show "$new" &>/dev/null; then
ip link set dev "$new" down 2>/dev/null || true
ip link set dev "$new" name "$orig" 2>/dev/null || true
ip link set dev "$orig" up 2>/dev/null || true
echo " reverted $new → $orig"
fi
done
nmcli connection reload 2>/dev/null || true
systemctl restart NetworkManager 2>/dev/null || true
MGMT_COUNT=0
echo " Revert done. mgmt NICs left at original names; investigate before retrying rename."
fi
fi
else
# mgmt already renamed by udev this boot. Count contiguous bond* that are real
# PCI mgmt NICs; stop at any usb-bus bond (stale BMC entry from an old udev rule)
# so RDMA numbering isn't pushed off-by-one.
while ip link show "bond${BOND_IDX}" &>/dev/null; do
bus=$(basename "$(readlink -f "/sys/class/net/bond${BOND_IDX}/device/subsystem" 2>/dev/null)" 2>/dev/null)
[[ "$bus" == "usb" ]] && { echo " WARN: bond${BOND_IDX} is a USB NIC (stale mgmt rename); not counting as mgmt"; break; }
BOND_IDX=$((BOND_IDX + 1))
done
[ $BOND_IDX -gt 0 ] && echo " Management NICs already renamed (bond0-bond$((BOND_IDX - 1)))"
MGMT_COUNT=$BOND_IDX
fi
# RDMA rename — rename the RDMA *netdev* (gpu*rdma* → bondN); leave the ibdev
# (mlx5_*) UNCHANGED. Customer-confirmed rule:
# gpu0rdma0→bond2, gpu1rdma0→bond3, ... ; ibdev mlx5_0..N stay as-is.
# NOTE for customer: this renames the RDMA *netdev*. Any component that keys on
# the netdev name (e.g. dranet / k8s device plugin) must be configured to
# accept bond*; the ibdev name (mlx5_*) is intentionally preserved per the
# requirement. If dranet must see gpu*rdma*, do NOT enable this rename.
# Re-applied every boot (NOT udev-persisted, unlike mgmt): a netdev rename
# carries no SSH / default route so it is safe to defer to here; on GB300 the
# dual-port CX-8 can put two netdevs behind one PCI slot, which would make a
# PCI-keyed udev NAME= rule collide — so we simply re-apply on each boot.
RDMA_NETDEVS=()
for devpath in /sys/class/net/*/device; do
[ -e "$devpath" ] || continue
nic=$(basename "$(dirname "$devpath")")
[[ "$nic" == bond* ]] && continue
[[ -d "/sys/class/net/$nic/device/infiniband" ]] || continue # RDMA netdev only
RDMA_NETDEVS+=("$nic")
done
# sort by name so gpu0rdma0 < gpu1rdma0 < ... → bond2, bond3, ...
IFS=$'\n' RDMA_NETDEVS=($(printf '%s\n' "${RDMA_NETDEVS[@]}" | sort)); unset IFS
for nic in "${RDMA_NETDEVS[@]}"; do
newname="bond${BOND_IDX}"
ip link show "$nic" &>/dev/null || continue
ip link set dev "$nic" down 2>/dev/null || true
if ip link set dev "$nic" name "$newname" 2>/dev/null; then
ip link set dev "$newname" up 2>/dev/null || true
echo " $nic → $newname (netdev; ibdev unchanged)"
BOND_IDX=$((BOND_IDX + 1))
else
ip link set dev "$nic" up 2>/dev/null || true
echo " WARN: failed to rename RDMA netdev $nic → $newname"
fi
done
RDMA_COUNT=$((BOND_IDX - MGMT_COUNT))
echo " --- Result: ${MGMT_COUNT} mgmt + ${RDMA_COUNT} RDMA = ${BOND_IDX} total ---"
ip -br link show type ether 2>/dev/null || true
rdma link show 2>/dev/null || true
fi
set -e
###############################################################################
# [5] Lustre —— 【v6.2 重写】只注入策略,不碰 lnet 配置也不碰模块
###############################################################################
# ── 为什么 v6.1 的写法要改掉 ────────────────────────────────────────────────
# v6.1 这里做的是:
# echo 'options lnet networks="tcp(bond1)"' > /etc/modprobe.d/lustre.conf
# 两个问题,都在真机上出过事:
#
# 1. 【时序】写 conf 与 modprobe 必须原子发生。本段在 boot 的 +112~124s 才执行
# (google-startup-scripts 起得晚),而 fstab 的 _netdev 挂载在 +6~10s 就可能
# 触发 mount.lustre → modprobe lustre。那一刻 conf 还没写,lnet 拿不到
# networks=,退回自动枚举只看到 down 的 tunl0:
# LNetError: lnet: Can't find any usable interfaces, rc = -ENOENT
# 并回滚且【永不重试】;更糟的是 lnet 模块残留但无 NID,此后任何
# mount/modprobe 都返回 -22,必须 lustre_rmmod 才能恢复。
# (2026-08-06 在 taiji `gb300-central-d0007-w16` 实测,时间戳逐条对上。)
#
# 2. 【整文件覆写】`>` 会抹掉同文件里的调优行。车队机器上实际存在:
# options lnet networks="tcp(bond1)" lnet_numa_range=0
# options ksocklnd nscheds=16 peer_credits=32
# 覆写后 lnet_numa_range 与整个 ksocklnd 调优静默消失。
#
# ⇒ v21 镜像把「写 conf + modprobe + 校验 NID」合并进 /usr/local/sbin/lustre-lnet-up.sh,
# 由 lustre-lnet.service 在 bond1 的 .device 单元就绪后执行(声明式依赖,非轮询),
# 并且只替换 networks= 那一行、保留其它 options。
# 本段因此【不再碰 lustre.conf】,只负责注入本机的环境参数。
#
# ── 策略从 GCE metadata 读,镜像里零环境耦合 ─────────────────────────────────
# lustre-mgs-nid e.g. 44.10.26.7@tcp:/lustrefs
# lustre-mountpoint e.g. /apdcephfs_wzaz
# lustre-peering-cidr e.g. 44.10.24.0/21 (可选,给 50-lustre-psa-route 用)
# lustre-nic 默认 bond1 (可选)
# MGS 或挂载点缺任一 ⇒ 本机不挂 lustre,什么都不写(干净的开关)。
###############################################################################
echo "=== [5] Lustre 策略注入(v6.2:不再写 lustre.conf)==="
md_attr() { # $1=属性名;取不到返回空。
# 必须带 -f —— 不带时 404 会把 HTML 错误页当正文返回(实测 1614 字节),
# 使「未设就什么都不做」的保护恒真失效。
# 必须带 `|| true` —— curl -sf 在 404 时返回 22,而【赋值语句的退出码就是命令替换的
# 退出码】,此处 set -e 生效,`L_CIDR=$(md_attr ...)` 会直接打死整个 startup script。
# 2026-08-08 首次真机验证就栽在这:只注了 mgs-nid/mountpoint、没注 peering-cidr
# (本来就不需要,MGS 与 bond1 同 /21),结果脚本死在 [5] 段第三行。
# 同类坑:v6.1 里的 `do_partition; PART_RC=$?`。
curl -sf -m 3 -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/attributes/$1" 2>/dev/null || true
}
L_MGS=$(md_attr lustre-mgs-nid)
L_MP=$(md_attr lustre-mountpoint)
L_CIDR=$(md_attr lustre-peering-cidr)
L_NIC=$(md_attr lustre-nic); L_NIC="${L_NIC:-bond1}"
if [ -z "$L_MGS" ] || [ -z "$L_MP" ]; then
echo " metadata 未设 lustre-mgs-nid / lustre-mountpoint ⇒ 本机不挂 lustre,跳过"
echo " (镜像里的 lustre-lnet.service 会因 /etc/sysconfig/lustre-client 无挂载点而自行跳过,不加载任何模块)"
else
# 格式校验:纵深防御。metadata 返回了奇怪的东西时绝不往 fstab 里写。
case "$L_MGS" in
*@tcp:/*) ;;
*) echo " !! lustre-mgs-nid 格式不对(期望 <ip>@tcp:/<fsname>),跳过: $L_MGS"; L_MGS="" ;;
esac
case "$L_MP" in
/*) ;;
*) echo " !! lustre-mountpoint 不是绝对路径,跳过: $L_MP"; L_MGS="" ;;
esac
fi
if [ -n "$L_MGS" ] && [ -n "$L_MP" ]; then
echo " MGS=$L_MGS 挂载点=$L_MP 网卡=$L_NIC PSA网段=${L_CIDR:-<未设>}"
mkdir -p /etc/sysconfig "$L_MP"
{
echo "# 由 customer-init v6.2 于 $(date -Is) 从 GCE metadata 注入"
echo "LUSTRE_NIC=$L_NIC"
echo "LUSTRE_MOUNTPOINT=$L_MP"
[ -n "$L_CIDR" ] && echo "LUSTRE_PEERING_CIDR=$L_CIDR"
} > /etc/sysconfig/lustre-client
echo " 已写 /etc/sysconfig/lustre-client"
# fstab 行:挂载被钉在 lustre-lnet.service 之后(systemd 依赖,不是靠时间)
# x-systemd.requires= → 生成 Requires= + After=
# x-systemd.automount → 首次访问才挂,访问被 autofs 阻塞而不是失败
# device-timeout → 等 bond1 的 .device 单元的上限
FSTAB_OPTS="nofail,_netdev,x-systemd.requires=lustre-lnet.service,x-systemd.automount,x-systemd.mount-timeout=300,x-systemd.device-timeout=300"
FSTAB_LINE="$L_MGS $L_MP lustre $FSTAB_OPTS 0 0"
if grep -qE "^[^#]*[[:space:]]${L_MP}[[:space:]]+lustre[[:space:]]" /etc/fstab 2>/dev/null; then
CUR_LINE=$(grep -E "^[^#]*[[:space:]]${L_MP}[[:space:]]+lustre[[:space:]]" /etc/fstab | head -1)
if [ "$CUR_LINE" != "$FSTAB_LINE" ]; then
cp -a /etc/fstab "/etc/fstab.bak.customer-init.$(date +%Y%m%d-%H%M%S)"
# 用 awk 重写而不是 sed —— MGS NID 里有 @ 和 /,做 sed 替换串要转义,容易出错
awk -v mp="$L_MP" -v line="$FSTAB_LINE" \
'($2==mp && $3=="lustre"){print line; next} {print}' /etc/fstab > /etc/fstab.new \
&& [ -s /etc/fstab.new ] && mv /etc/fstab.new /etc/fstab
echo " 已更新 fstab 行(旧行已备份)"
else
echo " fstab 行已正确"
fi
else
echo "$FSTAB_LINE" >> /etc/fstab
echo " 已追加 fstab 行"
fi
systemctl daemon-reload 2>/dev/null || true
grep -n lustre /etc/fstab | sed 's/^/ /'
# ★ 必须显式让机制层重新评估 —— 这是【策略写在机制之后】的必然要求。
# 实测(2026-08-08 graceivy 首启):NM dispatcher 在 bond1 up 时(+131s)就触发了
# lustre-lnet.service,而本段要到 +137s 才写出 /etc/sysconfig/lustre-client。
# 机制层那时看到"未配 LUSTRE_MOUNTPOINT"就干净跳过,并因 RemainAfterExit=yes 标记成
# active —— 此后没有任何事件会再触发它,LNet 永远没有 NID,挂载必失败。
# 差的只有 5 秒,但这不是偶发竞态:dispatcher 由网卡就绪驱动,本段固定在 startup 末尾。
systemctl restart lustre-lnet.service 2>&1 | sed 's/^/ /' || true
sleep 2
NIDS=$(lctl list_nids 2>/dev/null | grep -v '^0@lo$' | tr '\n' ' ' || true)
if [ -n "$NIDS" ]; then
echo " LNet 已就绪: $NIDS"
else
echo " !! WARN LNet 仍无 NID —— 查 journalctl -u lustre-lnet.service"
fi
# ★ 2026-08-09 原地补:daemon-reload 只【生成】 mnt-xxx.{mount,automount} 单元,
# 【不会启动它们】。少这一步 automount 恒为 inactive dead(journal 里一条记录都没有),
# findmnt 查不到,要等【下一次 boot】由 local-fs.target 拉起才生效。
# 2026-08-08 在 graceivy-w1 / regalivy-w1 实测到该状态,两台重启后即自愈 ——
# 即「首启挂不上、重启才好」这个现象的真正原因,不是 LNet 也不是 fstab 写错。
#
# 位置在 restart lustre-lnet 之后:fstab 里有 x-systemd.requires=lustre-lnet.service,
# automount 依赖它,必须先起 LNet。
#
# 【只 start,不主动访问挂载点】:automount 是惰性的,start 完机制即就绪,
# 首次访问时自动挂。在 startup script 里主动 ls 会阻塞到真正挂完,
# 最坏等到 x-systemd.mount-timeout=300 秒,不值得拖慢开机。
AM_UNIT="$(systemd-escape -p --suffix=automount "$L_MP" 2>/dev/null || true)"
if [ -n "$AM_UNIT" ]; then
systemctl start "$AM_UNIT" 2>&1 | sed 's/^/ /' || true
echo " automount 单元 $AM_UNIT = $(systemctl is-active "$AM_UNIT" 2>/dev/null)"
else
echo " !! WARN 无法推导 automount 单元名(systemd-escape 不可用?)"
fi
fi
# [7]/[8]/[9] 已从本脚本移出(见 v5.9 changelog):
# - [8] GPU 持久化+超时、[9] MDS 防护 → deploy/scripts/gb-gcp-hardening.sh
# (装一次即持久;存量车队 SSH 下发一次,并作为 v18 镜像烘焙清单)。
# - [7] MRDMA host route → deploy/scripts/gb-host-rdma-route.sh(host NCCL 测试用)。
###############################################################################
# 开机校验区 —— 【2026-08-08 从一次性 gate 移出,改为每 boot 执行】
#
# 这三段(原 [4] / [6] / [6b])此前在 `if [ ! -f $INIT_STAMP ]` 内,只在首启跑一次。
# 移出的理由:首启校验只能发现【镜像配错】,发现不了【运行时退化】——
# 而 hugepages 恰恰是最容易退化的一项(生产 taiji 那批就是重启后归零,
# 见 2026-08-08 只读排查:service 因 /usr/local 挂载竞态 203/EXEC,重启即 0)。
#
# 三段都【只读】:不写任何配置、不装任何东西。缺失时 warn_section 记入
# /etc/.customer-init-failures 并继续,不终止脚本。
#
# ⚠️ 时序:本区在 startup script 末尾执行(约 boot +130s 之后)。
# configure-numa-hugepages.service 内部最多等 120s(等 GPU 显存 NUMA node 上线),
# 正常情况下此时已完成。若打印的页数偏低而 service 仍在 activating,不是故障 ——
# 以 systemctl 状态为准,或稍后重查。
###############################################################################
#############################################################################
# [4] 2MB Hugepages —— 【2026-08-08 起改为只校验,安装已烤入镜像】
#
# 安装动作搬到了 v21/v22 构建脚本的 [7e] 段(configure-numa-hugepages.sh +
# 同名 unit + 旧名 gb300-hugepages.sh 的 symlink)。本段不再安装,只核实镜像里有、
# 且 enabled、且旧名 symlink 有效。
#
# ⚠️ 本段同时是【新脚本配旧镜像】的错配检测器:配 2026-08-08 之前构建的 v21/v22
# (未烤入 [7e])会在这里报 MISSING —— 那种组合下 hugepages 恒 0,
# kubelet capacity=0 → asapd-lite 恒 Pending → 节点拿不到 GUA,而机器表面完全正常。
#
# 给存量机器补装用 scripts/install-hugepages-service.sh(运行时写文件 = 单副本,
# 没有镜像烤入那份的双副本保护 —— 理由见构建脚本 [7e] 段注释)。
#
# ↓↓↓ 原安装逻辑整段保留为注释:它是镜像里那份的【对照基准】,改镜像时要比对 ↓↓↓
#############################################################################
echo "=== [4] Hugepages 校验(安装已烤入镜像,本段不安装)==="
HP_UNIT=/etc/systemd/system/configure-numa-hugepages.service
HP_SH=/usr/local/sbin/configure-numa-hugepages.sh
if [ -f "$HP_UNIT" ] && [ -x "$HP_SH" ]; then
echo " OK 镜像已烤入 configure-numa-hugepages.service + configure-numa-hugepages.sh"
echo " enabled=$(systemctl is-enabled configure-numa-hugepages.service 2>&1) active=$(systemctl is-active configure-numa-hugepages.service 2>&1)"
# 旧名必须解析到真身。两边 unit 同名而 ExecStart 可能写不同文件名,谁后写谁生效 ——
# symlink 是防 203/EXEC 的那道保险,缺了不报错但会在别人推 unit 时静默归零。
if [ "$(readlink -f /usr/local/sbin/gb300-hugepages.sh 2>/dev/null)" = "$HP_SH" ]; then
echo " 旧名 symlink OK (gb300-hugepages.sh → configure-numa-hugepages.sh)"
else
echo " !! 旧名 symlink 缺失或指向别处 —— 若有人推同名 unit 会 203/EXEC"
warn_section "[4] hugepages 旧名 symlink" 1
fi
# 期望 8192 = 2 个【CPU】NUMA x 4096。GPU 显存 NUMA(node2/10/18/26)应为 0:
# 那 32 GiB 实测无人使用(used=0 / asapd-lite maps 无 hugetlbfs),白占每卡 8 GiB。
cat /sys/devices/system/node/node*/hugepages/hugepages-2048kB/nr_hugepages 2>/dev/null \
| awk '{s+=$1} END{print " 当前 2M 页总数="s+0" (期望 8192 = 2 CPU NUMA x 4096)"}' || true
else
echo " !! MISSING 镜像里没有 hugepages service"
echo " 本脚本(2026-08-08 起)必须配同日或之后【重建】的 v21/v22 镜像。"
echo " 后果:hugepages 恒 0 → kubelet capacity=0 → asapd-lite 恒 Pending、无 GUA。"
echo " 补救:sudo bash scripts/install-hugepages-service.sh"
warn_section "[4] hugepages(镜像未烤入 [7e])" 1
fi
# # [4] 2MB Hugepages —— 安装 systemd service(v6.2 改;分配动作交给它每 boot 执行)
# # 这里只做「安装 + enable + 首次 start」,属一次性动作,故仍在 one-time gate 内。
# # 为什么不能像 v6.1 那样直接写 nr_hugepages:见本文件 v6.2 changelog 第 15 条。
# # 2026-08-10 起脚本名统一为 configure-numa-hugepages.sh(与 unit 同名、与客户
# # 生产一致),旧名 gb300-hugepages.sh 留 symlink;分配范围改为只给 CPU NUMA。
# #############################################################################
# echo "=== [4] Hugepages: 安装 configure-numa-hugepages.service ==="
#
# cat >/usr/local/sbin/configure-numa-hugepages.sh <<'HPEOF'
# #!/bin/bash
# # 给每个【有 CPU 的】NUMA node 分配 2MB hugepages;GPU 显存 NUMA 显式清零。
# # 每 boot 由 configure-numa-hugepages.service 调用。
# #
# # GB300 上 34 个 NUMA node 里只有 6 个有内存:node0/node1 是 CPU 内存(各约 480 GB),
# # 另外 4 个各约 283 GB 是 GPU 显存(coherent memory),要等 nvidia 驱动加载后才上线。
# #
# # 2026-08-08 起【只给 CPU NUMA 分配】:GPU 显存上那 32 GiB 实测无人使用
# # (used=0 / Rsvd=0 / asapd-lite maps 无 hugetlbfs),而 8 张 CX-8 全挂在 CPU NUMA。
# # kubelet 未配 topologyManager ⇒ capacity 按全节点总和算,2×4096×2MiB=16 GiB
# # 仍是 asapd-lite 需求(8 GiB)的两倍。
# #
# # ⚠️ 仍然要等 NUMA 拓扑稳定:GPU node 上线晚,不等的话【无法把它们显式清零】
# # (在线改配置的场景下它们可能还留着上一版的 4096)。
# # ⚠️ GPU NUMA 用【显式写 0】而不是 continue 跳过 —— 跳过的话存量分配不会被回收。
# # ⚠️ 判 CPU NUMA 必须用 `[ -n "$(cat cpulist)" ]`,不能用 `[ -s cpulist ]`:
# # sysfs 该文件 size 恒为 65536,与内容无关,用 -s 筛等于没筛。
# set -u
# PAGES="${HUGEPAGES_PER_NODE:-4096}"
# MAX="${HUGEPAGES_WAIT_MAX:-120}"
#
# mem_node_count() {
# local c=0 d m
# for d in /sys/devices/system/node/node[0-9]*; do
# [ -r "$d/meminfo" ] || continue
# m=$(awk '/MemTotal/{print $4; exit}' "$d/meminfo" 2>/dev/null)
# [ "${m:-0}" -gt 0 ] 2>/dev/null && c=$((c+1))
# done
# echo "$c"
# }
#
# prev=-1; stable=0; t=0; n=0
# while [ "$t" -lt "$MAX" ]; do
# n=$(mem_node_count)
# if [ "$n" = "$prev" ] && [ "$n" -gt 0 ]; then
# stable=$((stable+1)); [ "$stable" -ge 3 ] && break
# else
# stable=0
# fi
# prev="$n"; sleep 2; t=$((t+2))
# done
# echo "有内存的 NUMA node: ${n} 个(等待 ${t}s,上限 ${MAX}s)"
#
# ok=0; bad=0; zeroed=0
# for d in /sys/devices/system/node/node[0-9]*; do
# f="$d/hugepages/hugepages-2048kB/nr_hugepages"
# [ -w "$f" ] || continue
# m=$(awk '/MemTotal/{print $4; exit}' "$d/meminfo" 2>/dev/null)
# [ "${m:-0}" -gt 0 ] 2>/dev/null || continue
# if [ -n "$(cat "$d/cpulist" 2>/dev/null)" ]; then want="$PAGES"; else want=0; fi
# cur=$(cat "$f" 2>/dev/null)
# [ "${cur:-0}" = "$want" ] || echo "$want" >"$f" 2>/dev/null
# # 内核对 nr_hugepages 是【尽力分配】:写入不报错,但实得可能少于请求,必须回读校验
# got=$(cat "$f" 2>/dev/null)
# if [ "${got:-0}" = "$want" ]; then
# if [ "$want" = "0" ]; then zeroed=$((zeroed+1)); else ok=$((ok+1)); fi
# else
# bad=$((bad+1)); echo " WARN $(basename "$d"): 请求 ${want} 实得 ${got:-0}"
# fi
# done
# total=$(cat /sys/devices/system/node/node*/hugepages/hugepages-2048kB/nr_hugepages 2>/dev/null | paste -sd+ - | bc)
# echo "结果:CPU NUMA ${ok} 个足额、GPU NUMA ${zeroed} 个已清零、${bad} 个不符,总计 ${total:-0} 页 ≈ $(( ${total:-0} * 2 / 1024 )) GiB"
#
# mkdir -p /dev/hugepages
# mountpoint -q /dev/hugepages || mount -t hugetlbfs none /dev/hugepages 2>/dev/null
# exit 0
# HPEOF
# chmod +x /usr/local/sbin/configure-numa-hugepages.sh
# ln -sfn /usr/local/sbin/configure-numa-hugepages.sh /usr/local/sbin/gb300-hugepages.sh
#
# cat >/etc/systemd/system/configure-numa-hugepages.service <<'UNITEOF'
# [Unit]
# Description=GB300 2MB hugepages allocation (per NUMA node)
# Documentation=file:///usr/local/sbin/configure-numa-hugepages.sh
# # GPU 显存作为 NUMA node 上线依赖 nvidia 驱动;脚本内部还会再轮询等待。
# After=local-fs.target nvidia-persistenced.service
# Wants=nvidia-persistenced.service
# # kubelet 只在启动时读一次 hugepages capacity 并上报。晚于它分配的话节点 capacity
# # 仍是 0,请求 hugepages 的 pod(如 asapd-lite limits.hugepages-2Mi=8Gi)照样调度不上。
# Before=kubelet.service containerd.service
#
# [Service]
# Type=oneshot
# RemainAfterExit=yes
# ExecStart=/usr/local/sbin/configure-numa-hugepages.sh
#
# [Install]
# WantedBy=multi-user.target
# UNITEOF
#
# systemctl daemon-reload
# systemctl enable configure-numa-hugepages.service >/dev/null 2>&1
# systemctl start configure-numa-hugepages.service || true
# echo " configure-numa-hugepages.service 已安装并启动:"
# systemctl is-enabled configure-numa-hugepages.service 2>/dev/null | sed 's/^/ enabled=/'
# cat /sys/devices/system/node/node*/hugepages/hugepages-2048kB/nr_hugepages 2>/dev/null \
# | paste -sd+ - | bc | sed 's/^/ 总页数=/'
#############################################################################
# [6] sshd 端口 —— 【2026-08-08 起改为只校验,不写任何配置】
#
# ⚠️ 2026-08-08 实测更正(mintivy-v21 / regalivy-v22 两台交叉验证):
# 镜像里的 /etc/ssh/sshd_config.d/00-gb-dualstack.conf 是【死文件】——
# TencentOS 的 /etc/ssh/sshd_config 【没有 Include 指令】(两台实测
# `grep -ci '^[[:space:]]*Include'` 均为 0),该 drop-in 从未被任何 daemon 读过。
#
# 22 / 56000 实际由【两个独立 daemon】提供:
# sshd.service 无 -f,读主文件 → 22(主文件无 Port 行时用 OpenSSH 默认 22)
# sshd-56000.service -f /etc/ssh/sshd_config.l → 56000
#
# ⇒ 本段往主文件插 Port 行在功能上确实【冗余】(端口本来就有 daemon 提供),
# 但此前注释里「因为 drop-in 已烤入所以冗余」这个【归因是错的】,已更正。
#
# ⚠️ 判据不能用 `sshd -T`:它只解析主文件(无 Include),【结构上永远看不到 56000】,
# 拿它判会恒假 —— 每 boot 往 FAIL_LEDGER 写一条假失败,淹没真信号。
# 改判「谁在监听」+「能否握手」,这两条与配置文件长什么样无关。
#
# ↓↓↓ 原写入逻辑整段保留为注释 ↓↓↓
#############################################################################
echo "=== [6] sshd 端口校验(由镜像内多个 sshd daemon 提供,本段不改配置)==="
SSHD_MISS=0
# 判据一:谁在监听。`:22[[:space:]]` 精确到端口,避免 5622 之类误匹配。
SSHD_LISTEN=$(ss -lntpH 2>/dev/null | grep sshd || true)
for p in 22 56000; do
if printf '%s\n' "$SSHD_LISTEN" | grep -qE ":${p}[[:space:]]"; then
echo " OK sshd 在监听 $p"
else
echo " !! MISSING 没有 sshd 在监听 $p"
SSHD_MISS=$((SSHD_MISS + 1))
fi
done
# 判据二:能否握手。banner 仅 ~21 字节,必须 `head -1` —— 用 `head -c N` 会等够 N 字节而阻塞。
for p in 22 56000; do
B=$(timeout 5 bash -c "exec 3<>/dev/tcp/127.0.0.1/$p && head -1 <&3" 2>/dev/null | tr -d '\r' || true)
case "$B" in
SSH-*) echo " OK $p 握手正常: $B" ;;
*) echo " !! $p 握手失败: ${B:-<无响应>}"; SSHD_MISS=$((SSHD_MISS + 1)) ;;
esac
done
echo " sshd 进程: $(pgrep -c sshd 2>/dev/null || echo 0) 个; units: $(systemctl list-units --type=service --no-legend 2>/dev/null | grep -ci ssh || echo 0)"
[ "$SSHD_MISS" -eq 0 ] || warn_section "[6] sshd 端口" "$SSHD_MISS"
# #############################################################################
# # [6] sshd ports 22 + 56000
# #############################################################################
# echo "=== [6] sshd port 22 + 56000 ==="
# SSHD_CHANGED=0
# if ! grep -q '^Port 22' /etc/ssh/sshd_config; then
# sed -i '1i Port 22' /etc/ssh/sshd_config
# SSHD_CHANGED=1
# fi
# if ! grep -q '^Port 56000' /etc/ssh/sshd_config; then
# sed -i '/^Port 22/a Port 56000' /etc/ssh/sshd_config
# SSHD_CHANGED=1
# fi
# if grep -q '^AddressFamily inet6' /etc/ssh/sshd_config; then
# sed -i 's/^AddressFamily inet6$/AddressFamily any/' /etc/ssh/sshd_config
# SSHD_CHANGED=1
# fi
# if [ "$SSHD_CHANGED" -eq 1 ]; then
# # v6.1: restart 失败不再打死脚本(否则后面的 Calico 模块 + [1] 网卡改名全不跑)。
# # 注意这里失败是有分量的:sshd 起不来会丢 SSH,所以要显式记账而不是 `|| true` 一笔带过。
# if systemctl restart sshd; then
# echo "sshd now listening on ports 22 and 56000 (AddressFamily set to any)"
# else
# warn_section "[6] sshd restart" "$?"
# sshd -t 2>&1 | head -5 || true
# fi
# else
# echo "sshd ports 22 and 56000 already configured"
# fi
# [7] Mellanox MRDMA host route —— 已抽出到 deploy/scripts/gb-host-rdma-route.sh
# (默认关,仅 host 直跑 NCCL 测试用;生产 TKE 由 pod/asapd-lite 负责,不需要)。
#############################################################################
# [6b] Calico 内核模块 —— 【2026-08-08 起改为只校验,已烤入镜像 [7e]】
# /etc/modules-load.d/{vxlan,ipip}.conf 由 v21/v22 镜像提供。
# 缺失【不就地补写】—— 那会把「镜像到底烤没烤」这个事实掩盖掉。
# ↓↓↓ 原逻辑保留为注释 ↓↓↓
#############################################################################
echo "=== [6b] Calico 内核模块校验(已烤入镜像,本段不写)==="
MISSING_MOD=0
for m in vxlan ipip; do
if [ -f "/etc/modules-load.d/$m.conf" ]; then
if lsmod | grep -qE "^$m "; then st="已加载"; else st="未加载(下次 boot 由 systemd-modules-load 加载)"; fi
echo " OK /etc/modules-load.d/$m.conf 存在,当前 $st"
else
echo " !! MISSING /etc/modules-load.d/$m.conf —— 镜像未烤入 [7e]"
MISSING_MOD=$((MISSING_MOD + 1))
fi
done
[ "$MISSING_MOD" -eq 0 ] || warn_section "[6b] Calico 模块(镜像未烤入 [7e])" "$MISSING_MOD"
# # [6b] Load networking modules for Calico (VXLAN / IPIP)
# #############################################################################
# echo "=== [6b] Loading networking modules (Calico vxlan/ipip) ==="
# modprobe vxlan || true
# modprobe ipip || true
# echo "vxlan" > /etc/modules-load.d/vxlan.conf
# echo "ipip" > /etc/modules-load.d/ipip.conf
echo "=== Customer Initialization Complete (v7.0: [5] 改为 metadata 策略注入,不再写 lustre.conf) ==="
H. 首次交付一次性前置资源
以下 VPC / 子网 / RDMA network profile / placement policy 均为一次性资源:首次交付创建一次,之后每次开机 / 扩容(§2.1)只需引用,无需重建。若环境已预置(本项目 sub-block 的 placement policy 已由平台预设),核实存在后直接引用,不要重复创建。GB200 与 GB300 的前置资源有差异,分列如下。
| 资源 | GB200(us-east1-d,VM) | GB300(us-central1-b,裸金属) | 频率 |
|---|---|---|---|
| VPC 网络 | 2×GVNIC(MTU 8896)+ 1×RDMA | mgmt(MTU 1500)+ lustre(MTU 8896)+ 1×RDMA | 一次性 |
| RDMA network profile | us-east1-d-vpc-roce(非 metal) | us-central1-b-vpc-roce-metal(裸金属) | Google 预置只读,不创建 |
| RDMA 子网 | 手建 4 个 IPv4 rail 子网 | profile 自动生成 IPv6-only 单子网,禁手建 | GB200 一次性 / GB300 自动 |
| placement policy | COLLOCATED + 1x72 | COLLOCATED + 1x72(相同) | 一次性 |
| 防火墙规则 | GVNIC 网 | mgmt / lustre 网(RDMA 由 profile 托管) | 一次性 |
| 建实例(§2.1) | bulk create | bulk create | 每次开机 / 扩容 |
H.1 VPC 网络
GB300:
gcloud compute networks create <mgmt-net> --project=<P> --subnet-mode=custom --mtu=1500 # 管理网
gcloud compute networks create <lustre-net> --project=<P> --subnet-mode=custom --mtu=8896 # Lustre 网
# RDMA 网:引用 network profile(见 H.3);勿加 --enable-ula-internal-ipv6(profile 已定义 ULA 段,重复会报错)
gcloud beta compute networks create <rdma-net> --project=<P> \
--network-profile=us-central1-b-vpc-roce-metal --subnet-mode=custom
GB200:
gcloud compute networks create <gvnic-net-0> --project=<P> --subnet-mode=custom --mtu=8896 # 主 GVNIC
gcloud compute networks create <gvnic-net-1> --project=<P> --subnet-mode=custom --mtu=8896 # 辅 GVNIC
gcloud beta compute networks create <rdma-net> --project=<P> \
--network-profile=us-east1-d-vpc-roce --subnet-mode=custom
H.2 子网
GB300——mgmt / lustre 手建;RDMA 子网由 profile 自动生成 default-subnet-1-<rdma-net>(IPv6-only,8 张 MRDMA 网卡共用),手建会报 SUBNETWORK_CREATION_BLOCKED,只需核实:
gcloud compute networks subnets create <mgmt-sub> --project=<P> --network=<mgmt-net> --region=us-central1 --range=<mgmt-cidr>
gcloud compute networks subnets create <lustre-sub> --project=<P> --network=<lustre-net> --region=us-central1 --range=<lustre-cidr>
# RDMA 子网自动生成,勿手建,仅核实:
gcloud compute networks subnets list --project=<P> --network=<rdma-net>
# no-address 的 VM 需访问 Google API / Artifact Registry → 给 mgmt/lustre 子网开 Private Google Access:
gcloud compute networks subnets update <mgmt-sub> --project=<P> --region=us-central1 --enable-private-ip-google-access
gcloud compute networks subnets update <lustre-sub> --project=<P> --region=us-central1 --enable-private-ip-google-access
GB200——GVNIC×2 与 RDMA 的 4 个 IPv4 rail 子网全部手建(rail-optimized:每张 RDMA 网卡一个独立子网,对应 §2.1 建机命令的 -sub-0..3):
gcloud compute networks subnets create <gvnic-sub-0> --project=<P> --network=<gvnic-net-0> --region=us-east1 --range=<gvnic-cidr-0>
gcloud compute networks subnets create <gvnic-sub-1> --project=<P> --network=<gvnic-net-1> --region=us-east1 --range=<gvnic-cidr-1>
RDMA_CIDRS=(10.0.16.0/22 10.0.20.0/22 10.0.24.0/22 10.0.28.0/22) # 4 条 rail 网段
for n in 0 1 2 3; do
gcloud compute networks subnets create <rdma-net>-sub-${n} --project=<P> \
--network=<rdma-net> --region=us-east1 --range=${RDMA_CIDRS[$n]}
done
H.3 RDMA network profile(理解,不创建)
- profile 由 Google 按 zone / 机型预定义:
gcloud compute network-profiles仅提供describe/list(无create/delete),按现成名引用即可。 - 名称与机型 / zone 强绑定,不可替换:GB300 =
us-central1-b-vpc-roce-metal(裸金属),GB200 =us-east1-d-vpc-roce(非 metal)。 - 作用:承载 GPU-to-GPU 的 RoCE 高速 fabric。GB300 的 profile 预置 IPv6-only 段并在建 RDMA VPC 时自动生成、指派子网(故建网后子网即就绪,8 张 CX-8 网卡共用同一子网);GB200 的 profile 不自动生成子网,需按 H.2 手建 4 个 IPv4 rail 子网。
- 查看:
gcloud compute network-profiles describe <profile> --zone=<zone> --project=<P> - 官方文档:RDMA network profiles · network-profiles CLI · A4X Max 建机(单子网多网卡)
H.4 placement policy(紧凑放置)
- 类型:group-placement,
--collocation=COLLOCATED+--gpu-topology=1x72。GB200 与 GB300 完全相同——一个 NVL72 域(18 节点 × 4 GPU)绑一条 policy。 - 作用:强制同域 18 台落到物理紧邻机架(同 sub-block),启用 NVSwitch 全互联;拓扑不匹配会导致 NCCL 跨域 fallback 严重降速(故重建须复用同一 policy,见 §2.3)。
- 一次性创建(每个 sub-block 一条,策略名对齐 sub-block 编号;平台已预置则跳过,直接引用):
# <REGION>:GB300=us-central1 / GB200=us-east1
gcloud compute resource-policies create group-placement <PREFIX>-nvl72-policy-<DDDD> \
--project=<P> --region=<REGION> --collocation=COLLOCATED --gpu-topology=1x72
# 查现有(取名 / 核实):
gcloud compute resource-policies list --project=<P> --filter="name~nvl72-policy"
- 建机时引用:
--resource-policies=<PREFIX>-nvl72-policy-<DDDD>(见 §2.1)。 - 与 1x72 MIG workload policy 区分:后者是 MIG(§4.1)场景新建的 workload policy,用途不同,勿混用(MIG 的可订性受预留可订容量与
maintenanceStatus约束,与单机 / bulk 一致,详见 §4.1)。 - 官方文档:Compact placement policies · resource-policies CLI
H.5 防火墙规则
GB300(作用于 mgmt / lustre 网;RDMA 网防火墙由 profile 托管,无需手建):
# IAP SSH(22/56000,来源为 IAP 网段)
gcloud compute firewall-rules create <PREFIX>-allow-iap-ssh --project=<P> --network=<mgmt-net> \
--direction=INGRESS --priority=900 --action=ALLOW --rules=tcp:22,tcp:56000 --source-ranges=35.235.240.0/20
# 管理网 / Lustre 网内部互通
gcloud compute firewall-rules create <PREFIX>-allow-internal-mgmt --project=<P> --network=<mgmt-net> \
--direction=INGRESS --priority=1000 --action=ALLOW --rules=all --source-ranges=<mgmt-cidr>
gcloud compute firewall-rules create <PREFIX>-allow-internal-lustre --project=<P> --network=<lustre-net> \
--direction=INGRESS --priority=1000 --action=ALLOW --rules=all --source-ranges=<lustre-cidr>
GB200(作用于 GVNIC 网):
gcloud compute firewall-rules create <PREFIX>-allow-iap-ssh --project=<P> --network=<gvnic-net-0> \
--direction=INGRESS --priority=900 --action=ALLOW --rules=tcp:22,tcp:56000 --source-ranges=35.235.240.0/20
gcloud compute firewall-rules create <PREFIX>-allow-internal-gvnic --project=<P> --network=<gvnic-net-0> \
--direction=INGRESS --priority=1000 --action=ALLOW --rules=tcp,udp,icmp --source-ranges=<gvnic-cidr>,<pod-cidr>
RDMA 网防火墙由 network profile 托管,无需手建。若组织策略会自动删除防火墙规则,每次 SSH 前需核实规则仍在。
参考:VPC 网络创建 · Private Google Access · 防火墙规则 · A4X 批量建机(UI)