vMetal
vMetal provisions and manages physical and virtual machines. It boots bare metal servers over the network, installs an operating system, configures networking, and tracks which servers are claimed and which are free to reuse. The same model covers virtual machines through other drivers.
vMetal isn't a single driver, repository, or service. It spans Platform's NodeClaim, NodeProvider, and NodeType APIs, vCluster's node-consumption workflows, and a portfolio of provisioning drivers. vMetal documentation is part of the Platform documentation source, and it always ships and versions in lockstep with Platform.
An instance represents a claim on one provisioned server, either physical or virtual. A provisioning driver integrates the infrastructure that supplies and manages that server. See the Glossary for terminology and Instance and server concepts for the lifecycle and identity model.
Two use cases, three outcomes​
vMetal serves two use cases as peers. Both use the same instances, the same drivers, and the same pool of servers.
Stand up and hand out hardware. Request an instance on its own and get a provisioned server with your SSH keys on it. Nothing installs Kubernetes. This is how you run vMetal as a metal-as-a-service layer, or as the foundation for workloads that aren't Kubernetes at all.
Give clusters dedicated capacity. Request an instance for a cluster and the provisioned server joins it as a Kubernetes node, with no manual join step. This use case has two shapes. A server can join as a worker, or it can carry the cluster's own control plane. The second doesn't need a separate workload cluster to host the tenant control plane, but vMetal still needs the connected cluster where the driver's own components run.
That makes three things a provisioned server can become, and they differ by a field or two on the request. Everything up to the moment the operating system boots is identical, and all three share the same setup and day-2 operations.
| Outcome | What the platform appends to cloud-init | Guide |
|---|---|---|
| Independently provisioned instance | Your SSH keys only | Independently provisioned instances |
| Control plane instance | SSH keys and the vCluster install script | Control plane instances |
| Cluster node | SSH keys and a Kubernetes join command | Cluster nodes |
Evaluate vMetal​
Work out whether vMetal fits your hardware and your team before you set it up.
| If you want to | Go to |
|---|---|
| Check vMetal works with your servers, BMCs, and network | Requirements |
| Run the whole provisioning flow with no hardware at all | Try it yourself |
| See what to ask a data center or colocation provider for | Handoff checklist |
| Confirm your control plane cluster is a supported one | Managed Kubernetes restrictions |
| Understand what vMetal doesn't do | What the Metal3 driver doesn't provide |
| Know where the driver's current boundaries are | Known limits |
Trying it yourself is the fastest way in. That guide runs Metal3, a NodeProvider, and simulated BareMetalHosts with Redfish BMC endpoints on KubeVirt VMs, so you can watch a server provision end to end before any hardware arrives.
Where to start​
Once you've decided to build on vMetal, both use cases start with the same hardware setup, whichever of the three a server ends up as.
| If you want to | Go to |
|---|---|
| Provision your first bare metal server | Get started with Metal3 |
| Choose an initial provisioning workflow | Get started |
| Register many servers at once | Bulk registration |
| Configure a NodeProvider and node types | Node types and node providers |
| Add, remove, and inspect servers | Operations |
| Diagnose a server that won't provision | Troubleshooting |
| Secure a production Metal3 deployment | Production and Security |
Run AI workloads on it​
| If you want to | Go to |
|---|---|
| Understand GPU passthrough, vGPU, and MIG boundaries | GPU presentation modes |
| Provision GPU servers as cluster nodes | GPU quickstart |
| Build a GPU fleet for an inference provider | GPU Fleet Operations |
Understand the model​
| If you want to | Go to |
|---|---|
| Learn vMetal terminology | Glossary |
| Understand the instance and server model and lifecycle | Instance and server concepts |
| See how servers join clusters | Cluster attachment |
| Understand the Machine inventory mirror and claim it directly | Machine inventory |
| Understand network environments and integrations | Networking |
What the platform owns​
The platform owns the NodeProvider, NodeType, and NodeClaim resources. A NodeClaim is the Kubernetes resource that represents one instance request and tracks its lifecycle. Every use above creates a NodeClaim. They differ only in whether the claim names a cluster and whether it's marked as a control plane.
Clusters consume that capacity through Private Nodes, either at a count you set or maintained automatically by Auto Nodes. Auto Nodes maintains private node lifecycle in either a static mode, reconciling to a configured desired node count, or a dynamic mode, adding and removing nodes based on configurable resource requirements. Auto Nodes is one way to consume vMetal capacity, not the whole of vMetal.
Choose a provisioning driver​
vMetal provisions instances through a portfolio of drivers. Drivers differ in implementation, maturity, and available features. Check each driver's documentation before relying on a specific capability. See Node types and node providers for the current driver list.
Metal3 provisions bare metal directly without a hypervisor in the vMetal-managed path. KubeVirt provisions Kubernetes nodes as virtual machines on infrastructure you provide separately. Each driver publishes its own requirements, capabilities, and day-two operations. This section currently documents Metal3 in the most depth.
What vMetal provides, across drivers​
Regardless of which driver provisions an instance, vMetal gives you:
- Common provisioning API - the same
NodeClaim,NodeProvider, and node type model across drivers, so you request capacity the same way whatever sits underneath. - OS image lifecycle - each driver resolves its own OS image today. A shared, project-scoped image cache across drivers is planned but not yet available.
- Automatic node registration - an instance that targets a cluster joins it without a manual
kubeadmjoin or agent installation. An instance requested on its own skips this step entirely. - Capacity tracking and reclaim - vMetal tracks the infrastructure assigned to an instance. During teardown, the driver either returns reusable inventory to a pool or destroys infrastructure created for the claim.
- Resource-aware consumption - Tenant and Project boundaries control which infrastructure resources users can see and consume. vCluster and vNode provide separate workload and runtime isolation boundaries.
Physical and virtual instance use cases include general compute, GPU workloads, accelerator workloads, and other AI infrastructure needs. See GPU presentation modes for how vMetal exposes GPUs without owning the driver stack itself.
How vMetal fits into the platform stack​
- vMetal provides the common
NodeClaimprovisioning model across physical and virtual provisioning drivers, whether the servers become Kubernetes nodes or instances you use directly. - vCluster Platform manages Tenant and Project boundaries, node providers, and infrastructure availability.
- vCluster provides clusters that consume instances as private nodes, and can run its own control plane on one.
- vNode adds runtime isolation for workloads that need privileged capabilities, such as Docker-in-Docker or
hostPID.