Merge pull request #53597 from rohennes/TELCODOCS-804-BMO

TELCODOCS-804 adding conceptual info about the BMO

Author: jab-rh

images/302_OpenShift_Bare_Metal_Operator_0223.png

@@ -0,0 +1,29 @@
+// This is included in the following assemblies:
+//
+// post_installation_configuration/bare-metal-configuration.adoc
+
+:_module-type: CONCEPT
+[id="bmo-about-the-bare-metal-operator_{context}"]
+= About the Bare Metal Operator
+
+Use the Bare Metal Operator (BMO) to provision, manage, and inspect bare-metal hosts in your cluster. 
+ 
+The BMO uses three resources to complete these tasks: 
+
+* `BareMetalHost`
+* `HostFirmwareSettings`
+* `FirmwareSchema`
+
+The BMO maintains an inventory of the physical hosts in the cluster by mapping each bare-metal host to an instance of the `BareMetalHost` custom resource definition. Each `BareMetalHost` resource features hardware, software, and firmware details. The BMO continually inspects the bare-metal hosts in the cluster to ensure each `BareMetalHost` resource accurately details the components of the corresponding host. 
+
+The BMO also uses the `HostFirmwareSettings` resource and the `FirmwareSchema` resource to detail firmware specifications for the bare-metal host. 
+
+The BMO interfaces with bare-metal hosts in the cluster by using the Ironic API service. The Ironic service uses the Baseboard Management Controller (BMC) on the host to interface with the machine. 
+
+Some common tasks you can complete by using the BMO include the following:
+
+* Provision bare-metal hosts to the cluster with a specific image
+* Format a host's disk contents before provisioning or after deprovisioning
+* Turn on or off a host
+* Change firmware settings
+* View the host's hardware details 

modules/bmo-about-the-bare-metal-operator.adoc

@@ -0,0 +1,48 @@
+// This is included in the following assemblies:
+//
+// post_installation_configuration/bare-metal-configuration.adoc
+:_content-type: CONCEPT
+[id="bmo-bare-metal-operator-architecture_{context}"]
+= Bare Metal Operator architecture
+
+The Bare Metal Operator (BMO) uses three resources to provision, manage, and inspect bare-metal hosts in your cluster. The following diagram illustrates the architecture of these resources:
+
+image::302_OpenShift_Bare_Metal_Operator_0223.png[BMO architecture overview]
+
+.BareMetalHost
+
+The `BareMetalHost` resource defines a physical host and its properties. When you provision a bare-metal host to the cluster, you must define a `BareMetalHost` resource for that host. For ongoing management of the host, you can inspect the information in the `BareMetalHost` or update this information. 
+
+The `BareMetalHost` resource features provisioning information such as the following:
+
+* Deployment specifications such as the operating system boot image or the custom RAM disk 
+* Provisioning state 
+* Baseboard Management Controller (BMC) address
+* Desired power state
+
+The `BareMetalHost` resource features hardware information such as the following: 
+
+* Number of CPUs
+* MAC address of a NIC
+* Size of the host's storage device
+* Current power state
+
+.HostFirmwareSettings
+You can use the `HostFirmwareSettings` resource to retrieve and manage the firmware settings for a host. When a host moves to the `Available` state, the Ironic service reads the host's firmware settings and creates the `HostFirmwareSettings` resource. There is a one-to-one mapping between the `BareMetalHost` resource and the `HostFirmwareSettings` resource. 
+
+You can use the `HostFirmwareSettings` resource to inspect the firmware specifications for a host or to update a host's firmware specifications. 
+
+[NOTE]
+====
+You must adhere to the schema specific to the vendor firmware when you edit the `spec` field of the `HostFirmwareSettings` resource. This schema is defined in the read-only `FirmwareSchema` resource.
+====
+
+.FirmwareSchema
+Firmware settings vary among hardware vendors and host models. A `FirmwareSchema` resource is a read-only resource that contains the types and limits for each firmware setting on each host model. The data comes directly from the BMC by using the Ironic service. The `FirmwareSchema` resource enables you to identify valid values you can specify in the `spec` field of the `HostFirmwareSettings` resource. 
+
+A `FirmwareSchema` resource can apply to many `BareMetalHost` resources if the schema is the same. 
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://metal3.io/[Metal³ API service for provisioning bare-metal hosts]
+* link:https://ironicbaremetal.org/[Ironic API service for managing bare-metal infrastructure]

modules/con_bmo-bare-metal-operator-architecture.adoc

@@ -6,13 +6,10 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-When deploying {product-title} on bare metal hosts, there are times when you need to make changes to the host either before or after provisioning. This can include inspecting the host's hardware, firmware, and BIOS details. It can also include formatting disks or changing modifiable BIOS settings. There are two resources that you can use with the Bare Metal Operator (BMO):
-
-* `BareMetalHost`
-* `HostFirmwareSettings`
-
-There is also a read-only `FirmwareSchema` resource, which you can use to determine the valid values that you can send to a host when making changes to host firmware settings.
+When deploying {product-title} on bare metal hosts, there are times when you need to make changes to the host either before or after provisioning. This can include inspecting the host's hardware, firmware, and firmware details. It can also include formatting disks or changing modifiable firmware settings. 
 
+include::modules/bmo-about-the-bare-metal-operator.adoc[leveloffset=+1]
+include::modules/con_bmo-bare-metal-operator-architecture.adoc[leveloffset=+2]
 include::modules/bmo-about-the-baremetalhost-resource.adoc[leveloffset=+1]
 include::modules/bmo-getting-the-baremetalhost-resource.adoc[leveloffset=+1]