Skip to main content
Version: main 🚧

Bare metal server lifecycle

Enterprise
Available in these plansFreeDevProdScale
Metal3 Integration

Free, Dev, Prod, and Scale are vCluster Platform license plans. Open source does not need a license or a Platform connection. See Compare open source and free tiers.

vCluster Platform integrates Metal3 and Ironic for bare metal server lifecycle management. Physical servers are represented as BareMetalHost resources on a control plane cluster. The platform manages their detection, provisioning, configuration, and decommissioning for reuse.

When to use bare metal​

Bare metal servers are a good fit when workloads need direct hardware access or predictable performance that virtualization cannot provide. Common use cases include:

  • GPU and accelerator workloads: Machine learning training, inference, or video processing that requires direct GPU passthrough without a hypervisor layer.
  • Performance-sensitive applications: Latency-critical databases, real-time analytics, or high-frequency trading systems that benefit from eliminating virtualization overhead.
  • Hardware passthrough: Workloads that need access to specific hardware such as FPGAs, NICs with SR-IOV, or storage controllers.
  • Compliance requirements: Environments where dedicated physical isolation is mandated by regulatory or security policies.

Prerequisites​

Before managing bare metal servers, you need a Metal3 node provider configured on a control plane cluster. The node provider can deploy Metal3, Ironic, and a DHCP server automatically, or you can install them yourself.

Metal3 and the Bare Metal Operator rely on admission webhooks, which require cert-manager on the control plane cluster. Install cert-manager before deploying Metal3. The platform checks for it and warns when it is missing.

Add servers​

Bare metal servers are added by creating BareMetalHost resources on the control plane cluster, either through the platform UI or by applying them directly with kubectl. Each BareMetalHost represents a physical server and requires BMC (Baseboard Management Controller) configuration for out-of-band management.

BMC configuration​

Each BareMetalHost needs a BMC address and credentials. The address scheme determines which driver Metal3 uses to communicate with the server's BMC.

Common address formats:

  • Redfish: redfish://192.168.1.100/redfish/v1/Systems/1
  • Redfish on a Dell iDRAC: idrac-redfish://192.168.1.100/redfish/v1/Systems/System.Embedded.1
  • IPMI: ipmi://192.168.1.100:623

A Redfish address needs the full system path, not just the host. /redfish/v1/Systems/1 is what Lenovo, HPE, and Supermicro BMCs answer. Dell iDRACs use their own scheme and system ID, as shown above. Consult the server vendor for its Redfish system ID. See BMC requirements.

For the full list of supported BMC drivers and address formats, see the Metal3 Bare Metal Operator documentation.

BMC credentials are stored in a Kubernetes Secret:

apiVersion: v1
kind: Secret
metadata:
name: server-01-bmc
namespace: metal3-system
type: Opaque
stringData:
username: admin
password: <BMC-PASSWORD>

Add a single server​

Configure BMC certificate trust before registration. The example keeps certificate verification enabled.

You can add servers through the Metal3 view, or create the resources directly. The example includes the DHCP reservation needed for initial inspection. Replace its addresses with available addresses on your provisioning network:

apiVersion: metal3.io/v1alpha1
kind: BareMetalHost
metadata:
name: server-01
namespace: metal3-system
annotations:
# Initial inspection address, outside the claim allocation pool.
metal3.vcluster.com/ip-address: 192.168.100.20/24
metal3.vcluster.com/gateway: 192.168.100.1
metal3.vcluster.com/dns-servers: 192.168.100.53
labels:
role: compute
spec:
online: false
bmc:
address: redfish://192.168.1.100/redfish/v1/Systems/1
credentialsName: server-01-bmc
disableCertificateVerification: false
bootMACAddress: "aa:bb:cc:dd:ee:01"

Key fields:

FieldDescription
spec.onlineDesired power state. Register servers with false and let Ironic power them on during provisioning.
spec.bmc.addressBMC endpoint URL. The scheme (redfish://, ipmi://, and so on) selects the driver.
spec.bmc.credentialsNameName of the Secret containing username and password keys. Must be in the same namespace.
spec.bmc.disableCertificateVerificationSkips BMC TLS certificate verification when true. Prefer configuring CA trust. See BMC certificate verification.
spec.bootMACAddressMAC address of the NIC used for PXE boot.
metadata.labelsUsed by node type selectors to match servers to node types.

Configure a host address​

When using the platform DHCP server, set a host address before registration so the inspection ramdisk can boot. See Set a host address for the UI fields and equivalent BareMetalHost annotations.

A claim can later supply an IPAM address that temporarily replaces this reservation. The host reservation alone doesn't generate static network data for the installed OS.

Bulk registration​

Add multiple servers at once by applying BareMetalHost and Secret resources together:

---
apiVersion: v1
kind: Secret
metadata:
name: server-01-bmc
namespace: metal3-system
type: Opaque
stringData:
username: admin
password: <BMC-PASSWORD>
---
apiVersion: metal3.io/v1alpha1
kind: BareMetalHost
metadata:
name: server-01
namespace: metal3-system
annotations:
# Initial inspection address, outside the claim allocation pool.
metal3.vcluster.com/ip-address: 192.168.100.20/24
metal3.vcluster.com/gateway: 192.168.100.1
metal3.vcluster.com/dns-servers: 192.168.100.53
labels:
role: compute
rack: rack-a
spec:
bmc:
address: redfish://192.168.1.100/redfish/v1/Systems/1
credentialsName: server-01-bmc
bootMACAddress: "aa:bb:cc:dd:ee:01"
---
apiVersion: v1
kind: Secret
metadata:
name: server-02-bmc
namespace: metal3-system
type: Opaque
stringData:
username: admin
password: <BMC-PASSWORD>
---
apiVersion: metal3.io/v1alpha1
kind: BareMetalHost
metadata:
name: server-02
namespace: metal3-system
annotations:
# Initial inspection address, outside the claim allocation pool.
metal3.vcluster.com/ip-address: 192.168.100.21/24
metal3.vcluster.com/gateway: 192.168.100.1
metal3.vcluster.com/dns-servers: 192.168.100.53
labels:
role: compute
rack: rack-b
spec:
bmc:
address: ipmi://192.168.1.101:623
credentialsName: server-02-bmc
bootMACAddress: "aa:bb:cc:dd:ee:02"
kubectl apply -f servers.yaml

Server lifecycle​

BareMetalHost resources go through the following states:

StateDescription
registeringThe server is being registered in the Ironic database and BMC credentials are verified.
inspectingHardware inventory is being collected, including CPU, RAM, NICs, disks, firmware, and PCIe devices such as GPUs.
preparingRAID or firmware configuration is being applied.
availableServer is ready to be provisioned.
provisioningOS image is being written and cloud-init is being configured.
provisionedServer is running with the configured OS.
deprovisioningServer is being cleaned and returned to available state.

Errors appear separately in status.operationalStatus, status.errorType, and status.errorMessage. For example, status.operationalStatus: error can accompany status.provisioning.state: provisioning. See the upstream Host state machine.

When an instance claims a server, the platform writes the OS image, user data, and network data to the BareMetalHost and sets spec.online: true. The host moves from available through provisioning to provisioned. When the claim is removed, the platform clears the image, user data, and network data and sets spec.online: false. The Bare Metal Operator (BMO) then deprovisions the host, powers it off, and returns it to available.

Ironic controls server power through the BMC. Register a BareMetalHost with spec.online: false and let Ironic power the server on when an instance claims it. Ironic powers it off again when the claim is removed.

A host can be claimed only when BMO reports it available, powered off, with no image and no consumerRef. Two instances can't claim the same host.

When a host fails during provisioning​

An instance doesn't move to another host once it has claimed one. During provisioning, inspecting, or preparing, the platform keeps the instance Pending and checks the host again. This wait has no platform provisioning timeout.

A BMO operational error doesn't move the instance to Failed. The instance stays Pending with no timeout. Check the host's status.operationalStatus, and if it's error, fix the host or replace the instance. The instance fails with HostProvisioningFailed only if BMO reports the provisioning state itself as error.

While the instance waits, its Machine can report a fault. The platform reports ramdisk not booted when Ironic has waited more than 15 minutes for the deploy ramdisk to call back. During provisioning, inspecting, or preparing, the platform adds that fault to the instance's condition message and keeps waiting. Fix the host or replace the instance. See Stuck in provisioning and Error state for the checks.

Reuse and reprovisioning​

After an instance is released, its BareMetalHost returns to the available pool. The next instance to claim it follows the same placement rules as any other. A host assigned to a tenant serves that tenant's Assigned or machine-pinned instances again. An unassigned host can serve any tenant whose node type uses the OnDemand policy, or an instance requested outside a tenant. See Where an instance is placed.

During release, the platform undoes what it wrote to the host when it claimed it. It removes the host's project association and the instance data it generated. See Prevent cross-project server access for how the project association is set. If the platform wrote the host's DHCP annotations, it restores the values you set before the claim. See the per-host DHCP annotations on the DHCP Server tab of Infrastructure deployment.

Tenant assignment labels stay on the host's Machine. Release doesn't return a tenant's host to the unassigned pool.

During deprovisioning, BMO follows the BareMetalHost's spec.automatedCleaningMode. The default metadata mode removes partition tables from all disks, while disabled skips automated cleaning. Neither mode performs a full-disk data erasure, and vMetal doesn't override this setting. Before allowing hosts to move between projects, define any additional sanitization controls your security policy requires. See Automated cleaning for the upstream behavior.

When the host is provisioned again, it follows the same steps as the first time. Metal3 doesn't skip PXE boot or OS installation for a server it has provisioned before.

DHCP and PXE boot​

When the Metal3 node provider deploys a DHCP server, it automatically handles the PXE boot flow. The DHCP server acts as a proxy between the bare metal servers and Ironic, which may reside in a different network. It forwards the API communication needed for PXE boot and OS installation.

Configure the DHCP server's provisioning-network attachment and each host's address and boot MAC before registration. The provider-managed server then supplies the boot files and proxies IPA communication. See Network configuration.