This spec proposes support for retrieving the BIOS Registry from Sushy and exposing it through the ``nodes/<node>/bios`` API. Story: 2008571 Task: 41722 Change-Id: Ib93e62076207e3e25960111bd0b46b83fe481c69
12 KiB
Provide Redfish BIOS Attribute Registry data in API
https://storyboard.openstack.org/#!/story/2008571
This proposal is to retrieve the Redfish BIOS Attribute Registry when using the Redfish driver and provide it as additional data in the bios API endpoint.
Problem description
The Redfish BIOS Attribute Registry (aka BIOS Registry) is defined in the DMTF Redfish specification1 as a way to describe the semantics of each property in a BIOS settings resource. This JSON encoded registry contains descriptions of each property and other information, such as data type, allowable values, and whether the attribute is read-only.
When a user attempts to set a BIOS attribute through clean steps2 it is not obvious which name should be used for the attribute, what its allowable values are, or even if the attribute is writeable. It is useful to expose the BIOS Registry through an API so that it can be used as a form of documentation when setting BIOS attributes.
An example of an entry in BIOS Registry returned from a BMC for an attribute:
{
"AttributeName": "SriovGlobalEnable",
"CurrentValue": null,
"DisplayName": "SR-IOV Global Enable",
"DisplayOrder": 2331,
"HelpText": "Enables or disables the BIOS configuration of Single Root
I/O Virtualization (SR-IOV) devices. Enable this feature
if booting to a virtualization operating system that
recognize SR-IOV devices. ",
"Hidden": false,
"Immutable": false,
"MenuPath": "./IntegratedDevicesRef",
"ReadOnly": false,
"ResetRequired": true,
"Type": "Enumeration",
"Value": [
{
"ValueDisplayName": "Enabled",
"ValueName": "Enabled"
},
{
"ValueDisplayName": "Disabled",
"ValueName": "Disabled"
}
],
"WarningText": null,
"WriteOnly": false
}
This change was discussed at the Wallaby mid-cycle, see notes3.
Proposed change
The effort will encompass the following changes:
- Support for getting the BIOS Registry in Sushy. Retrieving the BIOS
Registry requires multiple Redfish requests as the base URI
-
/redfish/v1/Registries
, provides the BIOS Registry URI with a vendor specific name. The registry will be a list of dictionary entries, one for each BIOS attribute. - Changes to Ironic to retrieve the Redfish BIOS Registry for a node
when it gets the BIOS settings; currently this is when Ironic moves the
node to
manageable
orcleaning
and after changing the BIOS settings. - Filtering of the BIOS registry received from Sushy to only save the
entries that match the BIOS settings received from Sushy, based on the
AttributeName
field in the BIOS Registry entries. - Storing the registry data in the Ironic DB associated with each BIOS setting.
- Exposing the BIOS Registry data via the REST API. No new endpoints
will be added. The registry data will be included in the
/v1/nodes/<node>/bios
endpoint only if?detail=True
is set. The registry data will always be included in/v1/nodes/<node>/bios/<setting>
. This is similar to how the API for nodes currently works e.g./v1/nodes
,/v1/nodes?detail=True
, and/v1/nodes/<node>
Alternatives
- An operator can continue to set the BIOS settings in clean steps perhaps by using vendor documentation or only making simple changes to Boolean values.
- Instead of retrieving the registry and caching it, Ironic could do a synchronous get from the API. However, this may lead to performance problems especially when handling multiple API requests.
Data model impact
There is a schema defined for the BIOS Registry, for example4, however it is vendor dependent as to which attribute fields are stored in the registry. Sushy should parse the following common fields which are present in the registry of typical vendors, for example Dell, HPE, and SuperMicro:
* AttributeName * DefaultValue * Type * Immutable * ReadOnly * ResetRequired * IsSystemUniqueProperty * LowerBound * UpperBound * MinLength * MaxLength * Value (possible values for enumeration types) * ValueName
The BIOS Registry will be stored in the Ironic DB along with the BIOSSetting, see5. The following columns will be added and must be included in the migration code:
attribute_type
(string)allowable_values
(list)lower_bound
(integer)max_length
(integer)min_length
(integer)read_only
(boolean)reset_required
(boolean)unique
(boolean)upper_bound
(integer)
For each setting only the relevant fields for
attribute_type
will be stored as returned from the BMC. For
example, for an Enumeration type only allowable_values
will
be stored and for an Integer only min_length
and
max_length
.
In addition, the BIOSSetting name
field should be
indexed for faster retrieval.
State Machine Impact
The BIOS Registry will be retrieved from the BMC upon transition to
manageable
and cleaning
states using multiple
Redfish requests. This may add some additional time to the state
transition but it is not foreseen that this will have an impact on the
state transition performance.
REST API impact
No new REST API endpoints will be added. The
/v1/nodes/<node>/bios/<attribute>
endpoint will be changed to include the new registry fields. The/v1/nodes/<node>/bios
endpoint will only include this data per attribute if?detail=True
is set, similar to how the/v1/nodes/
endpoint works. The query can also be used to retrieve only particular fields.If BIOS Registry could not be retrieved from the node then the registry fields will be set to
null
.For allowable_values, some vendors include both ValueName and ValueDisplayName in the response. The API will just show a list of the allowable values.
An example response for
/v1/nodes/<node>/bios/ProcVirtualization
, an enumeration type, with the new registry fields is as follows:{ "ProcVirtualization": { "created_at": "2021-03-31T13:50:51+00:00", "updated_at": null, "name": "ProcVirtualization", "value": "Enabled", "allowable_values": ["Enabled","Disabled"] "lower_bound": null, "max_length": null, "min_length": null, "read_only": false, "reset_required": null, "type": "Enumeration", "unique": null, "upper_bound": null, "links": [ { "href": "http://IP/v1/nodes/1b1c6edf-4459-4172-b069-5c6ca3e59e03/bios/ProcVirtualization", "rel": "self" }, { "href": "http://IP/nodes/1b1c6edf-4459-4172-b069-5c6ca3e59e03/bios/ProcVirtualization", "rel": "bookmark" } ] } }
An example response for
/v1/nodes/<node>/bios/SerialNumber
, a String type unique to this node, is as follows:{ "SerialNumber": { "created_at": "2021-03-31T13:50:51+00:00", "updated_at": null, "name": "SerialNumber", "value": "Q95102Q8", "allowable_values": [], "lower_bound": null, "max_length": 16, "min_length": null, "read_only": false, "reset_required": null, "type": "String", "unique": true, "upper_bound": null, "links": [ { "href": "http://IP/v1/nodes/1b1c6edf-4459-4172-b069-5c6ca3e59e03/bios/SerialNumber", "rel": "self" }, { "href": "http://IP/nodes/1b1c6edf-4459-4172-b069-5c6ca3e59e03/bios/SerialNumber", "rel": "bookmark" } ] } }
Client (CLI) impact
"baremetal" CLI
- The bios command
baremetal node bios
will change as follows.This command will now include the registry data as an additional fields, for example:
$ baremetal node bios setting show hp-910 ProcVirtualization -f json { "created_at": "2021-03-31T13:50:51+00:00", "name": "ProcVirtualization", "updated_at": null, "value": "Enabled" "allowable_values": ["Enabled","Disabled"] "lower_bound": null, "max_length": null, "min_length": null, "read_only": false, "reset_required": null, "type": "Enumeration", "unique": null, "upper_bound": null, }
- A new parameter
--long
will be added to thebaremetal node bios list
command to include the registry data for each attribute. It will not be included by default. This is similar tobaremetal node list <node> --long
command.
"openstacksdk"
Openstacksdk does not currently have support for bios settings. Although not a requirement for this specification. bios should be added to openstacksdk and the detailed registry information should be included.
RPC API impact
A new method to get the BIOS registry will be added to the RPC API.
Driver API impact
- The
cache_bios_settings
method in the Redfish driver will now also get the BIOS Registry from Sushy.
Nova driver impact
None
Ramdisk impact
None
Security impact
Unprivileged access to the BIOS configuration can expose sensitive BIOS information and configurable BIOS options to attackers, which may lead to disruptive consequence. It's recommended that this kind of ability is restricted to administrative roles.
Other end user impact
None
Scalability impact
The Redfish requests to retrieve BIOS Registry data will increase the
traffic to the BMC however, since these requests will only be when the
node transitions to manageable
or cleaning
, it
should not impact scalability.
The BIOS Registry data will be stored in the Ironic DB along with the BIOS setting that it corresponds to. This will add to the size of the Ironic DB but its not expected to be prohibitive as the BIOS settings list, although it varies per vendor, is approximately 100 to 200 items.
Performance Impact
It is not expected that this change will introduce a performance
impact on the time it takes for nodes to transition to
manageable
or cleaning
.
Other deployer impact
None
Developer impact
None
Implementation
Assignee(s)
- Primary assignee:
Work Items
- Add support for BIOS Registry to Sushy
- Add caching support for the registry to Ironic.
- Add retrieval of the registry in Ironic when transitioning the node
to
cleaning
ormanageable
and store/update the cache. - Add the API to get the BIOS Registry for the node.
- Add configuration items for
bios_registory_lang
andbios_registry_enable
to ironic.conf.
Dependencies
None
Testing
- Unit testing will be added with sample vendor data but it will necessary for 3rd party testing to be added to test each vendor's interface.
Upgrades and Backwards Compatibility
None
Documentation Impact
- API reference will be updated.
References
DMTF Redfish Specification - http://redfish.dmtf.org/schemas/DSP0266_1.11.0.html↩︎
BIOS configuration - https://github.com/openstack/ironic-specs/blob/master/specs/approved/generic-bios-config.rst↩︎
Discussion at Wallaby mid-cycle - https://etherpad.opendev.org/p/ironic-wallaby-midcycle↩︎
AttributeRegistry schema - https://redfish.dmtf.org/schemas/v1/AttributeRegistry.v1_3_4.json↩︎
BIOSSetting in Ironic DB - https://opendev.org/openstack/ironic/src/branch/master/ironic/db/sqlalchemy/models.py#L326↩︎