BIOS Settings: add admin doc

Change-Id: I8fd50be453c5306aa34d8afa5ebb79476af5f1cb
Story: #1712032

doc/source/admin/bios.rst

@@ -0,0 +1,159 @@
+.. _bios:
+
+==================
+BIOS Configuration
+==================
+
+Overview
+========
+
+The Bare Metal service supports BIOS configuration for bare metal nodes.
+It allows administrators to retrieve and apply the desired BIOS settings
+via CLI or REST API. The desired BIOS settings are applied during manual
+cleaning.
+
+Prerequisites
+=============
+
+Bare metal servers shall be configured by the administrator to be managed
+via ironic hardware type that supports BIOS configuration.
+
+Enabling hardware types
+-----------------------
+
+Enable a specific hardware type that supports BIOS configuration.
+Refer to :doc:`/install/enabling-drivers` for how to enable a hardware type.
+
+Enabling hardware interface
+---------------------------
+
+To enable the bios interface:
+
+.. code-block:: ini
+
+    [DEFAULT]
+    enabled_bios_interfaces = no-bios
+
+Append the actual bios interface name supported by the enabled hardware type
+to ``enabled_bios_interfaces`` with comma separated values in ``ironic.conf``.
+
+All available in-tree bios interfaces are listed in setup.cfg file in the
+source code tree, for example:
+
+.. code-block:: ini
+
+    ironic.hardware.interfaces.bios =
+        fake = ironic.drivers.modules.fake:FakeBIOS
+        no-bios = ironic.drivers.modules.noop:NoBIOS
+
+Retrieve BIOS settings
+======================
+
+To retrieve the cached BIOS configuration from a specified node::
+
+    $ openstack baremetal node bios setting list <node-uuid>
+
+BIOS settings are cached on each node cleaning operation or when settings
+have been applied successfully via BIOS cleaning steps. The return of above
+command is a table of last cached BIOS settings from specified node.
+If '-f json' is added as suffix to above command, it returns BIOS settings
+as following::
+
+    [
+      {
+        "<setting name>":
+          {
+            "name": <setting name>,
+            "value": <value>
+          }
+      },
+      {
+        "<setting name>":
+          {
+            "name": <setting name>,
+            "value": <value>
+          }
+      },
+      ...
+    ]
+
+To get a specified BIOS setting for a node::
+
+    $ openstack baremetal node bios setting show <node-uuid> <setting-name>
+
+If '-f json' is added as suffix to above command, it returns BIOS settings
+as following::
+
+    {
+      "<setting name>":
+        {
+          "name": <setting name>,
+          "value": <value>
+        }
+    }
+
+Configure BIOS settings
+=======================
+
+Two :ref:`manual_cleaning` steps are available for managing nodes'
+BIOS settings:
+
+Factory reset
+-------------
+
+This cleaning step resets all BIOS settings to factory default for a given
+node::
+
+    {
+      "target":"clean",
+      "clean_steps": [
+        {
+          "interface": "bios",
+          "step": "factory_reset"
+        }
+      ]
+    }
+
+The ``factory_reset`` cleaning step does not require any arguments, as it
+resets all BIOS settings to factory defaults.
+
+Apply BIOS configuration
+------------------------
+
+This cleaning step applies a set of BIOS settings for a node::
+
+    {
+      "target":"clean",
+      "clean_steps": [
+        {
+          "interface": "bios",
+          "step": "apply_configuration",
+          "args": {
+            "settings": [
+              {
+                "name": <name>,
+                "value": <value>
+              },
+              {
+                "name": <name>,
+                "value": <value>
+              }
+            ]
+          }
+        }
+      ]
+    }
+
+The representation of ``apply_configuration`` cleaning step follows the same
+format of :ref:`manual_cleaning`. The desired BIOS settings can be provided
+via the ``settings`` argument which contains a list of BIOS options to be
+applied, each BIOS option is a dictionary with ``name`` and ``value`` keys.
+
+To check whether the desired BIOS configuration is set properly, use the
+command mentioned in the `Retrieve BIOS settings`_ section.
+
+.. note::
+   When applying BIOS settings to a node, vendor-specific driver may take
+   the given BIOS settings from the argument and compare them with the
+   current BIOS settings on the node and only apply when there is a
+   difference.

doc/source/admin/index.rst

@@ -14,6 +14,7 @@ the services.
    Node Cleaning <cleaning>
    Node Adoption <adoption>
    RAID Configuration <raid>
+   BIOS Settings <bios>
    Configuring to boot from volume <boot-from-volume>
    Multi-tenant Networking <multitenancy>
    Port Groups <portgroups>

doc/source/contributor/bios_develop.rst

@@ -0,0 +1,117 @@
+.. _bios_develop:
+
+Developing BIOS Interface
+=========================
+
+To support a driver specific BIOS interface it is necessary to create a class
+inheriting from the ``BIOSInterface`` class:
+
+.. code-block:: python
+
+  from ironic.drivers import base
+
+  class ExampleBIOS(base.BIOSInterface):
+
+      def get_properties(self):
+          return {}
+
+      def validate(self, task):
+          pass
+
+See :doc:`/contributor/drivers` for a detailed explanation of hardware type
+and interface.
+
+The ``get_properties`` and ``validate`` are methods that all driver interfaces
+have. The hardware interface that supports BIOS settings should also implement
+the following three methods:
+
+* Implement a method named ``cache_bios_settings``. This method stores BIOS
+  settings to the ``bios_settings`` table during cleaning operations and
+  updates the ``bios_settings`` table when ``apply_configuration`` or
+  ``factory_reset`` are successfully called.
+
+  .. code-block:: python
+
+    from ironic.drivers import base
+
+    driver_client = importutils.try_import('driver.client')
+
+    class ExampleBIOS(base.BIOSInterface):
+        def __init__(self):
+            if driver_client is None:
+                raise exception.DriverLoadError(
+                    driver=self.__class__.__name__,
+                    reason=_("Unable to import driver library"))
+
+        def cache_bios_settings(self, task):
+            node_id = task.node.id
+            node_info = driver_common.parse_driver_info(task.node)
+            settings = driver_client.get_bios_settings(node_info)
+            create_list, update_list, delete_list = (
+                objects.BIOSSettingList.sync_node_setting(settings))
+
+            if len(create_list) > 0:
+                objects.BIOSSettingList.create(
+                    task.context, node_id, create_list)
+            if len(update_list) > 0:
+                objects.BIOSSettingList.save(
+                    task.context, node_id, update_list)
+            if len(delete_list) > 0:
+                for setting in delete_list:
+                    objects.BIOSSetting.delete(
+                        task.context, node_id, setting.name)
+
+  .. note::
+     ``driver.client`` is vendor specific library to control and manage
+     the bare metal hardware, for example: python-dracclient, sushy.
+
+* Implement a method named ``factory_reset``. This method needs to use the
+  ``clean_step`` decorator. It resets BIOS settings to factory default on the
+  given node. It calls ``cache_bios_settings`` automatically to update
+  existing ``bios_settings`` table once successfully executed.
+
+  .. code-block:: python
+
+    class ExampleBIOS(base.BIOSInterface):
+
+        @base.clean_step(priority=0)
+        def factory_reset(self, task):
+            node_info = driver_common.parse_driver_info(task.node)
+            driver_client.reset_bios_settings(node_info)
+
+* Implement a method named ``apply_configuration``. This method needs to use
+  the clean_step decorator. It takes the given BIOS settings and applies them
+  on the node. It also calls ``cache_bios_settings`` automatically to update
+  existing bios_settings table after successfully applying given settings on
+  the node.
+
+  .. code-block:: python
+
+    class ExampleBIOS(base.BIOSInterface):
+
+        @base.clean_step(priority=0, argsinfo={
+            'settings': {
+                'description': (
+                    'A list of BIOS settings to be applied'
+                ),
+                'required': True
+            }
+        })
+        def apply_configuration(self, task, settings):
+            node_info = driver_common.parse_driver_info(task.node)
+            driver_client.apply_bios_settings(node_info, settings)
+
+  The ``settings`` parameter is a list of BIOS settings to be configured.
+  for example::
+
+      [
+        {
+          'name': String,
+          'value': String,
+        },
+        {
+          'name': String,
+          'value': String,
+        },
+        ...
+      ]

doc/source/contributor/index.rst

@@ -62,6 +62,7 @@ the developer community about any implementation using this functionality.
 
   Driver Overview <drivers>
   Writing "vendor_passthru" methods <vendor-passthru>
+  Creating new BIOS interfaces <bios_develop>
   Third party continuous integration testing <third-party-ci>
 
 Testing Network Integration

doc/source/install/enabling-drivers.rst

@@ -53,6 +53,18 @@ Enabling hardware interfaces
 
 There are several types of hardware interfaces:
 
+bios
+    manages configuration of the BIOS settings of a bare metal node.
+    This interface is vendor-specific and can be enabled via the
+    ``enabled_bios_interfaces`` option:
+
+    .. code-block:: ini
+
+        [DEFAULT]
+        enabled_hardware_types = <hardware_type_name>
+        enabled_bios_interfaces = <bios_interface_name>
+
+    See :doc:`/admin/bios` for details. This interface is vendor-specific.
 boot
     manages booting of both the deploy ramdisk and the user instances on the
     bare metal node. See :doc:`/admin/interfaces/boot` for details.