NVKE 管理集群 Bootstrap 全流程解析:从 site spec 到自管理控制平面
NVKE 管理集群 Bootstrap 全流程解析:从 site spec 到自管理控制平面
本文以 NVKE(NVIDIA Kubernetes Engine)的站点引导(site bootstrap)为主线,解读 nvkectl bootstrap site 如何把一组已预置的裸金属节点变成自管理(self-managing)的 Kubernetes 管理集群。读完后你将掌握三步引导流程的时间预算与前置条件、临时 Kind 集群的内部编排与回收规则、引导结束后必须立即处理的 etcd 加密密钥,以及后续安装 Cluster API 与基础设施提供者的顺序要求。
一、总览:三个步骤与时间预算
NVKE 的管理集群是一个"自管理"的 Kubernetes 集群——它承载 NVKE 的工作流引擎、数据库与安全服务。引导过程被刻意拆成三步,每一步都有独立的文档与验收标准:
- 准备节点:在所有节点上安装
nvke-agent与 Kubernetes 组件,参见 Pre-Provisioned Nodes。 - 编写 site spec 文件:声明节点、版本与镜像仓库,参见 Configuration。
- 在 init 节点上执行
nvkectl bootstrap site:参见 Pre-Provisioned Nodes。
时间预算方面:三节点站点通常在 10–15 分钟内完成集群 bring-up,之后还需要时间部署 NVKE 服务栈。nvkectl bootstrap site 会等待 --timeout 指定的时长(默认 30m)让集群完成 provision,因此节点规模更大时应显式调高。
这条流程的一个关键含义是:bootstrap site 只负责"造出一个 Kubernetes 集群",它不安装站点栈、不安装 GitOps 控制器、也不部署应用负载。理解这一点,才能正确理解后面的"After Bootstrap"阶段为什么必须单独做。
二、Bootstrap 期间究竟发生了什么
nvkectl bootstrap site 做的事情远不止调用一次 kubeadm。它先在 init 节点上立起一个临时的 Kind 集群,把一套自包含的 NVKE 管理平面装进去(Postgres、Temporal、SPIRE、Cluster API 各 provider,以及 NVKE 控制器),然后用这套控制器,通过 nvke-agent 的 gRPC API 驱动真实节点上的 init 与 join 工作流——全程不需要 SSH。
--disable-mtls 是仅用于开发的明文模式,它会跳过 SPIRE。
原始的时序关系如下:
sequenceDiagram
participant Op as Operator
participant Ctl as nvkectl (init node)
participant Kind as Ephemeral Kind cluster
participant Controller as NVKE controller
participant Init as nvke-agent (init node)
participant Join as nvke-agent (join nodes)
participant K8s as Management Cluster
Op->>Ctl: nvkectl bootstrap site -f sitespec.yaml
Ctl->>Ctl: Load and validate inventory
Ctl->>Kind: Create ephemeral bootstrap Kind cluster
Ctl->>Kind: Deploy Postgres + Temporal + SPIRE (default path) + Cluster API + NVKE controller
Ctl->>Controller: Wait for /readyz healthy
Controller->>Init: ExecuteKubeadmInit (gRPC)
Init->>K8s: kubeadm init
K8s-->>Controller: Join strings
Controller->>Join: ExecuteKubeadmJoin (gRPC, parallel)
Join->>K8s: kubeadm join
Ctl->>Kind: Tear down ephemeral Kind cluster
K8s-->>Op: Cluster ready
2.1 源码中的五个阶段
这条流程在实现上被建模为可观测的五个阶段,定义在 bootstrap_phases.go:
| 阶段 | 含义 |
|---|---|
preflight |
加载与校验 site spec、检查容器运行时、检查遗留的 bootstrap 集群与既有控制平面、检查本地镜像 |
bootstrap_cluster |
创建临时 Kind 集群 |
engine_deploy |
在 Kind 集群内部署管理平面并等待 /readyz |
site_cluster |
创建设点集群、等待控制平面全部 join、写出 kubeconfig 与 etcd 密钥 |
finish |
收尾:解除 control-plane 污点、清理 Kind 集群、输出提示 |
每个阶段都由一个 span 与一条"phase finished"日志记录计时,日志记录中的 phase 字段即为该阶段的名称。这使得"卡在哪一步"可以直接从日志与追踪中读出,而不是靠猜。
2.2 先校验,再动手
命令的第一件事是加载并校验 site spec,任何非法或缺字段都会在任何节点被触碰之前立刻失败。核心逻辑在 bootstrap.go:
inv, err := sitespec.Load(opts.siteSpec, sitespec.WithAllowControlPlaneWithoutVIP(opts.allowControlPlaneWithoutVIP))
if err != nil {
return err
}
...
if err := errors.Join(inv.CheckBootstrapMode(opts.disableMTLS), inv.ValidateBootstrapReferences()); err != nil {
return fmt.Errorf("site spec file %s: %w", opts.siteSpec, err)
}
--dry-run 会在同一个位置返回,因此 dry-run 就是一次完整的预检:它校验 bootstrap 字段、解析 inventory 并打印出来,但不派发任何工作流、不触碰任何节点。
2.3 临时 Kind 集群的形态
临时集群只有一个控制平面节点——它只是在一次命令执行期间承载控制器的宿主,并不是多节点目标。Kind 配置的渲染逻辑见 kindconfig.go,节点角色固定为 control-plane,并支持额外的宿主机挂载与端口映射。
集群名称默认是 nvkectl-bootstrap,可通过 NVKECTL_BOOTSTRAP_CLUSTER_NAME 覆盖,见 bootstrapengine.go:
func DefaultConfig() Config {
return Config{
ClusterName: envOr("NVKECTL_BOOTSTRAP_CLUSTER_NAME", sitespec.DefaultBootstrapClusterName),
NodeImage: envalias.Get("NVKECTL_BOOTSTRAP_NODE_IMAGE"),
WaitReady: envDuration("NVKECTL_BOOTSTRAP_WAIT_READY", 3*time.Minute),
DockerHubMirror: envalias.Get("NVKECTL_BOOTSTRAP_DOCKERHUB_MIRROR"),
}
}
kind create cluster 调用带上了 --retain,这是有意的:否则 kind 在失败退出时会删掉节点容器,连带丢掉 kubelet journal 与控制平面静态 Pod 日志,让一次失败的 kubeadm init 只剩下"connection refused"。bootstrapengine.go 中的注释明确说明了这点——失败路径会先收集证据再删除,最终状态与之前一致,只是多留下了诊断材料。
2.4 管理平面的部署顺序
Kind 集群起来后,控制器会按依赖顺序部署管理平面:Postgres → Temporal → SPIRE → Cluster API → 控制器,每个 Helm release 都要等待 ready 才进入下一步。见 controllerdeploy.go。
这里有一个重要的设计区分:Deploy 本身不等待控制器自己的 /readyz。等待逻辑由调用方在 Deploy 返回后单独执行,从而让"Helm release 安装完成"与"控制器自报健康"成为两个独立计时、独立日志的步骤,见 bootstrap.go。
镜像的供给方式也值得注意:控制器与 provisioned provider 的镜像不是从集群内部拉取,而是从 init 节点的 containerd 镜像存储旁路加载进 Kind 集群——因为临时集群没有 pull secret。带 registry host 的引用在本地缓存缺失时会先被 nerdctl pull,因此需要在 init 节点上提前 nerdctl login。相关说明见 deployAndWaitForCWE 的注释:bootstrap.go。
2.5 site spec 如何被翻译成集群请求
site spec 描述的是"你已有的主机",控制器 API 描述的是"一个 Cluster API 集群"。这层翻译被单独收敛在一个包里,见 sitecluster.go。以 provisioned 提供者为例,请求的形态决定了它是一个 site cluster:
- 请求携带 infra payload 而不携带 nico payload——控制器据此选择 CAPI 模式而非 Forge 模式;
infra.cluster是一个ProvisionedCluster,其 site spec 就是文件里的主机列表;provider 把一台主机分配给一个 machine,自己不创建任何东西;- 控制平面是集群级的
controlPlaneConfig,每台主机一个节点; controlPlaneConfig.infra.machineTemplate是一个 spec 为空的ProvisionedMachineTemplate——一台 machine 需要的一切都已经在ProvisionedCluster中说明,没有 per-machine 的额外信息。
当 infra.provider: nico 时,请求改为携带 nico payload 且没有 infra payload,控制平面数量取自 infra.nico.controlPlane.count 而不是列表长度,见同一文件的 nicoClusterRequest。
2.6 启动前的"拒绝式"预检
在真正创建任何东西之前,命令会做几项只读检查,每一项都对应一种"新的 bootstrap 无法在其之上运行"的状态,并且都只报告、不修改:
- 遗留的临时 Kind 集群:
requireNoBootstrapCluster会拒绝启动,并在消息里优先提示如何从该集群中抢救 etcd 加密密钥(bootstrap.go)。 - 共享 CNI 配置:
requireIsolatedRuntimeCNI检查运行时是否已写入桥接 CNI 配置。 - 已存在的密钥文件:
requireNoKeyFile检查输出路径上是否已有同名集群的加密密钥文件;该文件从不被覆盖,否则失败会在整轮执行的最后才出现(bootstrap.go)。 - 已存在的控制平面:对
provisioned场景逐台尝试 TCP 连接 6443 端口;任何 dial 错误(含超时)都视为"没有监听",因为预置主机常常只放行 agent 端口(bootstrap.go)。对nico场景则探测controlPlaneVIP。 - 本地镜像是否存在:本仓库构建的两个镜像走旁路加载,未构建的镜像会在这里失败,而不是在集群建好之后。
三、临时 Kind 集群的保留与回收规则
临时 Kind 集群正常在引导成功后销毁。它在以下情况被保留:
- 传入
--keep-bootstrap-cluster; - 运行在站点集群创建之后失败;
infra.provider: nico时,创建请求没有得到应答(sitecluster.ErrCreateUnconfirmed)——此时控制器可能已经在分配 NICo 实例,删掉 Kind 集群会让这些实例变为已分配但无人管理的孤儿。
实现上,保留判定由 bootstrap.go 决定:
keepForSite := inv.IsNico() && err == nil
if opts.keepBootstrapKind || keepForSite || (siteClusterCreated && err != nil) {
...
return
}
注意 keepForSite 这一支:在 nico 模式下,一次成功的引导也会保留 bootstrap 集群,因为该站点在 pivot 把管理权交出去之前一直由 bootstrap 集群管理,而这条路径并不执行 pivot。日志会明确提示"不要删除它"。
保留策略与 nico 的回收顺序强相关。原文档给出的结论是:infra.provider: nico 时应使用被保留的 bootstrap 集群进行恢复,因为单独删除 Kind 集群会让 NICo 实例保持已分配且不受管理;而当每个控制平面节点都已 join 之后,只会删除 Kind 集群。源码中对应的建议由 nicoReleaseSteps 与 retainedClusterError 生成(bootstrap.go):需要先通过 nvkectl config set-site 指向 bootstrap 集群的控制器,执行 nvkectl delete cluster <name>,等 nvkectl get clusters 不再列出它,再删除 Kind 集群。
失败时的诊断采集发生在任何拆除动作之前,因为那是证据仍然存在的唯一时刻;每一步都用独立的、与命令上下文解绑的超时执行,避免诊断耗时吃掉删除的预算。相关逻辑见 bootstrap.go。
四、Bootstrap 之后:顺序与密钥
集群起来之后,在部署 NVKE 服务(NVKE 控制器、Temporal、CNPG)之前,必须先在其上安装 Cluster API 与一个基础设施提供者,通过你的 GitOps 工具链完成后续部署。顺序为何重要,见 Infrastructure Providers;ArgoCD 应用结构见 Deploy Repository。
概括该文档给出的核心约束:
- 先装 Cluster API core 与 kubeadm providers(NVKE 固定
v1.13.6,见make/tool-versions.mk)。 - 再装基础设施提供者:CAPNICo、CAPLL,或两者。
- NVKE 控制器必须最后装。它在进程启动时一次性读取
Machine、NicoMachine、LaunchLayerMachine三类 CRD,没有重试;缺失MachineCRD 会直接让进程停止。若控制器已在运行,provider 落地后需要重启它:
kubectl rollout restart deployment -n nvke-controller -l app.kubernetes.io/name=nvke-controller
同时要确认控制平面污点已被移除——站点集群上每个节点都是控制平面节点,而 cert-manager、Cluster API 管理器与 CAPNICo 管理器都不容忍该污点。nvkectl bootstrap site 会移除它,可用下面的命令核验:
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{": "}{.spec.taints}{"\n"}{end}'
4.1 etcd 静态加密:从第一次 kubeadm init 开始
集群的 etcd 数据从第一次 kubeadm init 起就已加密,并且每个控制平面节点都持有密钥。引导过程还会把密钥保存到工作目录下的 <clusterName>-etcd-encryption-key.json(用 --encryption-key-out 可改路径)。
这个文件有两个用途,都源于"节点做不到的事":
- 便利性:稍后安装的控制器可以直接拿到这个文件,而不必有人手工从节点上取密钥;
- 灾难恢复副本:把 etcd 恢复到新主机时,已经没有节点可供取密钥。
保存动作发生在控制平面全部 join 之后、拆除 Kind 集群之前,且 kubeconfig 先写、密钥后写——这样即使密钥捕获失败,操作者仍持有已建成集群的管理凭据。见 bootstrap.go。
密钥文件的写出实现相当保守,见 etcdkey.go:先在目标目录创建临时文件(目录权限 0700)、写入并 fsync、再用硬链接放置到目标路径——链接本身在目标已存在时会失败,因此旧文件永不被覆盖,被预置的符号链接也不会被跟随;随后同步目录并回读比对内容。理由写在包里:这份文件即将成为集群之外唯一的一份副本,"没有落盘的写入不算副本"。
生成的 Secret 清单形态也有讲究:
- 名称是
etcd-encryption-key-<clusterID>,与控制器侧读取的名字保持一致(见 etcdkey.go); - 数据字段为
active; - 带有注解
nvke.nvidia.com/cluster-name,因为 Secret 以集群 UUID 命名,操作者从未见过该 UUID,这是把磁盘上的文件与集群对应起来的唯一线索; - 不写 namespace:最终持有该密钥的控制器是在 bootstrap 之后安装的,namespace 那时才确定。
引导结束时会明确提示:把这个文件从本机移走并妥善保管——本机正是它所保护的节点之一。
若最后一步保存失败,错误类型是 keyCaptureError,消息会说明"集群已建成且已加密,只是密钥没写出去",并给出一条可执行的命令按 bootstrap 集群中的原样保存 Secret(bootstrap.go)。此时不要删除 Kind 集群、也不要重跑 bootstrap。
五、常用参数速查
下表按源码中的 flag 定义整理(bootstrap.go),补充了环境变量与默认值来源:
| 参数 | 默认值 | 作用 |
|---|---|---|
-f, --sitespec |
必填 | site spec YAML 路径 |
--dry-run |
关 | 只加载、校验并打印,不派发工作流 |
--timeout |
30m(可由 NVKECTL_BOOTSTRAP_CLUSTER_TIMEOUT 覆盖) |
等待集群完成 provision 的总预算,包含每个控制平面节点 join |
--diagnostics-dir |
cluster-diagnostics(可由 NVKECTL_BOOTSTRAP_DIAGNOSTICS_DIR 覆盖) |
失败时在拆除前写出集群诊断的目录;--verbose 下成功时也写 |
--keep-bootstrap-cluster |
关 | 保留临时 Kind 集群用于调试 |
--kubeconfig-out |
<clusterName>.kubeconfig |
最终集群的 breakglass 管理员 kubeconfig 输出路径 |
--encryption-key-out |
<clusterName>-etcd-encryption-key.json |
etcd 加密密钥(以 Secret 清单形式)的输出路径 |
--disable-mtls |
关 | 不部署 SPIRE,控制器以明文连接节点 agent;仅限开发,且节点侧 agent 也必须以 --disable-mtls 运行 |
--nvke-controller-image |
清单默认值 | 覆盖控制器镜像,优先于 NVKECTL_NVKE_CONTROLLER_IMAGE |
--provisioned-provider-image |
清单默认值 | 覆盖 provisioned provider 镜像,优先于 NVKECTL_CAPI_PROVISIONED_IMAGE |
--release / --arch |
空 / 跟随宿主架构 | nico 模式下用 NVKR release 中 capnico-controller 构件的固定 digest 替换 bootstrap CAPNICo 镜像 |
--allow-control-plane-without-vip |
关 | 允许多节点控制平面不带 VIP(仅开发,替换初始化节点可能破坏 API 访问) |
--otlp-endpoint / --otlp-insecure |
空 | 把本次运行的 span 与日志记录导出到 collector;回环地址会被拒绝,因为临时集群内的控制器也要能导出 |
两个输出文件都是凭据:kubeconfig 以 0600 写入(bootstrap.go),密钥文件同样只允许属主读取。
六、站点维护与下一步
针对站点管理集群证书的计划性轮换,请使用手工流程:manual certificate-renewal procedure。
如果你是自管理站点(以 NICo 作为基础设施提供者),需要持续保留 nvkectl 以便执行后续操作;把 NICo 本身安装到站点集群上的做法,见 Infrastructure Providers。
后续阅读路径:
- Installation —— 构建并安装
nvkectl; - Configuration —— 编写 site spec 文件;
- Pre-Provisioned Nodes —— 准备节点并执行 bootstrap;
- Custom Base OS —— 基于 cloud-init 的节点准备方式;
- Deploy Repository —— bootstrap 之后的 NVKE 服务部署结构;
- Infrastructure Providers —— 在 NVKE 控制器之前安装 Cluster API 与 CAPNICo。
命令行自身失败时的日志、诊断位置与"何时可以安全重跑",见 Troubleshooting a Site Bootstrap;节点侧的问题(agent 不启动、遗留 bootstrap 集群、端口 6443 已被占用、密钥未保存、手工加入的控制平面节点起不来、etcd 恢复到新主机)在 Pre-Provisioned Nodes 的排查小节中有完整对照。