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.

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 one provisioned server. The platform creates Machines automatically when a tenant cluster requests private nodes. You do not create Machines directly.

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

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 Architecture.