---
title: Managing bare-metal hosts
---

# Managing bare-metal hosts {#managing-bare-metal-hosts}

You can configure bare-metal hosts directly within OpenShift Container Platform. To provision and manage nodes in a bare-metal cluster, use `Machine` and `MachineSet` custom resources (CRs).

## About bare metal hosts and nodes {#about-bare-metal-hosts-and-nodes_managing-bare-metal-hosts}

To provision a Red Hat Enterprise Linux CoreOS (RHCOS) 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. OpenShift Container Platform uses `Machine` CRs to provision the bare-metal node that corresponds to the host as specified in the `MachineSet` CR.

## Maintaining bare metal hosts {#maintaining-bare-metal-hosts_managing-bare-metal-hosts}

You can maintain the details of the bare metal hosts in your cluster from the OpenShift Container Platform 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.

      > [!NOTE]
      > 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**
{._additional-resources}

- [Adding compute machines to bare metal](/openshift-docs-markdown/machine_management/user_infra/adding-bare-metal-compute-user-infra#adding-bare-metal-compute-user-infra)

### Adding a bare metal host to the cluster using the web console {#adding-bare-metal-host-to-cluster-using-web-console_managing-bare-metal-hosts}

You can add bare-metal hosts to the cluster by using the web console.

**Prerequisites**

- Install an RHCOS 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 baseboard management controller (BMC) of the host.
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.

   > [!NOTE]
   > 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 {#adding-bare-metal-host-to-cluster-using-yaml_managing-bare-metal-hosts}

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 RHCOS 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:

   ```yaml
   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.

1. Select **Create** to save the YAML and create the new bare-metal host.
2. 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.

   > [!NOTE]
   > 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**
{._additional-resources}

- [Understanding secrets](/openshift-docs-markdown/nodes/pods/nodes-pods-secrets#nodes-pods-secrets-about_nodes-pods-secrets)

### Automatically scaling machines to the number of available bare-metal hosts {#automatically-scaling-machines-to-available-bare-metal-hosts_managing-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 RHCOS 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:

   ```terminal
   $ 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.

   > [!NOTE]
   > 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 {#removing-bare-metal-hosts-from-provisioner_managing-bare-metal-hosts}

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 OpenShift Container Platform administration console or as a result of a Machine Config Pool update. In this case, OpenShift Container Platform logs into the integrated Dell Remote Access Controller (iDRAC) and issues a delete of the job queue.

> [!NOTE]
> This annotation has an effect for only `BareMetalHost` objects that are in either `Provisioned`, `ExternallyProvisioned`, or `Ready/Available` states.

**Prerequisites**

- Install RHCOS 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:

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

   Wait for the new machines to start.

   > [!NOTE]
   > 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:

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

**Additional resources**
{._additional-resources}

- [Expanding the cluster](/openshift-docs-markdown/installing/installing_bare_metal/bare-metal-expanding-the-cluster#bare-metal-expanding-the-cluster)
- [MachineHealthChecks on bare metal](/openshift-docs-markdown/machine_management/deploying-machine-health-checks#machine-health-checks-bare-metal_deploying-machine-health-checks)

### Powering off bare-metal hosts by using the web console {#powering-off-bare-metal-hosts-web-console_managing-bare-metal-hosts}

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 RHCOS 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 {#powering-off-bare-metal-hosts-cli_managing-bare-metal-hosts}

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 RHCOS 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:

   ```terminal
   $ oc get baremetalhosts -n openshift-machine-api -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.provisioning.state}{"\n"}{end}'
   ```

   ```terminal {title="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:

   ```terminal
   $ 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:

   ```terminal
   $ 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:

   ```terminal
   $ 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:

   ```terminal
   $ oc adm uncordon <bare_metal_host>
   ```