Install

Before you begin

To use vMetal, ensure you have the following:

• An existing vCluster Platform installation.

• A license plan that includes vMetal.

  note

  To check your plan, in the platform navigate to Admin > License and Billing. If your plan doesn't include vMetal, contact support@vcluster.com.

• A control plane cluster connected to vCluster Platform where Metal3 and Ironic run.

• Network access from the control plane cluster to the BMC endpoints (Redfish or IPMI) of your bare metal servers.

• Physical servers with BMC (Baseboard Management Controller) support and a NIC configured for PXE boot.

Quick start

This walkthrough covers the essential steps to go from a connected control plane cluster to a provisioned bare metal server.

Click to enlarge

1. Create a NodeProvider

A NodeProvider tells the platform which control plane cluster to use, what infrastructure to deploy, and how to categorize your servers.

apiVersion: management.loft.sh/v1
kind: NodeProvider
metadata:
  name: metal3-provider
spec:
  displayName: "Metal3 Bare Metal Provider"
  metal3:
    clusterRef:
      cluster: bare-metal-cluster
      namespace: metal3-system
    deploy:
      metal3:
        enabled: true
      dhcp:
        enabled: true
    nodeTypes:
    - name: "compute-node"
      displayName: "Compute Node"
      resources:
        cpu: "32"
        memory: 128Gi
      bareMetalHosts:
        selector:
          matchLabels:
            role: compute
      properties:
        vcluster.com/os-image: ubuntu-noble

kubectl apply -f metal3-provider.yaml

Wait for Metal3 and Ironic to be running on the control plane cluster before creating BareMetalHost resources. The Metal3 webhook must be ready to validate them.

2. Create BMC credentials

Create a Secret with the BMC username and password for your server. The BareMetalHost resource references this Secret.

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

kubectl apply -f server-01-bmc-secret.yaml

3. Register a bare metal server

Create a BareMetalHost resource. The bmc.address scheme determines which driver Metal3 uses, such as Redfish or IPMI. The bootMACAddress identifies the NIC used for PXE boot.

apiVersion: metal3.io/v1alpha1
kind: BareMetalHost
metadata:
  name: server-01
  namespace: metal3-system
  labels:
    role: compute
spec:
  bmc:
    address: redfish://192.168.1.100
    credentialsName: server-01-bmc
    disableCertificateVerification: true
  bootMACAddress: "aa:bb:cc:dd:ee:01"

kubectl apply -f server-01-bmh.yaml

The server moves through registering and inspecting states as Metal3 verifies BMC access and collects hardware inventory.

4. Verify the server reaches available state

Once the BareMetalHost passes inspection, it transitions to available. The server is registered, its hardware inventory is collected, and it's ready for provisioning.

kubectl get baremetalhost -n metal3-system

NAME        STATE       CONSUMER   ONLINE   ERROR
server-01   available              true

5. Create a vCluster that claims the server

Create a vCluster with private nodes configured to use the Metal3 provider. The platform provisions a Machine, which claims the BareMetalHost and installs the OS through Ironic.

privateNodes:
  enabled: true
  autoNodes:
    - provider: metal3-provider
      static:
        - name: compute-nodes
          quantity: 1
          nodeTypeSelector:
            - property: vcluster.com/node-type
              value: compute-node

After provisioning completes, the server boots into the configured OS and joins the tenant cluster as a worker node.

Try it locally

The vCluster Bare Metal with KubeVirt guide lets you run the full Metal3 bare metal provisioning flow locally using KubeVirt VMs as simulated bare metal servers. It sets up a cluster with KubeVirt, a Metal3 NodeProvider, and simulated BareMetalHosts with Redfish BMC endpoints. No physical hardware required.