把机房最脏的那段活做成流水线:裸金属到可调度算力的交付链路拆解
把机房最脏的那段活做成流水线:裸金属到可调度算力的交付链路拆解
一台 GPU 服务器从机柜上电,到成为 kubectl get nodes 里一个 Ready 的对象,中间隔着的不是一条命令,而是一串几乎没人愿意写进 PPT 的工作:装机、配 kernel flavor、装 DOCA 版 Open vSwitch、掩掉会和 kubelet 抢 daemon-reload 的 apt 定时器、把 multipathd 关掉免得它抢走 iSCSI 卷、绑定 TPM、等 cloud-init 真的跑完、在一个节点上 kubeadm init、再把其余控制面节点一个一个放进去。
社区里大量"自建 GPU 集群"的经验文章,最终都收敛到同一句话:先单机、再集群、混合算力。这句话在工程上是对的,但它描述的其实是一种人的操作顺序——先在一台机器上把驱动、CUDA、容器运行时、kubelet 全部手工调通,再把这台机器的状态复制到其他机器。它没有回答一个更麻烦的问题:当集群不是一台,而是每个租户一套独立控制面、每天创建和销毁的时候,这套顺序还能不能被执行。
NVKE(NVIDIA Kubernetes Engine)给出的答案是:把整条链路拆成两类东西——镜像里烘死的、可验证的静态契约,和由持久化工作流驱动的、可重放的动态步骤。前者解决"机器起来时就已经是对的",后者解决"后续每一步失败了都不至于把机器变成垃圾"。
本文基于仓库源码,逐段拆解这条链路,并说明它在顺序上和社区常见路径究竟差在哪里。
被省略的中间层:一条裸金属要跨过多少道关
先看一个最容易被忽略的前提。NVKE 的参考节点镜像规范里写得很直白:
This is the contract an OS image must satisfy for NVKE to manage a node. It is not a cluster-ready Kubernetes image: kubeadm and GPU drivers are installed later through
nvke-agent.
也就是说,镜像出厂时故意不带 kubeadm、kubelet、containerd、GPU 驱动。这个取舍很反直觉——大部分人做裸金属自动化,第一反应是把所有东西都烤进镜像,让机器一上电就是"完整体"。NVKE 反过来做,原因藏在 镜像契约 那张"必须有"的表里:那些条目几乎全是和硬件、和内核、和 systemd 时序强耦合的东西,一旦烤进镜像就必须随节点型号变化,而 kubeadm 那套东西是版本化的、需要按 Kubernetes 版本组合的。
这张表里的内容,正是"机房最脏的那段活"的清单:
- 内核不能是 generic。必须用 Ubuntu 的 NVIDIA 调优内核(amd64 上是
linux-nvidia;arm64 上 26.04 用linux-nvidia-64k-hwe-26.04,24.04 用linux-nvidia-64k),并且是通过 autoinstall 的kernel.package在 curtin 安装阶段直接指定,让 generic 内核根本没有落到磁盘上的机会。Vera Rubin 平台还要求 26.04 arm64 那条独立的linux-image-*-nvidia-bos-64k内核线。 - multipathd 必须 mask。Ubuntu Server 安装器默认把它开着,而它没有 blacklist 时会去认领 Longhorn 通过 iSCSI 导出的卷(呈现为
IET,VIRTUAL-DISK),结果是mkfs报is apparently in use by the system; will not make a filesystem here,新供给的卷永远格式化不了。 - apt 定时器必须 mask。
apt-daily.timer、apt-daily-upgrade.timer、unattended-upgrades.service全要关。理由极其具体:这些任务会在首次启动几分钟后触发,重启 journald、networkd、udevd,而如果正好撞上 kubeadm 的kubelet-start阶段执行systemctl daemon-reload,kubelet 就再也起不来,这个节点的 init 或 join 就丢了。所以镜像的立场是"节点只通过换镜像升级,永不原地升级"。 - etcd 数据目录要预建。
/var/lib/etcd以0700存在,属于一个在构建时创建的系统etcd用户和组,这样 kubeadm 会复用它而不是自己建一个root:root的目录——后者正是 CIS 1.1.12 检查的那一项。 - conntrack 上限要按开机时的实际内存算。
conntrack-tune.service在systemd-modules-load.service之后、systemd-sysctl.service之前运行,把nf_conntrack_max和nf_conntrack_buckets提到min(max(RAM_MiB × 64, 1024), 600000),并且只写"需要提高"的键。写进/run/sysctl.d/,因为/run每次开机清空——这个值必须来自正在启动的那台机器的内存,而不是构建镜像的那台 VM 的内存。
最后一条尤其能说明问题:这类参数一旦在镜像里写死常量,就会在某个机型上安静地错掉,而且错得很隐蔽。镜像契约里甚至专门用一张表说明 Calico 和 OVN-Kubernetes 两种 CNI 下 nf_conntrack_max 的最终归属——kube-proxy 每次启动都会按 CPU 数(不是内存)重算并覆盖,所以在 18 核及以下的 Calico 节点上,镜像设的 600000 会被压到 262144。这种知识不可能靠"一键脚本"传递,只能靠一份被人持续维护的契约文档加一套验证工具(nvke-os-image-check)。
而这些,全部发生在云初始化(cloud-init)之前。镜像规范还明确列了"不能烘进镜像"的东西:SPIRE server 地址、trust domain、trust bundle、join token。它们属于实例身份,只能由首次启动的 user data 注入。管理集群节点的 user data 长这样(摘自 准备节点):
#cloud-config
write_files:
- path: /etc/nke/spire.env
permissions: "0600"
content: |
SPIRE_SERVER_ADDRESS=<BOOTSTRAP_HOST_IP>
SPIRE_SERVER_PORT=30081
SPIRE_TRUST_DOMAIN=<TRUST_DOMAIN>
- path: /etc/nke/trust-bundle.pem
permissions: "0644"
content: |
<SPIRE_CA_CERT_PEM>
runcmd:
- DEBIAN_FRONTEND=noninteractive apt-get install -y nvke-kubeadm-distro-<K8S_VERSION>
- DEBIAN_FRONTEND=noninteractive apt-get install -y nvke-cni-ovn-images-2.4.2 nvke-cni-ovn-charts-2.4.2
注意 runcmd 的顺序被文档明确要求:先装 Kubernetes 包,再装 CNI 镜像包,因为后者要把镜像灌进 containerd,而 containerd 由前者提供。这种依赖关系就是"中间层"的真面目——它不是某个大步骤,而是几十个有先后约束的小步骤,每一个都有独立的失败模式。
上线之后第一件事:判断"到底跑完了没有"
有一个细节值得单独拎出来,因为它几乎所有人都踩过:agent 能连上,不等于节点准备好了。
NVKE 的节点侧有一个 ExecuteNodePreflight RPC,专门回答这个问题。它的设计文档 README-NodePreflight.md 把动机写得很清楚:
The NVKE controller gates first on agent reachability. That is necessary but insufficient: cloud-init may still be running
runcmdsteps (package installs, sysctl, service restarts) after the agent starts. Proceeding too early produces flaky kubeadm preflight failures or half-configured nodes.
实现上有两处很见功力。第一处是判断 cloud-init 的退出码:
const cloudInitStatusRecoverableExitCode = 2
cloud-init status 返回 2 表示"degraded",即它完成了工作但记录了警告——这依然满足"完成"检查,只有退出码 1 才是不可恢复错误。第二处是命令用了 --long,代码注释里给了原因:某次 CI 运行 Run 37745107586 在这一个检查上重试了 44 次、耗时 90 分钟,每次都只报 status: error,说不清是哪一段失败,而节点随后就被释放了,没人能再上去查。加上 --long 之后,失败阶段和它的消息会一起上报到控制器。
解析逻辑也做了防御:只认第一行以 status: 开头的行,因为 --long 后面的自由文本里可能出现任何词,包括另一个 "status"。并且在有 /var/lib/dsxos/.cidata-consumed 这个标记文件时直接短路成功。
控制器的侧对应实现在 node_preflight.go,还有一个版本门槛:
const minCloudInitStatusPreflightVersion = "0.1.24"
早于这个版本的 agent 没有 CheckCloudInitStatus 字段,所以对老节点只能退化成"检查连通性",跳过严格校验。这个处理方式很务实——它承认了节点上的软件是会版本漂移的,而编排层必须兼容漂移。
顺带一个容易漏的分支:如果节点是 Docker Machine 支撑的(本地评测用的 CAPD),它根本没有 cloud-init,检查项被替换成 /run/cluster-api/bootstrap-success.complete 这个文件是否存在。同一条流水线,两种底座,各自有各自的"完成信号"。
顺序的差异:不是先单机再集群,而是先声明集群、让节点各自收敛
这才是 NVKE 与社区经验路径真正的分歧点。
社区路径的隐含前提是:集群是我手动拼出来的,所以顺序必然是"机器 A 调通 → 机器 A 变成 master → 机器 B 加入 → 机器 C 加入"。这个顺序的优点是每一步都能亲眼看到结果,缺点是它无法并发,也无法在中途失败后自动恢复——因为状态在人的脑子里。
NVKE 的顺序反过来了。看 provision_cluster.go 的主干:
if err := provisionCAPIClusterResources(ctx, input.ClusterID); err != nil { ... }
// Wait for one of the control plane nodes to be ready to join, choose it as the initial node
initialNodeID, err := waitForControlPlaneNodeReadyToJoin(ctx, input.ClusterID)
if err := configureInitialNodeKubeVip(ctx, input.ClusterID, initialNodeID); err != nil { ... }
// Create the cluster with a single node -- remaining CP nodes join via JoinNode
if err := kubeadmInitWithCNI(ctx, input.ClusterID, initialNodeID); err != nil { ... }
第一步不是碰机器,而是创建 Cluster API 资源。也就是说,集群的期望形态先被声明出来(几个控制面、哪些 node pool、用哪个 instance type),然后由 CAPI 和基础设施提供者(NICo)去把机器凑齐,编排器只是在一旁等"有一台控制面节点进入了 ReadyToJoin"。
而且这个"等"的时间预算给得很有意思:
StartToCloseTimeout: 1 * time.Hour, // Includes waiting for Forge instances to be SSH-able, so can be 40+ minutes
注释直接承认了裸金属的现实:机器从被申请到能连上,可能要四十多分钟。这不是软件慢,是 BMC、固件、PXE、装机、首次启动加起来就是这么慢。任何把超时设成 5 分钟的流水线,在真实机房里都会失败。
节点侧的流水线在 provision_node.go,它的阶段划分本身就是一条产线节拍:
| 阶段 | 做什么 | 谁来做 |
|---|---|---|
capi_create |
创建 CAPI Machine,等待基础设施分配机器 | 控制器 → CAPI → NICo |
capi_ready |
等 CAPI Machine 就绪 | 控制器 |
host_preparation |
收敛 agent 版本 → 节点 preflight → 取配置档 → 跑 before-join runbook → 配 CNI 前置(OVS 网桥) | agent gRPC + runbook |
reboot |
可选的重启并等待 uptime 确认 | agent |
join |
kubeadm join |
agent |
post_join |
打标签、应用 metadata、校验控制面角色标签、after-join runbook、配 kube-vip、摘除 taint | 控制器 + agent |
这些阶段名不是文档里的装饰,它们是真正上报到指标系统的:代码里通过 metrics.RecordProvisionPhase(cluster, nodeType, phase, duration) 记录,并且用 workflow.IsReplaying(ctx) 做了保护——重放历史时不上报指标,否则一次 worker 重启就会把整条历史重新计一遍,指标立刻失真。这是把"工作流引擎"和"可观测性"接在一起时最容易写错的一行。
控制面节点和工作节点的分流同样体现在这里。ProvisionNodeInput 里有个 SkipJoin:
// SkipJoin leaves the host at ReadyToJoin without running kubeadm join.
// Control-plane nodes set this true so the control-plane controller can
// start JoinNode one node at a time. Workers leave it false (auto-join).
控制面节点必须一个一个加,因为每次 join 都要改 etcd membership;工作节点则可以在自己的 ProvisionNode 里内联 join,失败无限重试(joinMaximumAttempts = 0),而控制面那条路只允许单次尝试(MaximumAttempts: 1),把重试预算交给上层的 JoinNode 工作流——重试次数用尽后,控制器换下一个节点先上。
这是一个很值得抄的设计:不是所有重试都该由同一个层负责。让底层无限重试,会让"这台机器就是不行"这个事实永远浮不出来;让底层一次就死,又会让偶发抖动变成节点替换。分离之后,"抖动"和"机器坏了"才分得开。
把特权操作变成契约:agent 的边界
整条链路能成立的前提是:编排器不需要 SSH。
这一点在 准备节点 的端口表里体现得很直接:编排侧只需要 15005(nvke-agent 的 gRPC),节点侧只需要能回连引导主机的 30081。NVKE 的 Day 0 引导文档也明确写着 "no SSH required"。
节点 agent 的自我定位见 agent/docs/DESIGN.md:
the agent turns privileged, node-local imperative operations (kubeadm, apt, disk encryption, static-pod manipulation, script execution) into an authenticated, auditable, idempotent-where-it-matters gRPC API.
"It is not a controller" 这句话同样重要——agent 不 watch API server、不做收敛循环,跨节点顺序完全由控制器拥有。这个切分避免了"两个地方都在改同一台节点"的经典灾难。
几个值得注意的实现约定:
传输与身份。默认 SPIFFE mTLS,agent 校验客户端 SVID 的 trust domain 一致、且 SPIFFE path 以 /nke-service/ 开头;--disable-mtls 只用于开发。每个 unary RPC 都过审计拦截器,记录方法、错误、user-agent、客户端地址。gRPC reflection 也开在同一端口上,所以探测和调用受同一道门保护。
两种结果通道。破坏性操作(比如改静态 Pod 的 apiserver manifest)不在 gRPC 错误码里表达业务结果,而是在响应体里报全所有终态:
OUTCOME_APPLIED / UNCHANGED / FAILED_RESTORED / FAILED_NOT_RESTORED
gRPC 的 InvalidArgument / FailedPrecondition 只用于"请求没被尝试、节点未改变"。区别在于:调用方需要能分清"我把你回滚到原状了"和"我没能确认回滚,请人工介入",而这个区别必须能穿过网络。
异步操作框架。长操作由调用方提供 operation_id 作为幂等键,StartX(operation_id) 立即返回、GetXStatus(operation_id) 轮询;同 ID 重复 Start 幂等,同类型的不同非终态操作被 FailedPrecondition 拒绝;如果 agent 重启时发现一个持久化的非终态操作却没有任何活着的 worker,它会大声拒绝而不是悄悄续跑。这条规则的措辞很克制:"Operations that should resume must be written to recover from persisted state."——也就是说,能续跑是设计出来的能力,不是默认行为。
WAL 式可恢复。etcd 加密密钥轮换在改 encryption-config.yaml 之前先写一个 write-ahead 状态文件,然后阻塞直到本地 apiserver 确认加载了新配置。DeadlineExceeded 被明确标注为"可安全重试",因为 WAL 让重试能跳过一次已经生效的变更。
这些机制的意义不在于优雅,而在于它们让"重试"从一个危险动作变成默认动作——而任何一条要跑四十分钟的裸金属流水线,重试都是唯一现实的失败处理手段。
失败不是异常,是常态:清理比创建更难
真正区分"演示脚本"和"可运维系统"的,是失败之后留下的现场。
kubeadm join 不是幂等的。这一点在 provision_node.go 里被反复处理:
// Skip kubeadm join if it already succeeded in a prior attempt. The join
// changes etcd membership and is serialized across control-plane nodes by the
// control-plane controller ... A retry (e.g. a failed post-join step) must
// therefore never re-run the join, or it could overlap another node's join.
于是先查 Joined condition,已 join 就直接跳到 post-join 阶段。但还有更糟的情况:join 在 etcdctl member add 之后失败——集群里留下了一个投票成员,而机器上什么都没配好。这种成员既不能被 join 重新加入,又会拉高 quorum 风险。所以控制面重试前要跑 cleanBeforeControlPlaneRejoin:先用带类型的 activity 删掉残留的 etcd member,再 kubeadm reset -f,并且显式跳过 remove-etcd-member 阶段(因为上面已经删过了)。
代码里对这段"每次重试都无条件清理"的解释值得一读:它不能靠工作流 attempt 号判断"这是不是重试",因为控制器在重试预算耗尽后会启动一个全新的 JoinNode 工作流,attempt 从 1 重新开始;只有节点/集群状态是可信信号,而无条件清理正好绕开了读状态。两个步骤都是 best-effort,避免一次 agent 抖动把本来能成功的首次 join 弄挂。
仓库自己承认这块还没到位,留了 FIXME:
kubeadm reset belongs in the node-agent, run before every kubeadm join, and is needed for workers too: a worker that partially joins then fails loops on preflight leftovers.
也就是说,当前的控制面侧清理是兜底方案,正确的位置在 agent 里、对所有节点生效。一个开源项目能把自己的临时方案和它的失效边界写得这么清楚,比任何"生产就绪"的宣称都更可信。
同样的思路贯穿到运维态。etcd 密钥轮换如果拥有者节点失联,有一个专门的人工启动工作流 RetireLostEtcdRotationNode:它在保留轮换锁的前提下记录这次有审计的退役,然后只拆那一台节点,让轮换流程能在幸存控制面上继续收敛(retire_lost_etcd_rotation_node.go)。节点替换、drain、lease 续约等待,同样是独立的工作流而不是散落在某个脚本里的步骤。
编排层自举:先造一个一次性的脚手架,再把它拆掉
Day 0 有一个很妙的技巧。nvkectl bootstrap site 并不是直接对节点发命令,而是先在引导节点上起一个临时 Kind 集群,把 Postgres、Temporal、SPIRE、Cluster API 和 NVKE 控制器都部署进去,然后用这个控制器去驱动真实节点的 init 和 join,成功后把 Kind 集群销毁。流程图见 引导概览。
这解决了一个先有鸡还是先有蛋的问题:编排器本身需要一个 Kubernetes 集群才能跑,但用户要的就是一个 Kubernetes 集群。答案是把编排器跑在一个用完就扔的集群里。
它也有代价,仓库写在明面上的代价是:失败时要保留引导集群(--keep-bootstrap-cluster)来排查;而如果用 infra.provider: nico,直接删 Kind 集群会留下一堆已分配但无人管理的 NICo 实例,必须先释放实例。
同样的"自举"逻辑还出现在 pivot 里——管理面从 seed 集群迁移到 site 集群,步骤被显式枚举:
StepCheckCAPI = "check-capi"
StepStopSiteController = "stop-site-controller"
StepSpireHandover = "spire-handover"
StepQuiesceSeed = "quiesce-seed"
StepMoveCAPI = "move-capi"
StepMoveDatabase = "move-database"
StepCopySecrets = "copy-secrets"
StepActivateSite = "activate-site"
StepVerify = "verify"
注意 StepQuiesceSeed —— 在搬数据之前先把 seed 静默,这是典型的"先冻结再迁移"而不是"边跑边搬"。
再往上,管理面自己的创建请求也不直接调 Temporal。架构文档 描述了那个刻意的间接层:POST /api/clusters 在一个数据库事务里同时写 cluster 记录和 workflow_outbox 行,要么都成功要么都不成功;OutboxProcessor 轮询 outbox 表、启动对应工作流、标记已处理。所以"集群记录存在但工作没排上队"这个状态在结构上不存在。
边界:这条流水线在哪里停手
一篇文章如果只讲它做得多完整,可信度反而会打折。NVKE 的边界划得很清楚,而边界本身是设计的一部分。
GPU 驱动和软件栈不在 NVKE 范围内。 dsx-stack.md 明确写着:集群内的 GPU 驱动和软件栈交给 Nodewright + GPU Operator,由 AICR 提供版本锁定的配方;集群就绪认证交给 CRE;工作负载感知的 cordon/drain 和节点替换策略交给 NVSentinel。NVKE 在"OVN-Kubernetes 网络就绪"这一步交接。
这条边界解释了为什么镜像里没有 GPU 驱动却不影响 GPU 节点——驱动是集群生命周期里的一层,不是镜像构建期的一层,它需要随 Kubernetes 版本和 GPU Operator 版本组合,用 AICR 的配方来管理比烤进镜像更可控。
Preview 阶段的能力缺口是公开的。 preview-status.md 里列的限制相当不留情面:
- 管理集群不管理自己——不升级、不扩容、不替换自己的节点;
- 没有管理面升级流程,也没有备份/恢复流程;
- 安装后 API 在 30080 端口上是明文 HTTP 且认证关闭,且 NVKE 不做授权,任何被认证的调用方可以调所有端点;
- 交付给客户的 admin kubeconfig 无法吊销,因为 NVKE 不轮换工作负载集群的 CA;
- FDE 镜像不提供静态数据机密性:每次构建生成一个新卷密钥,但从同一镜像构建的每台节点继承同一个密钥,首次启动只做 TPM 绑定并移除那个公开的引导口令,并不重新加密卷。
最后一条尤其值得警醒:它说明"镜像里带 LUKS"和"数据在静态时是安全的"是两件完全不同的事,而混淆这两件事的成本会在出事那天才显现。
这条链路真正的可复用之处
把 NVKE 的做法抽出来,和社区"先单机再集群"的路径对照,可以归纳成三条可以迁移的经验:
第一,把不变的东西变成可验证的契约,把会变的东西变成可重放的工作流。内核 flavor、conntrack 公式、multipathd 掩码属于前者,它们以文档加检查器(nvke-os-image-check)的形式存在;kubeadm 版本、CNI 版本、加密密钥属于后者,它们由 Temporal 工作流按阶段推进。混在一起做,两种东西都会失控。
第二,顺序上先声明、再收敛,而不是先调通、再复制。先用 CAPI 资源声明集群形态,再等机器到位,再让每台机器各自跑到 ReadyToJoin,最后控制面一台一台 join、工作节点并行 join、全部完成后才摘掉 nvke.nvidia.com/provisioning=true:NoSchedule 这个 taint。taint 放到最后摘,意味着调度器在看到节点之前,节点已经是完整的——而不是"先让节点进来,再慢慢补配置"。
第三,为失败写代码,而不是为成功写文档。kubeadm join 的非幂等、etcd 残留投票成员、agent 重启时未完成的异步操作、cloud-init 与 kubelet 的时序竞争、被释放前来不及排查的节点——这些都不是边缘情况,它们是裸金属交付的日常。把它们写进 cleanBeforeControlPlaneRejoin、写进 WAL、写进 OUTCOME_FAILED_NOT_RESTORED 这样的返回值里,流水线才真的能在机房里跑起来。
机房那段最脏的活不会因为被抽象就变干净。它只是从"某个工程师深夜 SSH 上去敲命令",变成了"一份能被 review、能被重放、失败时会大声说话的代码"。这才是把交付链路做成流水线的实际含义。