#裸金属 Provider

#概述

Bare Metal Infrastructure Provider 可在物理服务器上启用不可变基础设施，中间不包含虚拟化层。它在 global 集群上组合了两个长期运行的组件：

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

与 VM Provider（DCS、vSphere）不同，裸金属 Provider 不会创建或销毁机器。主机只安装一次（通过 live ISO → 借助 elemental install 写入磁盘的 OS），注册为 MachineInventory，并在整个集群生命周期内保留在清单中。节点的“创建”和“删除”通过由计划驱动的 elemental upgrade 实现，随后执行重启和 cloud-init 重新执行。

#状态

Provider 目前遵循仅使用 YAML 的工作流。目前还没有用于裸金属集群的 Fleet Essentials UI——本页中的每一步都由 kubectl apply 驱动。

#主要功能

• MachineInventoryPool 分配模型 — operator 预先声明哪些 MachineInventory 对象可以为 KubeadmControlPlane 或 MachineDeployment 提供支持。创建 Machine 时，Provider 会从该池中选择一个 Available 清单；不会在声明集合之外配置任何资源。
• 计划驱动的节点生命周期 — 节点附加使用 reprovision 计划（写入 cloud-init、cloud-init clean、elemental upgrade、重启、重新执行 cloud-init、kubeadm init/join）。节点分离使用 clean 计划（停止 kubelet、清理 CRI 工作负载、停止 containerd）。在扩展、升级或删除集群期间，Provider 永远不会删除 MachineInventory。
• Cluster API 原生对象树 — 使用上游的 Cluster、KubeadmControlPlane、MachineDeployment、Machine。Provider 仅负责基础设施树（BaremetalCluster、BaremetalMachine、BaremetalMachineTemplate、MachineInventoryPool）。不存在自定义控制平面 CRD。
• 由镜像目录驱动的 Kubernetes 版本 — Provider 维护一个集群范围的 elemental-image-catalog ConfigMap，将 Machine.spec.version 映射到 elemental upgrade 镜像。升级将变为“修补版本、控制器解析匹配的镜像、重新配置节点”。
• 两种控制平面端点模式 — BaremetalCluster.spec.controlPlaneLoadBalancer.type: Internal 部署 Alive（keepalived + IPVS + kube-lock Lease 仲裁）并协调自建 VIP。External 跳过 Alive，使用预先配置的第 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 数据卷。Provider 会在分配前准备这些卷，在重新配置期间于 kubelet 之前激活其挂载单元，在节点移除期间停用这些单元，并在重新使用同一清单时保留其文件系统和数据。请参阅管理裸金属主机上的数据磁盘。

#与基于 VM 的 Provider 的差异

#概念和术语

#对象层次结构

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

#裸金属概念

#MachineRegistration

声明注册端点和首次安装 cloud-config，elemental-register 会在 live ISO 上使用该配置。Operator 设置 machineName、machineInventoryLabels 和 machineInventoryAnnotations（使用 ${SMBIOS/...} 模板化），以及 elemental.install 和 elemental.registration 块。MachineRegistration 会被查询，但不会由裸金属 Provider 修改 — 它属于 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

长期存在的主机身份对象。Provider 依赖其契约中的以下部分：

• status.plan.secretRef — 由 elemental-operator 所拥有的唯一默认计划 secret。
• status.plan.state — 用于驱动 BaremetalMachine 状态机的 Applied / Failed 转换。
• status.conditions — 主机侧就绪信号。
• spec.observedNetwork — 仅 fork 使用的字段，由 elemental-register 从 live-ISO NIC 填充；在安装期间以及每个 reprovision 计划期间重新应用。
• spec.storage — 可选的由 Operator 编写的清单所拥有数据卷声明。
• status.observedStorage — 由主机上的 elemental-storage-observer.service 报告的客观设备、文件系统、挂载和 multipath 事实。
• status.storage — Provider 所拥有的 Prepare / Activate / Deactivate / Release 状态、操作日志、条件和已应用卷的身份信息。

Provider 从不删除 MachineInventory，从不使用 MachineInventorySelector，也不会运行单独的 MachineInventoryLifecycleController — 该生命周期仍由 elemental-operator 负责。

#MachineInventoryPool

由 Operator 编写的 MachineInventory 名称集合，指定给定的 BaremetalMachineTemplate 可以从中提取的对象。池限定在单个 clusterName 内，并且每个 MachineInventory 同一时间最多属于一个活动池。池 reconciler 汇总文档中各处使用的池级容量计数器：

• available — 可供分配
• allocated — 已绑定到活动的 BaremetalMachine
• preparing — 正在运行 clean 计划
• reprovisioning — 正在运行 reprovision 计划
• unavailable — Ready=False、计划失败、缺少计划 secret，或不在集群中

#BaremetalCluster

Cluster API 基础设施集群资源。拥有 controlPlaneLoadBalancer（VIP 以及 alive chart 使用的 vrid）和 controlPlaneEndpoint（仅设置 VIP 时从 controlPlaneLoadBalancer 回填）。Reconciler 会延迟集群 addon 部署（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；升级镜像在重新置备时从全局镜像目录解析。

#BaremetalMachine

Cluster API 基础设施机器。将单个 Machine 与单个 MachineInventory 进行 reconciler：

1. 从所属模板引用的池中选择一个 Available 清单。
2. 读取所属的 Machine.spec.bootstrap.dataSecretName，并从镜像目录中解析 Machine.spec.version 的 elemental 升级镜像。
3. 规范化 bootstrap user-data（主机名、kubelet provider-id、criSocket），并将 reprovision 计划写入 MachineInventory 计划 secret。
4. 监视 MachineInventory.status.plan.state，直到计划报告 Applied，然后设置 BaremetalMachine.spec.providerID = baremetal:///<inventory-name>。
5. 删除时，写入 clean 计划；计划应用后清除所有者 annotation，将清单返回池中。

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

#镜像目录

集群范围的 ConfigMap（在 cpaas-system 中的默认名称为 elemental-image-catalog），将 Machine.spec.version 映射到 elemental upgrade 镜像。裸金属 Provider chart 根据 provider.imageCatalog.images 渲染此 ConfigMap（每个仓库前都会添加 global.registry.address），并根据 provider.imageCatalog.data 渲染（用于 digest 固定镜像等完全限定的覆盖项）。这两个值默认均为空，因此在添加条目之前，ConfigMap 不包含任何条目；请参阅 导入 OS 镜像并填充镜像目录。Reconciler 会热加载 ConfigMap；缺少键会进入终止性的 Failed 状态，而不是回退到默认镜像。

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

#主机生命周期计划

Provider 通过清单的唯一默认计划 secret 串行处理所有主机工作。secret 的 baremetal.alauda.io/plan.type annotation 标识当前生命周期计划：

• 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 中删除的卷的 Provider 所有权和激活元数据，但不会擦除其文件系统或数据。

Provider 不使用 MachineInventorySelector 或 FleetBundle。存储生命周期详细信息、安全门控和示例请参阅管理裸金属主机上的数据磁盘。

#alive（控制平面 HA）

alive 是一组静态 Pod（keepalived + IPVS）以及一个 kube-lock Lease 仲裁器，用于维护 BaremetalCluster.spec.controlPlaneLoadBalancer 中描述的控制平面 VIP。当第一个控制平面节点 Ready 后，Provider 会在业务集群中将 alive 部署为 AppRelease，并在控制平面成员发生变化时重新渲染它。在首次 kubeadm init 期间，Provider 会在 bootstrap 前置一个一次性的 ip addr add <control-plane-vip>/32 dev eth0 命令，使第一个节点持有 VIP，直到 alive 接管。

VIP 必须位于控制平面节点的 Layer-2 广播域中；vrid 在该域内必须唯一。

#MachineInventory.spec.observedNetwork

仅 fork 使用的字段，由 elemental-register 从 live-ISO NIC 状态填充，并通过 MsgObservedNetworkConfig 注册消息报告回来。它会在两个位置使用：

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

#API 组

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

#支持的 Kubernetes 版本

请使用产品支持矩阵了解每个 ACP 版本支持的 Kubernetes 版本。有关发行版批准的 Kubernetes 版本及其匹配的组件版本，请参阅 OS Support Matrix。

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

#要求

• 物理主机（或用于实验室环境的可通过 PXE 启动的 VM），并可通过 BIOS 或 UEFI 访问以挂载 SeedImage ISO。
• 每台主机都可访问的平台 registry（elemental install 和 elemental upgrade 均使用该 registry）。设置 global.registry.address；当 registry 使用自签名证书时，保留 global.registry.tlsVerify=false（chart 默认值）。
• 一个控制平面 VIP、一个空闲端口（通常为 6443），以及一个在控制平面 Layer-2 广播域内唯一的 vrid。
• 每个角色（控制平面、worker）各需要一个 MachineInventoryPool，其规模至少应达到目标从节点数，并为升级预留余量。
• 具有真实硬件 TPM（/dev/tpm0）的主机可以向 emulate-tpm: false 注册。任何不具备硬件 TPM 的主机（包括虚拟机和出厂时未配备 TPM 模块的物理服务器）都必须设置 MachineRegistration.spec.config.elemental.registration.emulate-tpm: true；物理主机与虚拟机之间的区别不适用。
• 受管数据磁盘还要求主机 OS 镜像具备支持 observer 的能力，并启用 elemental-storage-observer.service。仅升级管理侧的 provider 和 elemental-operator，不会将此服务添加到使用旧版镜像安装的主机中。

#文档

有关使用裸金属 provider 的详细操作说明，请参阅：

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