ironic/doc/source/dev/drivers.rst
Andreas Jaeger 4cff2ab6d5 Use Sphinx 1.5 warning-is-error
With pbr 2.0 and Sphinx 1.5, the setting for treat sphinx warnings as
errors is setting warning-is-error in build_sphinx section. Migrate
the setting from the old warnerrors one.

Fix problems found:
* Duplicate labels (rename wrong faq entries, rename unused drivers
  entries)
* Add api/autoindex.rst as hidden to the index so that we do not get a
  warning. The modindex includes the same content, so no need to show
  this.
* Add releasenotes/index.rst, webapi/v1.rst, user-guide, and install-guide.rst
  to hidden index since they're not listed in index on purpose, so sphinx
  will not warn that they do not appear in a toc
* Add deploy/radosgw to index
* ignore app.add_directiv warning
* Fix reference to user-guide to use proper markup so that Sphinx knows
  the user-guide is referenced.

Change-Id: I00d249229d4d31ba36d4393d60847fdb1513a744
2017-03-08 08:22:24 +01:00

114 lines
4.2 KiB
ReStructuredText

.. _pluggable_drivers:
=================
Pluggable Drivers
=================
Ironic supports a pluggable driver model. This allows contributors to easily
add new drivers, and operators to use third-party drivers or write their own.
Drivers are loaded by the ironic-conductor service during initialization, by
enumerating the python entrypoint "ironic.drivers" and attempting to load
all drivers specified in the "enabled_drivers" configuration option. A
complete list of drivers available on the system may be found by
enumerating this entrypoint by running the following python script::
#!/usr/bin/env python
import pkg_resources as pkg
print [p.name for p in pkg.iter_entry_points("ironic.drivers") if not p.name.startswith("fake")]
A list of drivers enabled in a running Ironic service may be found by issuing
the following command against that API end point::
ironic driver-list
Supported Drivers
-----------------
For a list of supported drivers (those that are continuously tested on every
upstream commit) please consult the wiki page::
https://wiki.openstack.org/wiki/Ironic/Drivers
Node Vendor Passthru
--------------------
Drivers may implement a passthrough API, which is accessible via
the ``/v1/nodes/<Node UUID or Name>/vendor_passthru?method={METHOD}``
endpoint. Beyond basic checking, Ironic does not introspect the message
body and simply "passes it through" to the relevant driver.
A method:
* can support one or more HTTP methods (for example, GET, POST)
* is asynchronous or synchronous
+ For asynchronous methods, a 202 (Accepted) HTTP status code is returned
to indicate that the request was received, accepted and is being acted
upon. No body is returned in the response.
+ For synchronous methods, a 200 (OK) HTTP status code is returned to
indicate that the request was fulfilled. The response may include a body.
* can require an exclusive lock on the node. This only occurs if the method
doesn't specify require_exclusive_lock=False in the decorator. If an
exclusive lock is held on the node, other requests for the node will be
delayed and may fail with an HTTP 409 (Conflict) error code.
This endpoint exposes a node's driver directly, and as such, it is
expressly not part of Ironic's standard REST API. There is only a
single HTTP endpoint exposed, and the semantics of the message body
are determined solely by the driver. Ironic makes no guarantees about
backwards compatibility; this is solely up to the discretion of each
driver's author.
To get information about all the methods available via the vendor_passthru
endpoint for a particular node, you can issue an HTTP GET request::
GET /v1/nodes/<Node UUID or name>/vendor_passthru/methods
The response's JSON body will contain information for each method,
such as the method's name, a description, the HTTP methods supported,
and whether it's asynchronous or synchronous.
Driver Vendor Passthru
----------------------
Drivers may implement an API for requests not related to any node,
at ``/v1/drivers/<driver name>/vendor_passthru?method={METHOD}``.
A method:
* can support one or more HTTP methods (for example, GET, POST)
* is asynchronous or synchronous
+ For asynchronous methods, a 202 (Accepted) HTTP status code is
returned to indicate that the request was received, accepted and is
being acted upon. No body is returned in the response.
+ For synchronous methods, a 200 (OK) HTTP status code is returned
to indicate that the request was fulfilled. The response may include
a body.
.. note::
Unlike methods in `Node Vendor Passthru`_, a request does not lock any
resource, so it will not delay other requests and will not fail with an
HTTP 409 (Conflict) error code.
Ironic makes no guarantees about the semantics of the message BODY sent
to this endpoint. That is left up to each driver's author.
To get information about all the methods available via the driver
vendor_passthru endpoint, you can issue an HTTP GET request::
GET /v1/drivers/<driver name>/vendor_passthru/methods
The response's JSON body will contain information for each method,
such as the method's name, a description, the HTTP methods supported,
and whether it's asynchronous or synchronous.