Merge "Update docs on ironic boot mode management"11.1.0

1 files changed, 46 insertions, 5 deletions

diff --git a/doc/source/install/include/boot-mode.inc b/doc/source/install/include/boot-mode.inc
index 7895beba6..c528895fc 100644
--- a/doc/source/install/include/boot-mode.inc
+++ b/doc/source/install/include/boot-mode.inc
@@ -3,12 +3,53 @@
 Boot mode support
 -----------------
 
-Most of the bare metal drivers (including the generic ``ipmi`` hardware type)
-support setting of boot mode (Legacy BIOS or UEFI). The boot modes can be
-configured in the Bare Metal service in the following way:
+Some of the bare metal hardware types (namely, ``redfish``, ``ilo`` and
+generic ``ipmi``) support setting  boot mode (Legacy BIOS or UEFI).
 
-* When no boot mode setting is provided, these drivers default the boot_mode
-  to Legacy BIOS.
+.. note::
+
+   Setting boot mode support in generic ``ipmi`` driver is coupled
+   with setting boot device. That makes boot mode support in the
+   ``ipmi`` driver incomplete.
+
+.. note::
+
+   In this chapter we will distinguish *ironic node* from *bare metal node*.
+   The difference is that *ironic node* refers to a logical node, as it is
+   configured in ironic, while *bare metal node* indicates the hardware
+   machine that ironic is managing.
+
+The following rules apply in order when ironic manages node boot mode:
+
+* If the hardware type (or bare metal node) does not implement reading
+  current boot mode of the bare metal node, then ironic assumes that
+  boot mode is not set on the bare metal node
+
+* If boot mode is not set on ironic node and bare metal node boot mode
+  is unknown (not set, can't be read etc.), ironic node boot mode
+  is set to the value of the `[deploy]/default_boot_mode` option
+
+* If boot mode is set on a bare metal node, but is not set on ironic
+  node, bare metal node boot mode is set on ironic node
+
+* If boot mode is set on ironic node, but is not set on the bare metal
+  node, ironic node boot mode is attempted to be set on the bare metal
+  node (failure to set boot mode on the bare metal node will not fail
+  ironic node deployment)
+
+* If different boot modes appear on to be set ironic node and on the
+  bare metal node, ironic node boot mode is attempted to be set on
+  the bare metal node (failure to set boot mode on the bare metal
+  node will fail ironic node deployment)
+
+.. warning::
+
+   If a bare metal node does not support setting boot mode, then
+   the operator needs to make sure that boot mode configuration is
+   consistent between ironic node and the bare metal node.
+
+The boot modes can be configured in the Bare Metal service in the
+following way:
 
 * Only one boot mode (either ``uefi`` or ``bios``) can be configured for
   the node.