Skip to main content

Getting started

vMetal is the bare metal layer of the vCluster Platform. It builds on Metal3 and Ironic to handle BMC communication, PXE boot, OS installation, and server cleaning. On top of that, vMetal adds pooled server capacity by node type, automated IP allocation, cloud-init generation, and automatic Kubernetes node registration for tenant clusters. 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 enrolled as BareMetalHost resources. Metal3 then inspects each server and provisions it with an OS image.

Benefits of using vMetal include:

  • Pooled bare metal capacity Node types group servers by hardware profile, such as GPU model, CPU count, and rack location. The platform tracks availability across each pool. When a tenant requests a node, the platform claims a server, provisions it, and returns it to the pool when the cluster is done.

  • GPU and accelerator workloads Direct hardware access without a virtualization layer. vMetal provisions servers with GPUs, FPGAs, or other accelerators. Workloads in the tenant cluster access the hardware natively.

  • Automated provisioning pipeline Register a server as a BareMetalHost. Metal3 verifies BMC access and collects hardware inventory. When a tenant cluster requests a node, the platform selects a matching server, allocates an IP, and triggers PXE boot and OS installation through Ironic.

  • Automatic Tenant Cluster node registration When the platform provisions a private node for a tenant cluster, the cloud-init joins the server to that cluster automatically. No manual kubeadm join or agent installation is needed.

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

  • Bare metal with Tenant Isolation 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 control plane cluster manages Metal3 and Ironic. Provisioned servers join tenant 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 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.

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.