Skip to main content

Getting started

vMetal is a bare metal provisioning and lifecycle management layer for the vCluster Platform. It automates server discovery, OS installation via PXE boot, and Kubernetes node attachment. vMetal integrates Metal3 and Ironic to manage hardware through standard Kubernetes resources. For more details, see the vMetal architecture.

info

vMetal uses Metal3 and Ironic for out-of-band management of physical servers. It doesn't require a hypervisor. Servers are provisioned directly with an OS image and join Kubernetes clusters as bare metal nodes.

Benefits of using vMetal include:

  • Automated server discovery and provisioning Physical servers are represented as BareMetalHost resources. vMetal handles registration, hardware inspection, OS installation, and node configuration without manual intervention.

  • GPU and accelerator workloads Direct hardware access without a virtualization layer. vMetal provisions servers with GPUs, FPGAs, or other accelerators and attaches them to Kubernetes clusters where workloads can access the hardware natively.

  • Rack to cluster in minutes PXE-based provisioning installs the OS and runs cloud-init configuration automatically. Servers move from powered-on to cluster-ready through an automated pipeline.

  • Server reuse and lifecycle management When a server is no longer needed, vMetal deprovisions it and returns it to the available pool. Servers can be reclaimed, reimaged, and assigned to different clusters or tenants.

  • Multi-tenant bare metal Combine vMetal with vCluster for tenant isolation and vNode for secure runtime isolation on shared hardware.

  • Works with managed and self-managed clusters vMetal runs on any Kubernetes cluster that can reach the BMC network of the physical servers. The host cluster manages Metal3 and Ironic while the provisioned servers join virtual clusters as private nodes.

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@loft.sh.

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

  • Network access from the host 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 host cluster to a provisioned bare metal server.

1. Create a NodeProvider​

A NodeProvider tells the platform which host 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 host 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 virtual 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.