#裸金属提供程序

#概述

Bare Metal Infrastructure Provider 可在物理服务器上启用不可变基础设施，中间不经过任何虚拟化层。它由 global 集群中的两个长期运行组件构成：

• elemental-operator — 注册物理主机，构建安装 ISO（SeedImage），并为每台主机维护长期存在的 MachineInventory 对象。elemental-system-agent 在每台主机上运行，并执行 MachineInventory 计划密钥。
• cluster-api-provider-baremetal — Cluster API 基础设施提供程序。它将可用的 MachineInventory 对象分组到池中，将每个 Machine 绑定到一个 MachineInventory，并写入 clean / reprovision 计划，以驱动主机完成 Kubernetes 节点生命周期。

与 VM 提供程序（DCS、vSphere）不同，裸金属提供程序不会创建或销毁机器。主机只需安装一次（live ISO → 通过 elemental install 安装到磁盘上的 OS），随后将自己注册为 MachineInventory，并在整个集群生命周期内保留在库存中。节点的“创建”和“删除”是通过 elemental upgrade 驱动的计划来实现的，随后会重启并重新执行 cloud-init。

#状态

当前该提供程序仅支持基于 YAML 的工作流。页面中尚未提供裸金属集群的 Fleet Essentials UI——此页上的每个步骤都通过 kubectl apply 驱动。

#主要特性

• MachineInventoryPool 分配模型 — operator 预先声明哪些 MachineInventory 对象可作为 KubeadmControlPlane 或 MachineDeployment 的后端。创建 Machine 时，提供程序会从该池中选择一个 Available 库存；不会在声明集之外进行任何供应。
• 基于计划驱动的节点生命周期 — 节点挂接使用 reprovision 计划（写入 cloud-init、cloud-init clean、elemental upgrade、重启、cloud-init 重新执行、kubeadm init/join）。节点分离使用 clean 计划（停止 kubelet、清理 CRI 工作负载、停止 containerd）。在扩缩容、升级或集群删除期间，提供程序不会删除 MachineInventory。
• Cluster API 原生对象树 — 使用上游的 Cluster、KubeadmControlPlane、MachineDeployment、Machine。提供程序仅负责基础设施树（BaremetalCluster、BaremetalMachine、BaremetalMachineTemplate、MachineInventoryPool）。不存在自定义的 control-plane CRD。
• 由 image-catalog 驱动的 Kubernetes 版本 — 提供程序维护一个集群作用域的 elemental-image-catalog ConfigMap，用于将 Machine.spec.version 映射到 elemental upgrade 镜像。升级过程就变成了“补丁更新版本，控制器解析匹配镜像，重新配置节点”。
• 两种 control-plane 端点模式 — BaremetalCluster.spec.controlPlaneLoadBalancer.type: Internal 会部署 Alive（keepalived + IPVS + kube-lock Lease 仲裁），并协调自建 VIP。External 则跳过 Alive，使用一个预先配置好的 Layer 4 TCP LoadBalancer，其后端由集群外部维护。请参见 规划控制平面端点。
• 网络标识保留 — elemental-register 会将 live ISO 看到的网络上报为 MachineInventory.spec.observedNetwork。第一次 elemental install 以及之后每一次 reprovision 计划都会将该快照回放为 cloud-init network-config v2，因此主机在整个生命周期中都能保持其地址、默认路由和 DNS 不变。
• 由库存拥有的受管数据盘 — operator 可在 MachineInventory.spec.storage 中声明最多 32 个 XFS 或 ext4 数据卷。提供程序会在分配前准备这些卷，在 reprovision 期间于 kubelet 之前激活其挂载单元，在节点移除期间停用这些挂载单元，并保留其文件系统和数据，以便同一库存后续复用。请参见 在裸金属主机上管理数据盘。

#与基于 VM 的提供程序的差异

#概念与术语

#对象层次

这种所有权边界是有意设计的：elemental-operator 负责主机注册和 MachineInventory 生命周期，而 cluster-api-provider-baremetal 负责 Cluster API 基础设施树。提供程序通过名称引用 MachineInventory 对象，并通过库存现有的计划密钥写入计划；它不会创建或删除库存。

#裸金属概念

#MachineRegistration

声明 elemental-register 在 live ISO 上使用的注册端点和首次安装 cloud-config。operator 会设置 machineName、machineInventoryLabels 和 machineInventoryAnnotations（使用 ${SMBIOS/...} 模板）以及 elemental.install 和 elemental.registration 块。MachineRegistration 会被查询，但不会被裸金属提供程序修改——它属于 elemental 层。

#SeedImage

触发 elemental-operator 构建一个可启动 ISO，其中包含注册 URL 和 operator 的 TLS 材料。spec.baseImage 必须引用与目标 Kubernetes 版本匹配的 OS 镜像的 ISO 变体（仓库名称带有 -iso 后缀；tag/digest 与你打算安装的版本对应的 elemental-image-catalog 条目一致）。每台物理主机仅引导该 ISO 一次；启动后，主机会先运行 elemental-register，随后运行 elemental install，并创建一个 MachineInventory。

#MachineInventory

长期存在的主机身份对象。提供程序依赖其以下契约部分：

• status.plan.secretRef — 由 elemental-operator 拥有的单一默认计划密钥。
• status.plan.state — 用于驱动 BaremetalMachine 状态机的 Applied / Failed 过渡。
• status.conditions — 主机侧就绪信号。
• spec.observedNetwork — 仅分支字段，由 elemental-register 根据 live ISO 的 NIC 填充；会在安装期间以及每次 reprovision 计划期间回放。
• spec.storage — 可选的、由 operator 编写的数据卷声明。
• status.observedStorage — 由主机上的 elemental-storage-observer.service 报告的设备、文件系统、挂载和 multipath 客观事实。
• status.storage — 由提供程序拥有的 Prepare / Activate / Deactivate / Release 状态、操作日志、条件和已应用卷身份。

提供程序不会删除 MachineInventory，也不会使用 MachineInventorySelector，并且不会运行单独的 MachineInventoryLifecycleController——该生命周期仍由 elemental-operator 负责。

#MachineInventoryPool

由 operator 编写的 MachineInventory 名称集合，特定的 BaremetalMachineTemplate 允许从中选择。池的作用域限制在单个 clusterName 内，每个 MachineInventory 在同一时间最多只属于一个活动池。池 reconciler 会汇总文档中各处使用的池级容量计数器：

• available — 可用于分配
• allocated — 已绑定到一个活动的 BaremetalMachine
• preparing — 正在运行 clean 计划
• reprovisioning — 正在运行 reprovision 计划
• unavailable — Ready=False、计划失败、缺少计划密钥，或未出现在集群中

#BaremetalCluster

Cluster API 基础设施集群资源。负责 controlPlaneLoadBalancer（供 alive chart 使用的 VIP 和 vrid）以及 controlPlaneEndpoint（仅设置 VIP 时从 controlPlaneLoadBalancer 回填）。当工作负载 control plane 可达后，reconciler 才会延迟部署集群插件（alive、kube-ovn）。

#BaremetalMachineTemplate

由 KubeadmControlPlane.spec.machineTemplate.infrastructureRef 和 MachineDeployment.spec.template.spec.infrastructureRef 引用的 Cluster API 基础设施模板。模板仅包含 machineInventoryPoolRef（该机器组从哪个池中选取）和 allocationPolicy（当前唯一支持的值为 Ordered——按声明顺序选择第一个 Available 库存）。

模板上有意不包含 version、role 或 upgradeImage。角色来自所属的 Cluster API 资源；版本来自 Machine.spec.version；升级镜像则在 reprovision 时从全局 image catalog 中解析。

#BaremetalMachine

Cluster API 基础设施机器。将一个 Machine 与一个 MachineInventory 进行协调：

1. 从所属模板引用的池中选择一个 Available 库存。
2. 读取所属 Machine.spec.bootstrap.dataSecretName，并从 image catalog 中解析 Machine.spec.version 对应的 elemental upgrade 镜像。
3. 规范化 bootstrap user-data（hostname、kubelet provider-id、criSocket），并将 reprovision 计划写入 MachineInventory 计划密钥。
4. 监视 MachineInventory.status.plan.state，直到计划报告 Applied，然后设置 BaremetalMachine.spec.providerID = baremetal:///<inventory-name>。
5. 在删除时，写入 clean 计划，并在计划应用后清除 owner 注解，将库存返回到池中。

阶段转换：Pending → Allocated → Reprovisioning → Running；删除：Running → Preparing → Deleted；失败：* → Failed。

#Image catalog

一个集群作用域的 ConfigMap（默认名称为 cpaas-system 中的 elemental-image-catalog），用于将 Machine.spec.version 映射到 elemental upgrade 镜像。裸金属提供程序 chart 会根据 provider.imageCatalog.images 渲染此 ConfigMap（global.registry.address 会被添加到每个仓库前），以及根据 provider.imageCatalog.data 渲染（用于完全限定的覆盖项，例如固定 digest 的镜像）。reconciler 会热重载该 ConfigMap；缺少键会直接进入终止性的 Failed 状态，而不会回退到默认镜像。

请从 Alauda 技术支持获取匹配的 base-image 和 base-image-iso 引用。image catalog 使用 base-image 进行 reprovision，而 SeedImage.spec.baseImage 使用 base-image-iso 进行 live 安装。不要从其中一个引用推导另一个，也不要替换为独立构建的镜像。

#主机生命周期计划

提供程序通过库存的单一默认计划密钥串行化所有主机工作。该密钥的 baremetal.alauda.io/plan.type 注解标识当前生命周期计划：

• storage-prepare — 在库存可用且分配之前运行。它会预检每个已声明卷，然后接管一个现有的匹配文件系统，或者初始化一个明确授权的空白设备。它不会挂载业务路径。
• reprovision — 在节点挂接时运行。它会嵌入受管卷激活，写入 NoCloud user-data / meta-data（如果 MachineInventory.spec.observedNetwork 非空，则还会写入 network-config v2），写入清理标记，执行 cloud-init clean --logs --seed，执行 elemental upgrade --reboot=false --system <image>，并触发延迟重启。重启后，initramfs 会清除 /var/lib/kubelet、/var/lib/containerd、/var/lib/etcd 和 /etc/kubernetes；受管挂载单元会在 kubelet 之前启动，cloud-init 会执行 kubeadm init / kubeadm join。
• clean — 在节点分离时运行。它会停止 kubelet、停用受管挂载、清除 CRI 工作负载并停止 containerd。它明确不会擦除受管文件系统、执行 kubeadm reset、执行 cloud-init clean、执行 elemental upgrade 或重启。OS 清理会延后到下一次 reprovision 计划。
• storage-release — 仅在库存可用且所有受管卷均处于非活动状态时运行。它会移除从 spec.storage 中删除的卷的提供程序所有权和激活元数据，但不会擦除其文件系统或数据。

提供程序不使用 MachineInventorySelector 或 FleetBundle。存储生命周期细节、安全门禁和示例记录在 在裸金属主机上管理数据盘 中。

#alive（control-plane HA）

alive 是一组静态 Pod（keepalived + IPVS）以及一个 kube-lock Lease 仲裁器，用于维护 BaremetalCluster.spec.controlPlaneLoadBalancer 中描述的 control-plane VIP。提供程序会在第一个 control-plane Node 就绪后，将 alive 作为 AppRelease 部署到工作负载集群，并在 control-plane 成员发生变化时重新渲染它。在首次 kubeadm init 期间，提供程序会在 bootstrap 前加上一条一次性的 ip addr add <control-plane-vip>/32 dev eth0 命令，以便第一台节点在 alive 接管前持有 VIP。

VIP 必须位于 control-plane 节点的 Layer-2 广播域中；vrid 在该广播域内必须唯一。

#MachineInventory.spec.observedNetwork

仅分支字段，由 elemental-register 根据 live ISO 的 NIC 状态填充，并通过 MsgObservedNetworkConfig 注册消息回传。它在两个位置被使用：

• 在第一次 elemental install 期间，当 MachineInventory.spec.network 为空时，注册服务器会回退为将 observedNetwork 转换为 nmconnections NetworkConfig，以便磁盘上的 OS 保持与 live ISO 相同的地址。
• 在每次 reprovision 期间，提供程序会将 observedNetwork 转换为 cloud-init network-config v2（netplan 的子集），并将其写为第三个 NoCloud 种子文件。在这两种情况下，显式的 spec.network 都具有优先级。

#API 组

所有裸金属基础设施资源都属于 infrastructure.cluster.x-k8s.io/v1beta1。Elemental 资源属于 elemental.cattle.io/v1beta1。

#支持的 Kubernetes 版本

请参考产品支持矩阵，了解每个 ACP 版本支持的 Kubernetes 版本。有关发布版批准的 Kubernetes 版本及匹配的组件版本，请参见 OS 支持矩阵。

裸金属提供程序通过 elemental-image-catalog 强制执行该支持决策：集群使用的每个 Machine.spec.version 都必须作为该 ConfigMap 中的一个键存在。catalog 的配置方式及带外覆盖步骤记录在 安装 和 升级集群 中。

#需求

• 可访问 BIOS 或 UEFI 的物理主机（或用于实验室环境的可 PXE 启动 VM），以便挂载 SeedImage ISO。
• 每台主机都能访问的平台镜像仓库（elemental install 和 elemental upgrade 都会使用）。设置 global.registry.address，并且在镜像仓库使用自签名证书时，将 global.registry.tlsVerify=false 保持为默认值。
• control-plane VIP、可用端口（通常为 6443）以及在 control-plane Layer-2 广播域内唯一的 vrid。
• 每个角色（control plane、worker）一个 MachineInventoryPool，其规模至少应达到目标副本数，并为升级预留余量。
• 具有真实硬件 TPM（/dev/tpm0）的主机可以使用 emulate-tpm: false 注册。任何没有硬件 TPM 的主机——无论是虚拟机还是未配备 TPM 模块的物理服务器——都必须设置 MachineRegistration.spec.config.elemental.registration.emulate-tpm: true；物理与虚拟的区分在此不适用。
• 受管数据盘还要求主机 OS 镜像中启用了 elemental-storage-observer.service。仅升级管理侧的提供程序和 elemental-operator，不会将此服务添加到从旧镜像安装的主机上。

#文档

有关使用裸金属提供程序的详细说明，请参见：

• 安装
• 创建集群
• 管理节点
• 管理数据盘
• 升级集群
• API 参考