Skip to main content
Version: v5.0 Stable

Machine inventory

Enterprise
Available in these plansFreeDevProdScale
Machine Management

Free, Dev, Prod, and Scale are vCluster Platform license plans. Open source does not need a license or a Platform connection. See Compare open source and free tiers.

Modify the following with your specific values to replace on the whole page and generate copyable commands:
Requires Platform v5.0 or later

Everything on this page is part of the machine inventory layer introduced in Platform v5.0. For the clusterless provisioning path that doesn't depend on it, see Independently provisioned instances.

A Machine is a read-only mirror of one physical machine in a provider's inventory. The platform's inventory sync creates, updates, and deletes it from what the provider reports. You can't write its spec or status, only add or change its labels and annotations. This is a different object from the instance that claims capacity and the BareMetalHost that the Metal3 driver manages directly.

Machine, NodeClaim, and BareMetalHost​

Three objects describe overlapping things about one physical server, and each answers a different question:

ObjectAnswersWritten by
MachineWhat does the provider's inventory currently say about this server?The platform's inventory sync. Read-only for users.
NodeClaim (instance)Is this server claimed, and by what?The platform, in response to a request. See Instance and server concepts.
BareMetalHostWhat is Metal3 doing to provision or clean this specific server?The Metal3 driver and Bare Metal Operator.

A Machine's identity doesn't depend on a claim. Claimed or not, it exists for as long as the provider reports the server. An instance's identity is the opposite. It exists only for the duration of one claim.

Identity​

A Machine is cluster-scoped. Its resource name is <providerRef>.<provider-native-machine-id>. Metal3 uses the BareMetalHost name, such as metal3-provider.host-042. NICo uses the machine ID reported by the provider. spec.displayName is presentation only, not part of the resource name. When you reference a Machine by name, such as in machineRef below, use the full qualified form.

What you can and can't change​

You can't create or delete a Machine or change its spec or status. The inventory sync owns both, and the spec is immutable once written. You can add or change your own labels and annotations on it, the same way you would on any Kubernetes object.

The following metadata is platform-owned. The API rejects attempts to change it:

  • The machines.vcluster.com/source label, which records which inventory source produced the Machine.
  • The machines.vcluster.com/node-claim annotation, which records the claim holding the Machine.
  • The machines.vcluster.com/provider-labels annotation, and the labels the sync copies from the provider, such as a BareMetalHost's labels. Change those on the provider's own resource.
  • The nico.vcluster.com/instance-type-id label on Machines synced from NICo.
  • The machines.vcluster.com/netbox-device annotation on Machines synced from NetBox.
  • Labels and annotations in the netbox.vcluster.com/ namespace on Machines synced from NetBox.

While an instance holds a Machine, the API also refuses changes to its tenant.vcluster.com/owner and tenant.vcluster.com/exclusive-to labels. See Release and reclaim.

Provider-dependent fields​

status.phase is Pending, Available, Provisioning, Provisioned, Deprovisioning, Maintenance, Error, or Unknown. status.powerState is On, Off, or Unknown, and status.hardware normalizes CPU, memory, storage, GPU, DPU, network, and InfiniBand capabilities across drivers.

Not every provider reports every field. Power state is empty when a driver doesn't support it. The platform UI hides an unavailable value instead of showing a false one. Check which fields your provider reports.

Phase isn't claim occupancy​

status.phase describes the provider's view of the server, not whether a platform claim holds it. A Machine can read Available while a NodeClaim already holds it. This can happen before the claim reaches a phase that the provider recognizes. The reverse can also occur.

The machines.vcluster.com/node-claim annotation is the actual claim signal. The platform sets it to <namespace>/<name> of the NodeClaim currently consuming the Machine. It clears the annotation when the claim is released. Before treating a Machine as free to claim, confirm this annotation is absent. Available alone isn't sufficient evidence.

Sync failures​

If a provider's inventory listing fails, the platform doesn't guess. Existing Machine mirrors are retained, moved to Unknown phase, and marked Synced=False with reason ListFailed. lastSyncTime stays frozen at the last confirmed state rather than advancing, so you can tell a stale mirror from a current one.

A Machine is removed only after a successful inventory listing confirms the provider no longer reports it. A failed listing never deletes Machines, even if the provider would otherwise appear to have fewer servers.

Claim a specific machine​

NodeClaimSpec.MachineRef pins a claim to one named Machine from the provider's inventory. The platform doesn't select from a node type's eligible pool. MachineRef is mutually exclusive with TypeRef, and a pinned claim consumes no node-type capacity or tenant node type quota. Metal3 and NICo support it, as does the external platform provider, which mirrors another platform's inventory. A provider without machine inventory doesn't. Pinning requires the Machine Management license feature.

The referenced Machine must exist, be unclaimed, and belong to the same providerRef as the claim. The API rejects a missing, claimed, or mismatched Machine during admission. For a request made inside a tenant, pinning a Machine that isn't assigned to the tenant is refused with machine "<name>" does not exist. If a pin gets past admission and the Machine is out of reach by the time it's provisioned, the claim fails with the reason InvalidConfiguration.

A pin names no node type, but the node type boundary still applies. At least one node type that selects the Machine has to be allowed by the project's allowedNodeTypes. In a tenant project, that node type also has to be granted to the tenant. The API refuses a pin that fails this check during admission, with machine "<name>" is not covered by a node type this project may use. The check applies when a platform admin creates the claim too, and the admin's error adds the reason.

Apply a NodeClaim that identifies the provider and the full Machine name:

kubectl --context management-context apply -f - <<'EOF'
apiVersion: management.loft.sh/v1
kind: NodeClaim
metadata:
name: pinned-claim
namespace: loft-p-my-project
spec:
# Pin this claim to one Machine from the provider inventory.
displayName: "Pinned to host-042"
providerRef: metal3-provider
machineRef: metal3-provider.host-042
EOF

Verify that the claim was accepted and watch its provisioning phase:

kubectl --context management-context get nodeclaim pinned-claim \
-n loft-p-my-project -w

The claim reaches Available after the provider finishes provisioning the server.

Inventory sources​

Where a Machine's data comes from depends on the provider:

  • Metal3 mirrors its own BareMetalHost inventory directly. Every Metal3-managed server already has a corresponding Machine.
  • NetBox can be configured as a Metal3 inventory source (MachineSourceNetBox). It imports device records instead of relying only on manually registered BareMetalHost resources. Imported Machines carry SourceAttached and Registered conditions that track the NetBox link. When a device is untagged while provisioned or claimed, SourceAttached becomes False with reason Orphaned. This doesn't deprovision anything. It tells an operator to decide whether to release or reclaim the server.

Driver and integration status (including whether NICo and the NetBox import are recommended for general use, not just technically available) is tracked separately and isn't restated here. Check current guidance before depending on either in production.

Admin UI navigation​

Anyone who can list Machines can see the Overview tab in the admin Machines section. The other tabs require the Metal3 feature and platform administrator access.

  • Overview shows the cross-driver Machine inventory described on this page, regardless of which provider produced each entry.
  • Metal3 shows raw BareMetalHost operations specific to the Metal3 driver.
  • Network Attachments shows Metal3-scoped network attachment configuration separately from the Metal3 tab.

This is distinct from the project-facing Instances view, which lists claims (NodeClaim objects), not inventory. See Independently provisioned instances for connecting to a claimed server over SSH from that view.