bca44bcefc
Sphinx provides the versionadded syntax for indicating version related changes in documentation, the OpenStack doc theme is designed to handle this and render it nicely. This patch switches our inconsistent references to API version related change in the API ref to use this syntax so that it standardised through out the docs, and is more obvious in the documentation itself. Change-Id: Ied6f22deecebd71042d2230b81e057543db3d3f4
233 lines
7.6 KiB
ReStructuredText
233 lines
7.6 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
=================
|
|
Drivers (drivers)
|
|
=================
|
|
|
|
.. versionchanged:: 1.30
|
|
The REST API now also exposes information about *dynamic* drivers.
|
|
|
|
Ironic has two types of drivers: *classic* drivers and *dynamic* drivers.
|
|
|
|
A *classic* driver is a Python object containing all the logic to manage the
|
|
bare metal nodes enrolled within Ironic. A driver may be loaded within one or
|
|
more ``ironic-conductor`` services. Each driver contains a pre-determined set
|
|
of instantiated interfaces. Each type of interface (eg, ``power`` or ``boot``)
|
|
performs a specific hardware function.
|
|
|
|
*Dynamic* drivers are supported via hardware types, which are Python classes
|
|
enabled via entry points. Unlike *classic* drivers, which have pre-determined
|
|
interfaces, a hardware type may support multiple types of interfaces. For
|
|
example, the ``ipmi`` hardware type may support multiple methods for enabling
|
|
node console. Which interface a node of a particular hardware type uses is
|
|
determined at runtime. This collection of interfaces is called a *dynamic*
|
|
driver. For more information about this, see the node API documentation.
|
|
|
|
The REST API exposes the list of drivers and which ``ironic-conductor``
|
|
processes have loaded that driver via the Driver resource (``/v1/drivers``
|
|
endpoint). This can be useful for operators to validate their configuration in
|
|
a heterogeneous hardware environment. Each ``ironic-conductor`` process may
|
|
load one or more drivers, and does not necessarily need to load the same
|
|
*classic* drivers as another ``ironic-conductor``. Each ``ironic-conductor``
|
|
with the same hardware types must have the same hardware interfaces enabled.
|
|
|
|
The REST API also exposes details about each driver, such as what properties
|
|
must be supplied to a node's ``driver_info`` for that driver to manage
|
|
hardware.
|
|
|
|
Lastly, some drivers may expose methods through a ``driver_vendor_passthru``
|
|
endpoint, allowing one to interact with the driver directly (i.e., without
|
|
knowing a specific node identifier). For example, this is used by the ironic
|
|
python agent ramdisk to get the UUID of the node being deployed/cleaned by
|
|
using MAC addresses of the node's network interfaces the agent has discovered.
|
|
|
|
|
|
List drivers
|
|
============
|
|
|
|
.. rest_method:: GET /v1/drivers
|
|
|
|
Lists all drivers.
|
|
|
|
Normal response codes: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- type: driver_type
|
|
- detail: driver_detail
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
The response BODY contains a single key, "drivers", whose value is a list of
|
|
drivers supported by this Ironic service.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- drivers: drivers
|
|
- name: driver_name
|
|
- hosts: hosts
|
|
- type: response_driver_type
|
|
- links: links
|
|
- properties: driver_property_links
|
|
|
|
.. versionchanged:: 1.30
|
|
If the request has the "detail" URL parameter set to true, each
|
|
driver will also include the following fields.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- default_boot_interface: default_boot_interface
|
|
- default_console_interface: default_console_interface
|
|
- default_deploy_interface: default_deploy_interface
|
|
- default_inspect_interface: default_inspect_interface
|
|
- default_management_interface: default_management_interface
|
|
- default_network_interface: default_network_interface
|
|
- default_power_interface: default_power_interface
|
|
- default_raid_interface: default_raid_interface
|
|
- default_storage_interface: default_storage_interface
|
|
- default_vendor_interface: default_vendor_interface
|
|
- enabled_boot_interfaces: enabled_boot_interfaces
|
|
- enabled_console_interfaces: enabled_console_interfaces
|
|
- enabled_deploy_interfaces: enabled_deploy_interfaces
|
|
- enabled_inspect_interfaces: enabled_inspect_interfaces
|
|
- enabled_management_interfaces: enabled_management_interfaces
|
|
- enabled_network_interfaces: enabled_network_interfaces
|
|
- enabled_power_interfaces: enabled_power_interfaces
|
|
- enabled_raid_interfaces: enabled_raid_interfaces
|
|
- enabled_storage_interfaces: enabled_storage_interfaces
|
|
- enabled_vendor_interfaces: enabled_vendor_interfaces
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
Example for a request with detail=false (the default):
|
|
|
|
.. literalinclude:: samples/drivers-list-response.json
|
|
:language: javascript
|
|
|
|
Example for a request with detail=true:
|
|
|
|
.. literalinclude:: samples/drivers-list-detail-response.json
|
|
:language: javascript
|
|
|
|
Show driver details
|
|
===================
|
|
|
|
.. rest_method:: GET /v1/drivers/{driver_name}
|
|
|
|
Shows details for a driver.
|
|
|
|
Normal response codes: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- driver_name: driver_ident
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- name: driver_name
|
|
- hosts: hosts
|
|
- type: response_driver_type
|
|
- default_boot_interface: default_boot_interface
|
|
- default_console_interface: default_console_interface
|
|
- default_deploy_interface: default_deploy_interface
|
|
- default_inspect_interface: default_inspect_interface
|
|
- default_management_interface: default_management_interface
|
|
- default_network_interface: default_network_interface
|
|
- default_power_interface: default_power_interface
|
|
- default_raid_interface: default_raid_interface
|
|
- default_storage_interface: default_storage_interface
|
|
- default_vendor_interface: default_vendor_interface
|
|
- enabled_boot_interfaces: enabled_boot_interfaces
|
|
- enabled_console_interfaces: enabled_console_interfaces
|
|
- enabled_deploy_interfaces: enabled_deploy_interfaces
|
|
- enabled_inspect_interfaces: enabled_inspect_interfaces
|
|
- enabled_management_interfaces: enabled_management_interfaces
|
|
- enabled_network_interfaces: enabled_network_interfaces
|
|
- enabled_power_interfaces: enabled_power_interfaces
|
|
- enabled_raid_interfaces: enabled_raid_interfaces
|
|
- enabled_storage_interfaces: enabled_storage_interfaces
|
|
- enabled_vendor_interfaces: enabled_vendor_interfaces
|
|
- links: links
|
|
- properties: driver_property_links
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/driver-get-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show driver properties
|
|
======================
|
|
|
|
.. rest_method:: GET /v1/drivers/{driver_name}/properties
|
|
|
|
Shows the required and optional parameters that ``driver_name`` expects to be
|
|
supplied in the ``driver_info`` field for every Node it manages.
|
|
|
|
To check if all required parameters have been supplied to a Node, you should
|
|
query the ``/v1/nodes/{node_ident}/validate`` endpoint.
|
|
|
|
Normal response codes: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- driver_name: driver_ident
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
The response BODY is a dictionary, but the keys are unique to each driver.
|
|
The structure of the response is ``property`` : ``description``.
|
|
|
|
The following example is returned from the ``agent_ipmitool`` driver.
|
|
|
|
.. literalinclude:: samples/driver-property-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show driver logical disk properties
|
|
===================================
|
|
|
|
.. versionadded:: 1.12
|
|
|
|
.. rest_method:: GET /v1/drivers/{driver_name}/raid/logical_disk_properties
|
|
|
|
Show the required and optional parameters that ``driver_name`` expects to be
|
|
supplied in the node's ``raid_config`` field, if a RAID configuration change is
|
|
requested.
|
|
|
|
Normal response codes: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- driver_name: driver_ident
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
The response BODY is a dictionary, but the keys are unique to each driver.
|
|
The structure of the response is ``property`` : ``description``.
|
|
|
|
The following example is returned from the ``agent_ipmitool`` driver.
|
|
|
|
.. literalinclude:: samples/driver-logical-disk-properties-response.json
|
|
:language: javascript
|