Provisioning model

vMetal organizes bare metal capacity through a three-level hierarchy: NodeProvider, NodeType, and Machine. This hierarchy determines how the platform defines capacity, selects servers, and generates provisioning data. For the driver-neutral Machine model this hierarchy implements, see Machine concept.

Resource hierarchy

A NodeProvider targets one control plane cluster. It deploys Metal3, Ironic, and the DHCP server on that cluster. It contains one or more node type definitions.

A NodeType groups BareMetalHost resources by label selector. Use it to define provisioning defaults for the group: OS image, SSH keys, network configuration, and resource capacity. Tenants request capacity by specifying a node type name or node type selectors. Selectors can overlap across different hardware dimensions, such as rack, hardware generation, or GPU model, so a server may be eligible under multiple node types at once.

A Machine represents a claim on one provisioned server. The platform creates Machines automatically when a tenant cluster requests private nodes. You do not create Machines directly.

Click to enlarge

Server selection

When the platform creates a Machine, it scans the node type's label selector. It finds all BareMetalHost resources in the available state that match and picks one from the eligible set. A BareMetalHost can be claimed by only one Machine at a time.

The label selector lives in the NodeType definition:

bareMetalHosts:
  selector:
    matchLabels:
      role: compute

Any BareMetalHost with role: compute that is in the available state is eligible.

Property merging

Properties specify the OS image, SSH keys, network configuration, and other provisioning details. Define them at the NodeProvider or NodeType level and they flow down to the Machine.

When the same property is set at multiple levels, the most specific level wins. Machine-level properties override NodeType properties. NodeType properties override NodeProvider properties.

What the platform generates at provisioning time

Click to enlarge

After selecting a BareMetalHost, the platform performs these steps:

1. Merges properties from the NodeProvider and NodeType down to the Machine.
2. Allocates an IP address from the configured CIDR range or IP range.
3. Generates a network-data Secret with the allocated IP, gateway, and DNS servers.
4. Resolves the user-data source (direct cloud-config or Go template).
5. Appends the vCluster join command and SSH keys to the resolved user-data.
6. Writes a user-data Secret to the control plane cluster.
7. Sets the BareMetalHost image and user-data references to point to these Secrets.
8. Metal3 picks up the updated BareMetalHost and begins provisioning through Ironic.

When the Machine is deleted, the platform releases the IP, removes both Secrets, and triggers deprovisioning through Metal3. The BareMetalHost returns to available for reuse.

Server states during provisioning

The BareMetalHost moves through these states during the Machine lifecycle:

State	Description
available	Ready to be claimed.
provisioning	OS image is being written to disk.
provisioned	Server is running the installed OS.
deprovisioning	Server is being cleaned and returned to available.
error	An error occurred. Check the BareMetalHost status conditions for details.

For the full lifecycle including registration and inspection, see Server lifecycle.

Reprovisioning and reuse

After a Machine is released, its BareMetalHost returns to the available pool described in Server selection. Any Machine whose node type selector matches can claim it next, even for a different project or tenant cluster. During release, vMetal removes the project and NodeClaim labels it added to the host. See RBAC and project isolation for how that association is set in the first place.

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 does not 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.

After deprovisioning completes, the host returns to available. Reprovisioning it later, once claimed again, follows the same steps as What the platform generates at provisioning time. Metal3 does not skip PXE boot or OS installation for a server it has provisioned before.

Once provisioned, a server that targets a tenant cluster still needs to join it. See How joining works for that step.

If reprovisioning stalls or fails, see Troubleshooting rather than treating it as expected behavior.

Turnaround expectations

Assuming another Machine requests the server immediately, the time from releasing the current Machine until the next Machine is ready depends on several factors:

• Deprovisioning time, including the BareMetalHost's configured automated cleaning mode.
• BMC responsiveness for power and boot-device operations over Redfish or IPMI.
• Server boot time, including BIOS or UEFI POST and RAID controller initialization, before PXE begins.
• OS image size and the download speed between the image host and the bare metal server, since the server's IPA agent downloads the image directly.
• Startup automation and, for tenant-cluster capacity, the time required to bootstrap and join the node.

These vary by cleaning policy, hardware vendor, network topology, image size, and bootstrap dependencies. There is no universal Metal3 turnaround time. Measure your own environment before setting downstream expectations or SLAs. For fleet-scale image rollout timing, see Rotating OS images.