BIOS Settings: add admin doc
Change-Id: I8fd50be453c5306aa34d8afa5ebb79476af5f1cb Story: #1712032
This commit is contained in:
Zenghui Shi
parent
47c596298a
commit
a8c425a2cd
159
doc/source/admin/bios.rst
Normal file
159
doc/source/admin/bios.rst
Normal file
@ -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.
|
||||||
@ -14,6 +14,7 @@ the services.
|
|||||||
Node Cleaning <cleaning>
|
Node Cleaning <cleaning>
|
||||||
Node Adoption <adoption>
|
Node Adoption <adoption>
|
||||||
RAID Configuration <raid>
|
RAID Configuration <raid>
|
||||||
|
BIOS Settings <bios>
|
||||||
Configuring to boot from volume <boot-from-volume>
|
Configuring to boot from volume <boot-from-volume>
|
||||||
Multi-tenant Networking <multitenancy>
|
Multi-tenant Networking <multitenancy>
|
||||||
Port Groups <portgroups>
|
Port Groups <portgroups>
|
||||||
|
|||||||
117
doc/source/contributor/bios_develop.rst
Normal file
117
doc/source/contributor/bios_develop.rst
Normal file
@ -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,
|
||||||
|
},
|
||||||
|
...
|
||||||
|
]
|
||||||
@ -62,6 +62,7 @@ the developer community about any implementation using this functionality.
|
|||||||
|
|
||||||
Driver Overview <drivers>
|
Driver Overview <drivers>
|
||||||
Writing "vendor_passthru" methods <vendor-passthru>
|
Writing "vendor_passthru" methods <vendor-passthru>
|
||||||
|
Creating new BIOS interfaces <bios_develop>
|
||||||
Third party continuous integration testing <third-party-ci>
|
Third party continuous integration testing <third-party-ci>
|
||||||
|
|
||||||
Testing Network Integration
|
Testing Network Integration
|
||||||
|
|||||||
@ -53,6 +53,18 @@ Enabling hardware interfaces
|
|||||||
|
|
||||||
There are several types of 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
|
boot
|
||||||
manages booting of both the deploy ramdisk and the user instances on the
|
manages booting of both the deploy ramdisk and the user instances on the
|
||||||
bare metal node. See :doc:`/admin/interfaces/boot` for details.
|
bare metal node. See :doc:`/admin/interfaces/boot` for details.
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user