#Bare Metal Provider

#Overview

The Bare Metal Infrastructure Provider enables Immutable Infrastructure on physical servers, with no virtualization layer in between. It composes two long-running components on the global cluster:

• elemental-operator — registers physical hosts, builds installation ISOs (SeedImage), and maintains the long-lived MachineInventory object for every host. elemental-system-agent runs on each host and executes MachineInventory plan secrets.
• cluster-api-provider-baremetal — the Cluster API infrastructure provider. It groups available MachineInventory objects into pools, binds each Machine to a MachineInventory, and writes clean / reprovision plans that drive the host through Kubernetes node lifecycle.

Unlike VM providers (DCS, vSphere), the bare-metal provider does not create or destroy machines. A host is installed once (live ISO → on-disk OS via elemental install), registers itself as a MachineInventory, and stays in the inventory across the cluster lifecycle. Node "creation" and "deletion" are realized through elemental upgrade driven by plans, followed by reboot and cloud-init re-execution.

#Status

The provider currently follows a YAML-only workflow. There is no Fleet Essentials UI for bare-metal clusters yet — every step on this page is driven by kubectl apply.

#Key Features

• MachineInventoryPool allocation model — operators pre-declare which MachineInventory objects may back a KubeadmControlPlane or MachineDeployment. The provider picks an Available inventory from that pool when a Machine is created; nothing is provisioned outside the declared set.
• Plan-driven node lifecycle — node attach uses a reprovision plan (write cloud-init, cloud-init clean, elemental upgrade, reboot, cloud-init re-execute, kubeadm init/join). Node detach uses a clean plan (stop kubelet, clear CRI workload, stop containerd). MachineInventory is never deleted by the provider during scaling, upgrade, or cluster deletion.
• Cluster API native object tree — uses upstream Cluster, KubeadmControlPlane, MachineDeployment, Machine. The provider only owns the infrastructure tree (BaremetalCluster, BaremetalMachine, BaremetalMachineTemplate, MachineInventoryPool). There is no custom control-plane CRD.
• Image-catalog driven Kubernetes versions — the provider keeps a cluster-scoped elemental-image-catalog ConfigMap that maps Machine.spec.version to an elemental upgrade image. Upgrades become "patch the version, controller resolves the matching image, reprovisions the node."
• Two control-plane endpoint modes — BaremetalCluster.spec.controlPlaneLoadBalancer.type: Internal deploys Alive (keepalived + IPVS + kube-lock Lease arbitration) and reconciles the Self-built VIP. External skips Alive and uses a pre-provisioned Layer 4 TCP LoadBalancer whose backends are maintained outside the cluster. See Plan the Control Plane Endpoint.
• Network identity preservation — elemental-register reports the live-ISO observed network as MachineInventory.spec.observedNetwork. The first elemental install and every later reprovision plan replay that snapshot as cloud-init network-config v2, so a host keeps its address, default route, and DNS across the entire lifecycle.
• Inventory-owned managed data disks — an operator can declare up to 32 XFS or ext4 data volumes in MachineInventory.spec.storage. The provider prepares them before allocation, activates their mount units before kubelet during reprovision, deactivates them during node removal, and preserves their filesystems and data for reuse of the same inventory. See Manage Data Disks on Bare-Metal Hosts.

#Differences from VM-Based Providers

#Concepts and Terminology

#Object hierarchy

The ownership boundary is deliberate: elemental-operator owns host registration and MachineInventory lifecycle, while cluster-api-provider-baremetal owns the Cluster API infrastructure tree. The provider references MachineInventory objects by name and writes plans through the inventory's existing plan secret; it does not create or delete inventories.

#Bare-metal concepts

#MachineRegistration

Declares the registration endpoint and first-install cloud-config that elemental-register consumes on the live ISO. Operators set machineName, machineInventoryLabels, and machineInventoryAnnotations (with ${SMBIOS/...} templating) plus the elemental.install and elemental.registration blocks. MachineRegistration is queried but not modified by the bare-metal provider — it belongs to the elemental layer.

#SeedImage

Triggers elemental-operator to build a bootable ISO that contains the registration URL and the operator's TLS material baked into it. spec.baseImage must reference the ISO variant of the OS image that matches the target Kubernetes version (the repository name carries the -iso suffix; the tag/digest matches the elemental-image-catalog entry for the version you intend to install). The ISO is booted once per physical host; on boot, the host runs elemental-register followed by elemental install and creates a MachineInventory.

#MachineInventory

The long-lived host identity object. The provider relies on the following parts of its contract:

• status.plan.secretRef — the single default plan secret owned by elemental-operator.
• status.plan.state — Applied / Failed transitions used to drive the BaremetalMachine state machine.
• status.conditions — host-side readiness signals.
• spec.observedNetwork — fork-only field populated by elemental-register from the live-ISO NICs; replayed during install and during every reprovision plan.
• spec.storage — optional operator-authored declaration of inventory-owned data volumes.
• status.observedStorage — objective device, filesystem, mount, and multipath facts reported by elemental-storage-observer.service on the host.
• status.storage — provider-owned Prepare / Activate / Deactivate / Release state, operation journal, conditions, and applied-volume identities.

The provider never deletes a MachineInventory, never uses MachineInventorySelector, and does not run a separate MachineInventoryLifecycleController — that lifecycle remains with elemental-operator.

#MachineInventoryPool

Operator-authored set of MachineInventory names that a given BaremetalMachineTemplate is allowed to draw from. Pools are scoped to a single clusterName, and each MachineInventory belongs to at most one active pool at a time. The pool reconciler aggregates the pool-wide capacity counters used everywhere in the docs:

• available — free for allocation
• allocated — bound to an active BaremetalMachine
• preparing — running a clean plan
• reprovisioning — running a reprovision plan
• unavailable — Ready=False, plan failed, missing plan secret, or not present in the cluster

#BaremetalCluster

The Cluster API infrastructure cluster resource. Owns controlPlaneLoadBalancer (the VIP and vrid consumed by the alive chart) and controlPlaneEndpoint (backfilled from controlPlaneLoadBalancer when only the VIP is set). The reconciler defers cluster-addon deployment (alive, kube-ovn) until the workload control plane is reachable.

#BaremetalMachineTemplate

The Cluster API infrastructure template referenced by KubeadmControlPlane.spec.machineTemplate.infrastructureRef and by MachineDeployment.spec.template.spec.infrastructureRef. Templates only carry machineInventoryPoolRef (which pool this machine group draws from) and allocationPolicy (Ordered is currently the only supported value — picks the first Available inventory in declaration order).

There is deliberately no version, role, or upgradeImage on the template. Role comes from the owning Cluster API resource; the version comes from Machine.spec.version; the upgrade image is resolved at reprovision time from the global image catalog.

#BaremetalMachine

The Cluster API infrastructure machine. Reconciles a single Machine against a single MachineInventory:

1. Picks an Available inventory from the pool referenced by the owning template.
2. Reads the owning Machine.spec.bootstrap.dataSecretName and resolves the elemental upgrade image for Machine.spec.version from the image catalog.
3. Normalizes the bootstrap user-data (hostname, kubelet provider-id, criSocket) and writes the reprovision plan into the MachineInventory plan secret.
4. Watches MachineInventory.status.plan.state until the plan reports Applied, then sets BaremetalMachine.spec.providerID = baremetal:///<inventory-name>.
5. On deletion, writes a clean plan and clears the owner annotations once the plan applies, returning the inventory to the pool.

Phase transitions: Pending → Allocated → Reprovisioning → Running; deletion: Running → Preparing → Deleted; failure: * → Failed.

#Image catalog

A cluster-scoped ConfigMap (default name elemental-image-catalog in cpaas-system) that maps Machine.spec.version to an elemental upgrade image. The bare-metal provider chart renders this ConfigMap from provider.imageCatalog.images (global.registry.address is prepended to each repository) and from provider.imageCatalog.data (for fully-qualified overrides such as digest-pinned images). The reconciler hot-reloads the ConfigMap; a missing key is a terminal Failed state, not a fallback to a default image.

Obtain the matching base-image and base-image-iso references from Alauda technical support. The image catalog uses base-image for reprovisioning, while SeedImage.spec.baseImage uses base-image-iso for live installation. Do not derive one reference from the other or substitute an independently built image.

#Host lifecycle plans

The provider serializes all host work through the inventory's single default plan secret. The secret's baremetal.alauda.io/plan.type annotation identifies the current lifecycle plan:

• storage-prepare — runs while an inventory is available and before allocation. It preflights every declared volume, then adopts an existing matching filesystem or initializes an explicitly authorized blank device. It does not mount business paths.
• reprovision — runs on node attach. It embeds managed-volume activation, writes NoCloud user-data / meta-data (and, when MachineInventory.spec.observedNetwork is non-empty, network-config v2), writes a cleanup marker, runs cloud-init clean --logs --seed, runs elemental upgrade --reboot=false --system <image>, and triggers a delayed reboot. After reboot, initramfs clears /var/lib/kubelet, /var/lib/containerd, /var/lib/etcd, and /etc/kubernetes; managed mount units start before kubelet, and cloud-init performs kubeadm init / kubeadm join.
• clean — runs on node detach. It stops kubelet, deactivates managed mounts, clears CRI workload, and stops containerd. It explicitly does not wipe managed filesystems, run kubeadm reset, run cloud-init clean, run elemental upgrade, or reboot. OS cleanup is deferred to the next reprovision plan.
• storage-release — runs only while an inventory is available and all managed volumes are inactive. It removes provider ownership and activation metadata for volumes removed from spec.storage without wiping their filesystems or data.

The provider does not use MachineInventorySelector or FleetBundle. Storage lifecycle details, safety gates, and examples are documented in Manage Data Disks on Bare-Metal Hosts.

#alive (control-plane HA)

alive is a set of static pods (keepalived + IPVS) plus a kube-lock Lease arbitrator that maintain the control-plane VIP described in BaremetalCluster.spec.controlPlaneLoadBalancer. The provider deploys alive as an AppRelease on the workload cluster once the first control-plane Node is Ready, and re-renders it whenever the control-plane membership changes. During the very first kubeadm init, the provider prepends a one-off ip addr add <control-plane-vip>/32 dev eth0 command to the bootstrap so that the first node holds the VIP until alive takes over.

The VIP must live in the control-plane nodes' Layer-2 broadcast domain; vrid must be unique within that domain.

#MachineInventory.spec.observedNetwork

Fork-only field populated by elemental-register from the live-ISO NIC state and reported back via the MsgObservedNetworkConfig registration message. It is consumed in two places:

• During the first elemental install, when MachineInventory.spec.network is empty, the registration server falls back to translating observedNetwork into an nmconnections NetworkConfig so the on-disk OS keeps the same address that the live ISO had.
• During every reprovision, the provider translates observedNetwork into cloud-init network-config v2 (a netplan subset) and writes it as the third NoCloud seed file. Explicit spec.network takes precedence in both cases.

#API Group

All bare-metal infrastructure resources belong to infrastructure.cluster.x-k8s.io/v1beta1. Elemental resources belong to elemental.cattle.io/v1beta1.

#Supported Kubernetes Versions

Use the product support matrix for the Kubernetes versions supported by each ACP release. See OS Support Matrix for the release-approved Kubernetes version and matching component versions.

The bare-metal provider enforces that support decision through elemental-image-catalog: every Machine.spec.version used by a cluster must exist as a key in that ConfigMap. The catalog wiring and out-of-band override procedure are documented in Installation and Upgrading Clusters.

#Requirements

• Physical hosts (or PXE-bootable VMs for lab use) with BIOS or UEFI access to mount the SeedImage ISO.
• A platform registry reachable from each host (used by both elemental install and elemental upgrade). Set global.registry.address and, when the registry is self-signed, leave global.registry.tlsVerify=false (chart default).
• A control-plane VIP, free port (typically 6443), and a vrid unique within the control-plane Layer-2 broadcast domain.
• One MachineInventoryPool per role (control plane, worker) sized to at least the target replica count plus headroom for upgrades.
• A host with a real hardware TPM (/dev/tpm0) can register with emulate-tpm: false. Any host without a hardware TPM — virtual machines and physical servers that ship without a TPM module alike — must set MachineRegistration.spec.config.elemental.registration.emulate-tpm: true; the physical-versus-virtual distinction does not apply.
• Managed data disks additionally require an observer-capable host OS image with elemental-storage-observer.service enabled. Upgrading only the management-side provider and elemental-operator does not add this service to hosts installed from an older image.

#Documentation

For detailed instructions on using the bare-metal provider, see:

• Installation
• Creating Clusters
• Managing Nodes
• Managing Data Disks
• Upgrading Clusters
• API Reference