#裸金属 Provider

#概述

裸金属基础设施 Provider 可在物理服务器上创建和管理 Alauda OS 集群，无需虚拟化层。它由两个长期运行在 global 集群上的组件组成：

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

与 VM Provider（DCS、vSphere）不同，裸金属 Provider 不会创建或销毁机器。主机只需安装一次（通过 elemental install 将 Live ISO 安装到磁盘上的 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 重放，因此主机在整个生命周期内都能保留其 IP 地址、默认路由和 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 块。裸金属 Provider 会查询 MachineRegistration，但不会修改它——它属于 elemental 层。

#SeedImage

触发 elemental-operator 构建可启动 ISO，其中内置了注册 URL 和 Operator 的 TLS 材料。spec.baseImage 必须引用与目标 Kubernetes 版本匹配的 OS 镜像 ISO 变体（仓库名称带有 -iso 后缀；标签/摘要与计划安装版本对应的 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 报告的客观设备、文件系统、挂载和多路径事实。
• status.storage — Provider 所有的 Prepare / Activate / Deactivate / Release 状态、操作日志、条件和已应用卷标识。

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

#MachineInventoryPool

由 Operator 编写的 MachineInventory 名称集合，规定给定的 BaremetalMachineTemplate 可从中选取哪些资源。资源池的作用域限定为单个 clusterName，每个 MachineInventory 同一时间最多属于一个活动资源池。资源池协调器汇总整个资源池的容量计数器，供文档各处使用：

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

#BaremetalCluster

Cluster API 基础设施集群资源。拥有 controlPlaneLoadBalancer（VIP 和 vrid，由 alive chart 使用）以及 controlPlaneEndpoint（仅设置 VIP 时从 controlPlaneLoadBalancer 回填）。协调器会延迟部署集群附加组件（alive、kube-ovn），直到业务集群控制平面可访问。

#BaremetalMachineTemplate

由 KubeadmControlPlane.spec.machineTemplate.infrastructureRef 和 MachineDeployment.spec.template.spec.infrastructureRef 引用的 Cluster API 基础设施模板。模板仅包含 machineInventoryPoolRef（此机器组从哪个资源池选取）。Provider 会按照资源池声明中的顺序选择第一个 Available 库存。

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

#BaremetalMachine

Cluster API 基础设施机器。协调单个 Machine 与单个 MachineInventory：

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

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

#镜像目录

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

请向 Alauda 技术支持获取匹配的 base-image 和 base-image-iso 引用。镜像目录在重新置备时使用 base-image，而 SeedImage.spec.baseImage 在 Live ISO 安装时使用 base-image-iso。不要根据其中一个引用推导另一个，也不要替换为独立构建的镜像。

#主机生命周期计划

Provider 通过库存的唯一默认计划 secret 串行执行所有主机操作。该 secret 的 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 中已删除卷的 Provider 所有权和激活元数据，但不会擦除其文件系统或数据。

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

#alive（控制平面 HA）

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

VIP 必须位于控制平面节点的二层广播域中；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 种子文件写入。两种情况下，显式设置的 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 中的键存在。目录配置和带外覆盖操作步骤记录在安装和升级 Kubernetes中。

#要求

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

#文档

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

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