Architecture
vMetal manages bare metal servers through standard Kubernetes resources. Physical servers are represented as BareMetalHost objects on a host cluster. When a virtual cluster requests a node, vMetal selects an available server, provisions it via PXE boot, and attaches it as a Kubernetes node.
vMetal builds on Metal3 for bare metal lifecycle management and Ironic for out-of-band server provisioning. No hypervisor or virtualization layer is involved.
Provisioning flow
When a Machine is created, vMetal provisions the server through these steps:
- The provider selects an available BareMetalHost from the host cluster. Unlike VMs, bare metal Machines are mapped to existing physical servers rather than creating new instances.
- The platform generates a user data configuration (cloud-init) and stores it in a Kubernetes Secret on the host cluster.
- The Metal3 provider sets the BareMetalHost's image and userData references.
- Ironic powers on the server via BMC (Redfish or IPMI), initiates a PXE boot, and runs an in-memory installer that writes the OS to disk. After installation, it sets the boot device to disk and reboots the server.
- The server boots into the provisioned OS and runs the user data scripts.
- When used as a private node for a vCluster, the user data includes registration scripts that automatically join the server to the virtual cluster.
When the Machine is deleted, vMetal restores the BareMetalHost to its original state, making it available for reuse.
Server lifecycle
BareMetalHost resources go through the following states:
| State | Description |
|---|---|
registering | The server is being registered in the Ironic database and BMC credentials are verified. |
inspecting | Hardware inventory is actively being collected: CPU, RAM, NICs, disks, firmware, and PCIe devices (such as GPUs). |
available | Server is ready to be provisioned. |
provisioning | OS image is being written and cloud-init is being configured. |
provisioned | Server is running with the configured OS. |
deprovisioning | Server is being cleaned and returned to available state. |
error | An error occurred. Check the BareMetalHost status for details. |
When a Machine claims a server, it moves from available through provisioning to provisioned. When the claim is removed, the server is deprovisioned and returned to available.
Components
vMetal consists of the following components, all deployed on the host cluster:
Metal3 Bare Metal Operator
The Bare Metal Operator manages BareMetalHost custom resources. It drives server registration, hardware inspection, and state transitions by communicating with Ironic to execute provisioning operations.
Ironic
Ironic handles the low-level provisioning: BMC communication (power on/off, boot device selection), PXE boot orchestration, and OS image installation. It supports multiple BMC protocols including Redfish and IPMI, with broad hardware vendor compatibility out of the box.
DHCP server
A proxy DHCP server that handles PXE boot by forwarding requests between bare metal servers and Ironic. When the bare metal servers and Ironic are on different networks, the DHCP server bridges the communication. It is automatically configured based on BareMetalHost resources.
Multus CNI
Multus is a CNI plugin that enables attaching the DHCP server to a separate provisioning network. It allows the DHCP server pod to have a network interface on the bare metal provisioning network in addition to the cluster network.
Stack integration
vMetal operates as part of the vCluster Platform stack:
- vMetal provisions and manages physical servers as Kubernetes nodes.
- vCluster Platform orchestrates the control plane, node providers, and tenant management.
- vCluster provides virtual clusters for tenant isolation on shared infrastructure.
- vNode adds secure runtime isolation, allowing privileged workloads (Docker-in-Docker, hostPID) to run safely on shared hardware.