Operations

Day-2 operations for vMetal center on managing BareMetalHost resources on the control plane cluster. This page covers adding and removing servers, checking fleet capacity, and where to find guidance for other common tasks. Commands on this page use <control-plane-context>, the cluster referenced by NodeProvider.spec.metal3.clusterRef.cluster.

Set your namespace once. Every command on this page updates automatically.

Modify the following with your specific values to replace them across the whole page:

NAMESPACE

Adding servers

A physical server joins the pool by creating a BareMetalHost resource and a Secret containing its BMC credentials. Both must live in the NodeProvider's namespace on the control plane cluster.

apiVersion: v1
kind: Secret
metadata:
  name: server-01-bmc
  namespace: <namespace>
type: Opaque
stringData:
  username: admin
  password: <bmc-password>
---
apiVersion: metal3.io/v1alpha1
kind: BareMetalHost
metadata:
  name: server-01
  namespace: <namespace>
  labels:
    role: compute
spec:
  bmc:
    address: redfish://192.168.1.100/redfish/v1/Systems/1
    credentialsName: server-01-bmc
  bootMACAddress: "aa:bb:cc:dd:ee:01"

kubectl --context <control-plane-context> apply -f server.yaml

For the full set of BareMetalHost fields and bulk registration, see Configuration.

After creation, the BMO begins registration immediately. The server moves through registering → inspecting → available automatically. Inspection collects hardware inventory and typically takes a few minutes. The server is not eligible for provisioning until it reaches available.

Verify a server is ready

kubectl --context <control-plane-context> get baremetalhost server-01 -n my-metal3-namespace \
-o jsonpath='{.status.provisioning.state}'

A response of available means the server is ready to claim. See Troubleshooting if the server stalls in registering or inspecting.

Check hardware details

After inspection, the BMH records the server's hardware inventory:

kubectl --context <control-plane-context> get baremetalhost server-01 -n my-metal3-namespace \
-o jsonpath='{.status.hardwareDetails}' | jq .

This includes CPU count, memory, NIC information, and disk inventory. Verify it matches the expected hardware before the server is provisioned into production.

Removing servers

Permanent removal

If a Machine holds the server, delete it from the vCluster Platform UI or API first. The platform deprovisions the server and returns it to available. Then delete the BareMetalHost:

kubectl --context <control-plane-context> delete baremetalhost server-01 -n my-metal3-namespace

After the normal sequence, the Machine and its NodeClaim are already gone and the platform has released its IP address. Deleting the now-unclaimed BareMetalHost only removes the server from the inventory.

Also delete the BMC credential Secret if it is no longer needed:

kubectl --context <control-plane-context> delete secret server-01-bmc -n my-metal3-namespace

If the server is permanently unreachable and cannot complete normal deprovisioning, delete the BareMetalHost, then delete its Machine from the platform. During Machine deletion, the driver treats the missing host as already removed, releases the IP, and finishes deleting the NodeClaim. The server does not go through the normal deprovisioning cycle, so its disk is not cleaned. Do not use this sequence for a reachable server that can be deprovisioned normally.

Temporarily withhold a server

To stop an available server being claimed for new Machines, break the selectors that match it. Remove or change a label that every matching node type selector requires. The server stays registered. For example, if the server is eligible because its role is compute, remove that label:

kubectl --context <control-plane-context> label baremetalhost server-01 \
  -n <namespace> role-

Merely adding a maintenance=true label does not exclude a server unless every applicable node type selector explicitly requires that label not to exist. Label changes do not affect servers that are already provisioned. A server already claimed by a Machine remains claimed until that Machine is deleted.

Restore the selection label to return the server to the eligible pool:

kubectl --context <control-plane-context> label baremetalhost server-01 \
  -n <namespace> role=compute

Checking fleet capacity

Get a view of all servers and their current states:

kubectl --context <control-plane-context> get baremetalhost -n my-metal3-namespace \
-o custom-columns='NAME:.metadata.name,STATE:.status.provisioning.state,ERROR:.status.errorMessage'

Count available servers:

kubectl --context <control-plane-context> get baremetalhost -n my-metal3-namespace -o json | \
jq '[.items[] | select(.status.provisioning.state=="available")] | length'

A server in available is ready for a new Machine request. A server in provisioning or provisioned is claimed. A server in error needs attention before it can be used again. See Troubleshooting for how to resolve error states.

Other day-2 tasks

Task	Where to find it
Rotate BMC credentials	Production and Security
Release an independently provisioned machine and reclaim its server	Independently provisioned machines
Understand what scale-down does to a tenant cluster node	Cluster attachment
Update OS images across a fleet	GPU Fleet Operations
Update server labels	GPU Fleet Operations
Expand the IP address pool	Troubleshooting