TELCODOCS-356: Added modules for day 2 updates to firmware settings and components..

Author: johnwilkins

installing/installing_bare_metal/ipi/ipi-install-post-installation-configuration.adoc

@@ -42,7 +42,9 @@ include::modules/bmo-about-the-hostfirmwaresettings-resource.adoc[leveloffset=+2
 // Getting the HostFirmwareSettings resource
 include::modules/bmo-getting-the-hostfirmwaresettings-resource.adoc[leveloffset=+2]
 // Editing the HostFirmwareSettings resource
-include::modules/bmo-editing-the-hostfirmwaresettings-resource.adoc[leveloffset=+2]
+include::modules/bmo-editing-the-hostfirmwaresettings-resource-of-a-provisioned-host.adoc[leveloffset=+2]
+// Patching the HostFirmawareSettings resource
+include::modules/bmo-patching-the-hostfirmwaresettings-resource.adoc[leveloffset=+2]
 // Verifying the HostFirmware Settings resource is valid
 include::modules/bmo-verifying-the-hostfirmware-settings-resource-is-valid.adoc[leveloffset=+2]
 // About the FirmwareSchema resource
@@ -54,4 +56,10 @@ include::modules/bmo-about-the-hostfirmwarecomponents-resource.adoc[leveloffset=
 // Getting the HostFirmwareComponents resource
 include::modules/bmo-getting-the-hostfirmwarecomponents-resource.adoc[leveloffset=+2]
 // Editing the HostFirmwareComponents resource
-include::modules/bmo-editing-the-hostfirmwarecomponents-resource.adoc[leveloffset=+2]
+include::modules/bmo-editing-the-hostfirmwarecomponents-resource-of-a-provisioned-host.adoc[leveloffset=+2]
+// Patching the HostFirmawareComponents resource
+include::modules/bmo-patching-the-hostfirmwarecomponents-resource.adoc[leveloffset=+2]
+// About the HostUpdatePolicy resource
+include::modules/bmo-about-the-hostupdatepolicy-resource.adoc[leveloffset=+2]
+// Setting the HostUpdatePolicy resource
+include::modules/bmo-setting-the-hostupdatepolicy-resource.adoc[leveloffset=+2]

modules/bmo-about-the-hostfirmwaresettings-resource.adoc

@@ -13,6 +13,11 @@ The `HostFirmwareSettings` resource contains two sections:
 . The `HostFirmwareSettings` spec.
 . The `HostFirmwareSettings` status.
 
+[NOTE]
+====
+Reading and modifying firmware settings is only supported for drivers based on the vendor-independent Redfish protocol, Fujitsu iRMC or HP iLO.
+====
+
 == The `HostFirmwareSettings` spec
 
 The `spec` section of the `HostFirmwareSettings` resource defines the desired state of the host's BIOS, and it is empty by default. Ironic uses the settings in the `spec.settings` section to update the baseboard management controller (BMC) when the host is in the `Preparing` state. Use the `FirmwareSchema` resource to ensure that you do not send invalid name/value pairs to hosts. See "About the FirmwareSchema resource" for additional details.

modules/bmo-about-the-hostupdatepolicy-resource.adoc

@@ -0,0 +1,34 @@
+// This is included in the following assemblies:
+//
+// * installing/installing_bare_metal/ipi/ipi-install-post-installation-configuration.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="bmo-about-the-hostupdatepolicy-resource_{context}"]
+= About the HostUpdatePolicy resource
+
+You can use the `HostUpdatePolicy` resource to enable or disable applying live updates to the firmware settings, BMC settings, or firmware settings of each bare-metal host. By default, the Operator disables live updates to already provisioned bare-metal hosts by default.
+
+.The `HostUpdatePolicy` spec
+
+The `spec` section of the `HostUpdatePolicy` resource provides two settings:
+
+`firmwareSettings`:: This setting corresponds to the `HostFirmwareSettings` resource. 
+
+`firmwareUpdates`:: This setting corresponds to the `HostFirmwareComponents` resource.
+
+When you set the value to `onPreparing`, you can only update the host during provisioning, which is the default setting. When you set the value to `onReboot`, you can update a provisioned host by applying the resource and rebooting the bare-metal host. Then, follow the procedure for editing the `HostFirmwareSettings` or `HostFirmwareComponents` resource.
+
+.Example `HostUpdatePolicy` resource
+[source,yaml]
+----
+apiVersion: metal3.io/v1alpha1
+kind: HostUpdatePolicy
+metadata:
+  name: <hostname> <1>
+  namespace: openshift-machine-api
+spec:
+  firmwareSettings: <setting> <2>
+  firmwareUpdates: <setting>
+----
+<1> The name of the bare-metal host.
+<2> The update policy setting. Specify `onPreparing` to disable live updates. Specify `onReboot` to enable live updates.

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

@@ -12,7 +12,7 @@ image::715_OpenShift_Bare_Metal_Operator_updates_0624.png[BMO architecture overv
 
 .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 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` resource or update this information.
 
 The `BareMetalHost` resource features provisioning information such as the following:
 
@@ -39,7 +39,7 @@ You must adhere to the schema specific to the vendor firmware when you edit the
 ====
 
 .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.
+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. You can use the `FirmwareSchema` resource to identify valid values that 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.
 
@@ -51,3 +51,7 @@ Metal^3^ provides the `HostFirmwareComponents` resource, which describes BIOS an
 .Additional resources
 * link:https://metal3.io/[Metal^3^ API service for provisioning bare-metal hosts]
 * link:https://ironicbaremetal.org/[Ironic API service for managing bare-metal infrastructure]
+
+.HostUpdatePolicy
+
+The `HostUpdatePolicy` resource can enable or disable live updates to the firmware settings, BMC settings, or BIOS settings of bare-metal hosts. By default, the `HostUpdatePolicy` resource for each bare-metal host restricts updates to hosts during provisioning. You must modify the `HostUpdatePolicy` resource for a host when you want to update the firmware settings, BMC settings, or BIOS settings after provisioning the host.

modules/bmo-config-using-bare-metal-operator.adoc

@@ -11,7 +11,7 @@ When deploying {product-title} on bare-metal hosts, there are times when you nee
 You can use the Bare Metal Operator (BMO) to provision, manage, and inspect bare-metal hosts in your cluster. The BMO can complete the following operations:
 
 * Provision bare-metal hosts to the cluster with a specific image.
-* Turn on or off a host.
+* Turn a host on or off.
 * Inspect hardware details of the host and report them to the bare-metal host.
 * Upgrade or downgrade a host's firmware to a specific version.
 * Inspect firmware and configure BIOS settings.
@@ -23,9 +23,12 @@ The BMO uses the following resources to complete these tasks:
 * `HostFirmwareSettings`
 * `FirmwareSchema`
 * `HostFirmwareComponents`
+* `HostUpdatePolicy`
 
 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, the `FirmwareSchema` resource, and the `HostFirmwareComponents` resource to detail firmware specifications and upgrade or downgrade firmware 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.
+
+The BMO `HostUpdatePolicy` can enable or disable live updates to the firmware settings, BMC settings, or BIOS settings of a bare-metal host after provisioning the host. By default, the BMO disables live updates.

modules/bmo-editing-the-hostfirmwarecomponents-resource.adoc renamed to modules/bmo-editing-the-hostfirmwarecomponents-resource-of-a-provisioned-host.adoc

@@ -1,28 +1,30 @@
 // This is included in the following assemblies:
 //
 // * installing/installing_bare_metal/ipi/ipi-install-post-installation-configuration.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="bmo-editing-the-hostfirmwarecomponents-resource-of-a-provisioned-host_{context}"]
+= Editing the HostFirmwareComponents resource of a provisioned host
 
-[id="bmo-editing-the-hostfirmwarecomponents-resource_{context}"]
-= Editing the HostFirmwareComponents resource
-
-You can edit the `HostFirmwareComponents` resource of a node.
+You can edit the `HostFirmwareComponents` resource of a provisioned host.
 
 .Procedure
 
-. Get the detailed list of `HostFirmwareComponents` resources:
+. Get the detailed list of `HostFirmwareComponents` resources by running the following command:
 +
 [source,terminal]
 ----
 $ oc get hostfirmwarecomponents -n openshift-machine-api -o yaml
 ----
 
-. Edit a host's `HostFirmwareComponents` resource:
+. Edit the `HostFirmwareComponents` resource by running the following command:
 +
 [source,terminal]
 ----
 $ oc edit <host_name> hostfirmwarecomponents -n openshift-machine-api <1>
 ----
 <1> Where `<host_name>` is the name of the host. The `HostFirmwareComponents` resource will open in the default editor for your terminal.
+
+. Make the appropriate edits.
 +
 .Example output
 [source,yaml]
@@ -76,49 +78,49 @@ status:
 <1> To set a BIOS version, set the `name` attribute to `bios`.
 <2> To set a BIOS version, set the `url` attribute to the URL for the firmware version of the BIOS.
 <3> To set a BMC version, set the `name` attribute to `bmc`.
-<4> To set a BMC version, set the `url` attribute to the URL for the firmware verison of the BMC.
+<4> To set a BMC version, set the `url` attribute to the URL for the firmware version of the BMC.
 
 . Save the changes and exit the editor.
 
-. Get the host’s machine name:
+. Get the host machine name by running the following command:
 +
 [source,terminal]
 ----
 $ oc get bmh <host_name> -n openshift-machine name <1>
 ----
-<1> Where `<host_name>` is the name of the host. The machine name appears under the `CONSUMER` field.
+<1> Where `<host_name>` is the name of the host. The terminal displays the machine name under the `CONSUMER` field.
 
-. Annotate the machine to delete it from the machine set:
+. Annotate the machine to delete it from the machine set by running the following command:
 +
 [source,terminal]
 ----
 $ oc annotate machine <machine_name> machine.openshift.io/delete-machine=true -n openshift-machine-api <1>
 ----
 <1> Where `<machine_name>` is the name of the machine to delete.
 
-. Get a list of nodes and count the number of worker nodes:
+. Get a list of nodes and count the number of worker nodes by running the following command:
 +
 [source,terminal]
 ----
 $ oc get nodes
 ----
 
-. Get the machine set:
+. Get the machine set by running the following command:
 +
 [source,terminal]
 ----
 $ oc get machinesets -n openshift-machine-api
 ----
 
-. Scale the machine set:
+. Scale down the machine set by running the following command:
 +
 [source,terminal]
 ----
 $ oc scale machineset <machineset_name> -n openshift-machine-api --replicas=<n-1> <1>
 ----
 <1> Where `<machineset_name>` is the name of the machine set and `<n-1>` is the decremented number of worker nodes.
 
-. When the host enters the `Available` state, scale up the machine set to make the `HostFirmwareComponents` resource changes take effect:
+. When the host enters the `Available` state, scale up the machine set to make the `HostFirmwareComponents` resource changes take effect by running the following command:
 +
 [source,terminal]
 ----

modules/bmo-editing-the-hostfirmwaresettings-resource.adoc renamed to modules/bmo-editing-the-hostfirmwaresettings-resource-of-a-provisioned-host.adoc

@@ -3,27 +3,30 @@
 // * installing/installing_bare_metal/ipi/ipi-install-post-installation-configuration.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="bmo-editing-the-hostfirmwaresettings-resource_{context}"]
-= Editing the HostFirmwareSettings resource
+[id="bmo-editing-the-hostfirmwaresettings-resource-of-a-provisioned-host_{context}"]
+= Editing the HostFirmwareSettings resource of a provisioned host
 
-You can edit the `HostFirmwareSettings` of provisioned hosts.
+To make changes to the `HostFirmwareSettings` spec for a provisioned host, perform the following actions:
+
+* Delete the host from the machine set.
+* Scale down the machine set.
+* Scale up the machine set to make the changes take effect.
 
 [IMPORTANT]
 ====
 You can only edit hosts when they are in the `provisioned` state, excluding read-only values. You cannot edit hosts in the `externally provisioned` state.
-
 ====
 
 .Procedure
 
-. Get the list of `HostFirmwareSettings` resources:
+. Get the list of `HostFirmwareSettings` resources by running the following command:
 +
 [source,terminal]
 ----
 $ oc get hfs -n openshift-machine-api
 ----
 
-. Edit a host's `HostFirmwareSettings` resource:
+. Edit the host `HostFirmwareSettings` resource by running the following command:
 +
 [source,terminal]
 ----
@@ -32,7 +35,7 @@ $ oc edit hfs <host_name> -n openshift-machine-api
 +
 Where `<host_name>` is the name of a provisioned host. The `HostFirmwareSettings` resource will open in the default editor for your terminal.
 
-. Add name/value pairs to the `spec.settings` section:
+. Add name and value pairs to the `spec.settings` section by running the following command:
 +
 .Example
 [source,terminal]
@@ -45,16 +48,16 @@ spec:
 
 . Save the changes and exit the editor.
 
-. Get the host's machine name:
+. Get the host's machine name by running the following command:
 +
 [source,terminal]
 ----
  $ oc get bmh <host_name> -n openshift-machine name
 ----
 +
-Where `<host_name>` is the name of the host. The machine name appears under the `CONSUMER` field.
+Where `<host_name>` is the name of the host. The terminal displays the machine name under the `CONSUMER` field.
 
-. Annotate the machine to delete it from the machineset:
+. Annotate the machine to delete it from the machine set by running the following command:
 +
 [source,terminal]
 ----
@@ -63,34 +66,34 @@ $ oc annotate machine <machine_name> machine.openshift.io/delete-machine=true -n
 +
 Where `<machine_name>` is the name of the machine to delete.
 
-. Get a list of nodes and count the number of worker nodes:
+. Get a list of nodes and count the number of worker nodes by running the following command:
 +
 [source,terminal]
 ----
 $ oc get nodes
 ----
 
-. Get the machineset:
+. Get the machine set by running the following command:
 +
 [source,terminal]
 ----
 $ oc get machinesets -n openshift-machine-api
 ----
 
-. Scale the machineset:
+. Scale the machine set by running the following command:
 +
 [source,terminal]
 ----
 $ oc scale machineset <machineset_name> -n openshift-machine-api --replicas=<n-1>
 ----
 +
-Where `<machineset_name>` is the name of the machineset and `<n-1>` is the decremented number of worker nodes.
+Where `<machineset_name>` is the name of the machine set and `<n-1>` is the decremented number of worker nodes.
 
-. When the host enters the `Available` state, scale up the machineset to make the `HostFirmwareSettings` resource changes take effect:
+. When the host enters the `Available` state, scale up the machine set to make the `HostFirmwareSettings` resource changes take effect by running the following command:
 +
 [source,terminal]
 ----
 $ oc scale machineset <machineset_name> -n openshift-machine-api --replicas=<n>
 ----
 +
-Where `<machineset_name>` is the name of the machineset and `<n>` is the number of worker nodes.
+Where `<machineset_name>` is the name of the machine set and `<n>` is the number of worker nodes.

modules/bmo-getting-the-firmwareschema-resource.adoc

@@ -10,14 +10,14 @@ Each host model from each vendor has different BIOS settings. When editing the `
 
 .Procedure
 
-. To get a list of `FirmwareSchema` resource instances, execute the following:
+. Get the list of `FirmwareSchema` resource instances by running the following command:
 +
 [source,terminal]
 ----
 $ oc get firmwareschema -n openshift-machine-api
 ----
 
-. To get a particular `FirmwareSchema` instance, execute:
+. Get a particular `FirmwareSchema` instance by running the following command:
 +
 [source,terminal]
 ----

modules/bmo-getting-the-hostfirmwarecomponents-resource.adoc

@@ -1,29 +1,29 @@
 // This is included in the following assemblies:
 //
 // * installing/installing_bare_metal/ipi/ipi-install-post-installation-configuration.adoc
-
+:_mod-docs-content-type: PROCEDURE
 [id="bmo-getting-the-hostfirmwarecomponents-resource_{context}"]
 = Getting the HostFirmwareComponents resource
 
 The `HostFirmwareComponents` resource contains the specific firmware version of the BIOS and baseboard management controller (BMC) of a physical host. You must get the `HostFirmwareComponents` resource for a physical host to review the firmware version and status.
 
 .Procedure
 
-. Get the detailed list of `HostFirmwareComponents` resources:
+. Get the detailed list of `HostFirmwareComponents` resources by running the following command:
 +
 [source,terminal]
 ----
 $ oc get hostfirmwarecomponents -n openshift-machine-api -o yaml
 ----
 
-. Get the list of `HostFirmwareComponents` resources:
+. Get the list of `HostFirmwareComponents` resources by running the following command:
 +
 [source,terminal]
 ----
 $ oc get hostfirmwarecomponents -n openshift-machine-api
 ----
 
-. Get the `HostFirmwareComponents` resource for a particular host:
+. Get the `HostFirmwareComponents` resource for a particular host by running the following command:
 +
 [source,terminal]
 ----