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 installing the OS and supplying its networking and startup configuration. This condition does not prove that cloud-init or the services it starts succeeded inside the OS.
  4. Joined — for tenant-cluster worker capacity, the server has joined as a Kubernetes node. For Machines requested outside a tenant cluster and Machines that run a control plane, no worker join is required, so the platform marks this condition satisfied after provisioning.
  5. Ready — the platform's required Machine milestones are satisfied. For a worker, that includes joining the tenant cluster. For an independent or control plane Machine, Joined is satisfied without a worker join, so verify SSH access or cluster API health separately.
  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.

Machines that run a control plane​

A Machine can carry a tenant cluster's control plane instead of joining one as a worker. The platform installs vCluster on the provisioned server as a systemd service. The cluster's API server runs there rather than as a workload on another cluster.

These Machines reach Provisioned the same way as any other. They differ in ordering. A worker waits for its tenant cluster to be online before provisioning, because it needs a live API server to join. A control plane Machine does not wait, because it is what brings that API server up.

See Control plane machines.

Independently provisioned Machines​

An administrator can request a Machine directly, with no tenant cluster attached. The Machine goes through the same Requested, Scheduled, and Provisioned milestones, and the same server selection and cleanup. Because there is no cluster to join, the platform marks Joined satisfied after provisioning without running a join operation. What you get is a provisioned server reachable over SSH.

This is the same Machine model, not a separate one. The only difference is what the platform appends to the cloud-init it generates. Every Machine gets any SSH keys you configured. A worker also gets a Kubernetes join command and a control plane Machine gets the vCluster install script, while an independently provisioned Machine gets nothing further.

See Independently provisioned machines for the walkthrough.

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.