diff --git a/doc/source/admin/bios.rst b/doc/source/admin/bios.rst new file mode 100644 index 0000000000..9e6f433a0c --- /dev/null +++ b/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 + +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:: + + [ + { + "": + { + "name": , + "value": + } + }, + { + "": + { + "name": , + "value": + } + }, + ... + ] + +To get a specified BIOS setting for a node:: + + $ openstack baremetal node bios setting show + +If '-f json' is added as suffix to above command, it returns BIOS settings +as following:: + + { + "": + { + "name": , + "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": , + "value": + }, + { + "name": , + "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. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 79bfb99efa..42ccfd7ba9 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -14,6 +14,7 @@ the services. Node Cleaning Node Adoption RAID Configuration + BIOS Settings Configuring to boot from volume Multi-tenant Networking Port Groups diff --git a/doc/source/contributor/bios_develop.rst b/doc/source/contributor/bios_develop.rst new file mode 100644 index 0000000000..383aeb105d --- /dev/null +++ b/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, + }, + ... + ] diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index a100df798f..2e7affa945 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -62,6 +62,7 @@ the developer community about any implementation using this functionality. Driver Overview Writing "vendor_passthru" methods + Creating new BIOS interfaces Third party continuous integration testing Testing Network Integration diff --git a/doc/source/install/enabling-drivers.rst b/doc/source/install/enabling-drivers.rst index 73f2902151..21245d7508 100644 --- a/doc/source/install/enabling-drivers.rst +++ b/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 = + enabled_bios_interfaces = + + 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.