This is a cache of https://docs.okd.io/latest/scalability_and_performance/managing-bare-metal-hosts.html. It is a snapshot of the page at 2026-02-21T19:11:20.543+0000.
Managing bare metal hosts | Scalability and performance | OKD 4
  1. Documentation
×

Managing bare-metal hosts

About bare metal hosts and nodes

To provision a Fedora CoreOS (FCOS) bare-metal host as a node in your cluster, first create a MachineSet custom resource (CR) object that corresponds to bare-metal host hardware.

Bare-metal host compute machine sets describe infrastructure components specific to your configuration. You apply specific Kubernetes labels to these compute machine sets and then update the infrastructure components to run on only those machines.

When you scale up the relevant MachineSet CR that contains a metal3.io/autoscale-to-hosts annotation, Machine CRs are created automatically. OKD uses Machine CRs to provision the bare-metal node that corresponds to the host as specified in the MachineSet CR.

Maintaining bare metal hosts

To ensure your cluster inventory accurately reflects your physical infrastructure, maintain the details of the bare-metal host configurations by using the OKD web console.

Procedure

  1. From the web console, comlete the following steps:

    1. Navigate to Compute → Bare Metal Hosts.

    2. Select a task from the Actions drop-down menu.

    3. Manage items such as baseboard management controller (BMC) details, boot MAC address for the host, enable power management, and so on. You can also review the details of the network interfaces and drives for the host.

  2. Move a bare-metal host into maintenance mode. When you move a host into maintenance mode, the scheduler moves all managed workloads off the corresponding bare-metal node. No new workloads are scheduled while in maintenance mode.

  3. Deprovision a bare-metal host in the web console. Deprovisioning a host does the following actions:

    1. Annotates the bare-metal host CR with cluster.k8s.io/delete-machine: true.

    2. Scales down the related compute machine set.

      Powering off the host without first moving the daemon set and unmanaged static pods to another node can cause service disruption and loss of data.
Additional resources

Adding a bare metal host to the cluster using the web console

To integrate physical hardware into your cluster, you can add bare-metal hosts by using the web console. By adding these hosts, you can provision and manage these nodes directly through the web console.

Prerequisites

  • Install an FCOS cluster on bare metal.

  • Log in as a user with cluster-admin privileges.

Procedure

  1. In the web console, navigate to Compute → Bare Metal Hosts.

  2. Select Add Host → New with Dialog.

  3. Specify a unique name for the new bare metal host.

  4. Set the Boot MAC address.

  5. Set the Baseboard Management Console (BMC) Address.

  6. Enter the user credentials for the host’s baseboard management controller (BMC).

  7. Select to power on the host after creation, and select Create.

  8. Scale up the number of replicas to match the number of available bare metal hosts. Navigate to Compute → MachineSets, and increase the number of machine replicas in the cluster by selecting Edit Machine count from the Actions drop-down menu.

    You can also manage the number of bare-metal nodes by using the oc scale command and the appropriate bare-metal compute machine set.

Adding a bare-metal host to the cluster using YAML in the web console

You can add bare-metal hosts to the cluster in the web console by using a YAML file that describes the bare-metal host.

Prerequisites

  • Install a FCOS compute machine on bare-metal infrastructure for use in the cluster.

  • Log in as a user with cluster-admin privileges.

  • Create a Secret CR for the bare-metal host.

Procedure

  1. In the web console, navigate to Compute → Bare Metal Hosts.

  2. Select Add Host → New from YAML.

  3. Copy and paste the below YAML, modifying the relevant fields with the details of your host:

    apiVersion: metal3.io/v1alpha1
kind: BareMetalHost
metadata:
  name: <bare_metal_host_name>
spec:
  online: true
  bmc:
    address: <bmc_address>
    credentialsName: <secret_credentials_name>
    disableCertificateVerification: True
  bootMACAddress: <host_boot_mac_address>
# ...

    where:

    spec.bmc.credentialsName

    Specifies a reference to a valid Secret CR. The Bare Metal Operator cannot manage the bare-metal host without a valid Secret referenced in the credentialsName. For more information about secrets and how to create them, see "Understanding secrets".

    spec.bmc.disableCertificateVerification

    Specifies whether to require TLS host validation between the cluster and the baseboard management controller (BMC). When this field is set to true, TLS host validation is disabled.

  4. Select Create to save the YAML and create the new bare-metal host.

  5. Scale up the number of replicas to match the number of available bare-metal hosts. Navigate to Compute → MachineSets, and increase the number of machines in the cluster by selecting Edit Machine count from the Actions drop-down menu.

    You can also manage the number of bare-metal nodes by using the oc scale command and the appropriate bare-metal compute machine set.
Additional resources

Automatically scaling machines to the number of available bare-metal hosts

To automatically create the number of Machine objects that matches the number of available BareMetalHost objects, add a metal3.io/autoscale-to-hosts annotation to the MachineSet object.

Prerequisites

  • Install FCOS bare-metal compute machines for use in the cluster, and create corresponding BareMetalHost objects.

  • Install the OpenShift CLI (oc).

  • Log in as a user with cluster-admin privileges.

Procedure

  1. To configure automatic scaling for a compute machine set, annotate the compute machine set by running the following command:

    $ oc annotate machineset <machineset> -n openshift-machine-api 'metal3.io/autoscale-to-hosts=<any_value>'

    • <machineset>: Specifies the name of the compute machine set that you want to configure for automatic scaling.

    • <any_value> Specifies is a value, such as true or "".

  2. Wait for the new scaled machines to start.

    The BareMetalHost object continues to be counted against the MachineSet that the Machine object was created from when the following conditions are met:

    • You use a BareMetalHost object to create a machine in the cluster.

    • You subsequently change labels or selectors on the BareMetalHost.

Removing bare-metal hosts from the provisioner node

In certain circumstances, you might want to temporarily remove bare-metal hosts from the provisioner node. For example, to prevent the management of the number of Machine objects that matches the number of available BareMetalHost objects, add a baremetalhost.metal3.io/detached annotation to the MachineSet object.

Consider an example during provisioning when a bare-metal host reboot is triggered by using the OKD administration console or as a result of a Machine Config Pool update. In this case, OKD logs into the integrated Dell Remote Access Controller (iDRAC) and issues a delete of the job queue.

This annotation has an effect for only BareMetalHost objects that are in either Provisioned, ExternallyProvisioned, or Ready/Available states.
Prerequisites

  • Install FCOS bare-metal compute machines for use in the cluster and create corresponding BareMetalHost objects.

  • Install the OpenShift CLI (oc).

  • Log in as a user with cluster-admin privileges.

Procedure

  1. To configure automatic scaling for a compute machine set, annotate the compute machine set by running the following command:

    $ oc annotate machineset <machineset> -n openshift-machine-api 'baremetalhost.metal3.io/detached'

    Wait for the new machines to start.

    When you use a BareMetalHost object to create a machine in the cluster and labels or selectors are subsequently changed on the BareMetalHost, the BareMetalHost object continues to be counted against the MachineSet that the Machine object was created from.

  2. In the provisioning use case, remove the annotation after the reboot is complete by using the following command:

    $ oc annotate machineset <machineset> -n openshift-machine-api 'baremetalhost.metal3.io/detached-'
Additional resources

Powering off bare-metal hosts by using the web console

You can power off bare-metal cluster hosts in the web console. Before you power off a host, mark the node as unschedulable and drain all pods and workloads from the node.

Prerequisites

  • You have installed a FCOS compute machine on bare-metal infrastructure for use in the cluster.

  • You have logged in as a user with cluster-admin privileges.

  • You have configured the host to be managed and have added Baseboard Management Console credentials for the cluster host. You can add BMC credentials by applying a Secret custom resource (CR) in the cluster or by logging in to the web console and configuring the bare-metal host to be managed.

Procedure

  1. Navigate to Nodes and select the node that you want to power off. Expand the Actions menu and select Mark as unschedulable.

  2. Manually delete or relocate running pods on the node by adjusting the pod deployments or scaling down workloads on the node to zero. Wait for the drain process to complete.

  3. Navigate to Compute → Bare Metal Hosts.

  4. Expand the Options menu for the bare-metal host that you want to power off, and select Power Off.

  5. Select Immediate power off.

Powering off bare-metal hosts by using the CLI

You can power off bare-metal cluster hosts by applying a patch in the cluster by using the OpenShift CLI (oc). Before you power off a host, mark the node as unschedulable and drain all pods and workloads from the node.

Prerequisites

  • You have installed a FCOS compute machine on bare-metal infrastructure for use in the cluster.

  • You have logged in as a user with cluster-admin privileges.

  • You have configured the host to be managed and have added Baseboard Management Console credentials for the cluster host. You can add BMC credentials by applying a Secret custom resource (CR) in the cluster or by logging in to the web console and configuring the bare-metal host to be managed.

Procedure

  1. Get the name of the managed bare-metal host by entering the following command:

    $ oc get baremetalhosts -n openshift-machine-api -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.provisioning.state}{"\n"}{end}'
    Example output
    master-0.example.com  managed
master-1.example.com  managed
master-2.example.com  managed
worker-0.example.com  managed
worker-1.example.com  managed
worker-2.example.com  managed

  2. Mark the node as unschedulable by entering the following command:

    $ oc adm cordon <bare_metal_host>

    • <bare_metal_host>: Specifies the name of the host that you want to shut down. For example, worker-2.example.com.

  3. Drain all pods on the node by entering the following command:

    $ oc adm drain <bare_metal_host> --force=true

    Pods that are backed by replication controllers are rescheduled to other available nodes in the cluster.

  4. Safely power off the bare-metal host by entering the following command:

    $ oc patch <bare_metal_host> --type json -p '[{"op": "replace", "path": "/spec/online", "value": false}]'

  5. After you power on the host, make the node schedulable for workloads by entering the following command:

    $ oc adm uncordon <bare_metal_host>