Skip to main content

Machine and server concepts

A Machine is vMetal's claim on one server, physical or virtual, depending on the driver behind it. This page describes the Machine model at a driver-neutral level. For quick term definitions, see the Glossary. For the Metal3 driver's specific hierarchy and mechanics, see Provisioning model.

Machine and server​

"Machine" and "server" refer to two different objects with two different lifetimes.

A server is the physical or virtual host itself, the thing a driver provisions and hands out. Under the Metal3 driver, a server is a BareMetalHost. A server's identity is independent of any single request for it. It's registered once, inspected once, and then claimed, released, and claimed again many times over its life in the fleet.

A Machine is vMetal's record of one claim on a server. It's created when a tenant cluster or administrator requests capacity, and it's deleted when that capacity is no longer needed. A Machine's identity doesn't outlive the claim. Once it's deleted, the server it claimed doesn't disappear. The driver cleans that server and returns it to the capacity pool, where a later, different Machine can claim it.

This distinction matters because the two objects answer different questions. "Is this server healthy" is a question about the server, answered by checking its BareMetalHost status, BMC connectivity, and inspection results. "Is this Machine ready" is a question about the claim, answered by checking whether scheduling, provisioning, and joining have completed for the current request. A single server can pass through many Machines over its lifetime, each with its own independent lifecycle described below.

Machine lifecycle​

Every Machine, regardless of driver, passes through the same milestones:

Machine lifecycleA Machine moves through six milestones: Requested, Scheduled, Provisioned, Joined, Ready, and Destroyed. Joined applies only to tenant-cluster capacity. After Destroyed, the server it claimed is cleaned and returned to its capacity pool, where a new Machine can claim it.RequestedScheduledProvisionedJoinedReadyDestroyedserver freed for reuse
Click to enlarge
  1. Requested — a tenant cluster or an administrator asks for capacity matching a machine type, and the platform creates the Machine.
  2. Scheduled — vMetal selects an eligible server and claims it for this Machine.
  3. Provisioned — the driver behind that machine type finishes preparing the server by installing an OS, configuring networking, and running any startup automation.
  4. Joined — for tenant-cluster capacity, the server has joined as a Kubernetes node. Machines requested directly by an administrator, outside a tenant cluster, skip this milestone.
  5. Ready — every prior milestone has been reached. This is a single point in time, not a span. A Machine doesn't sit in "ready" before doing anything else. By the time a Machine reaches Ready, the server it claimed is already serving workloads.
  6. Destroyed — the tenant cluster or administrator no longer needs the Machine, and the platform deletes it.

Deleting a Machine doesn't delete the server it claimed. The driver cleans the server and returns it to the machine type's capacity pool, where a later, different Machine can claim it. The exact mechanics and observable states behind each milestone, and the server's own states during cleanup, are driver-specific. This site documents the Metal3 driver's states in depth. See Provisioning model and BareMetalHost states.

How a Machine reaches a tenant cluster​

How a Machine reaches a tenant clusterA tenant cluster requests capacity through Private Nodes or Auto Nodes, creating a NodeClaim. The platform selects an eligible server through the matching machine type, the driver provisions the server, the server joins the tenant cluster as a Kubernetes node, and only then does the Machine reach Ready.Tenant cluster requests capacityPrivate Nodes or Auto NodesNodeClaim createdPlatform selects an eligible serverthrough the matching machine typeDriver provisions the serverJoins the tenant clusteras a Kubernetes nodeMachine ready
Click to enlarge

A tenant cluster requests dedicated capacity through Private Nodes, either directly or automatically through Auto Nodes. That request becomes a NodeClaim, the Kubernetes resource that implements a Machine. The platform selects an eligible server through the matching machine type and claims it. The driver provisions the server, and it joins the tenant cluster as a standard Kubernetes node. Once joined, the Machine reaches Ready. See Cluster attachment for how that join happens.

Who owns what​

LayerOwns
vMetalProvisioning mechanics, driver dispatch, and the Machine and server lifecycles described above.
vCluster PlatformWhich machine types exist, who can request them, and quotas. See Configuration and Security and project isolation.
vClusterRequesting and releasing capacity for a tenant cluster through Private Nodes and Auto Nodes.

Security and ownership boundaries​

Requesting a Machine is governed by project role and machine-type restrictions rather than open to every tenant. The properties that shape how it's provisioned are constrained the same way. See Security and project isolation for the current access model.