openstack/ironic
Code Issues Proposed changes

Update the Vendor Passthru documentation

Browse Source 
This patch updates the documentation about the Nodes and Drivers Vendor
Passthru. It talks about the discoverability of the vendor methods via
the Ironic API, the support for multiple HTTP methods and what to expect
of a asynchrounous or synchrounous method.

Change-Id: I6a3c971dfe53cc7148ea2a51c6449bf729d39fa5
This commit is contained in:
Lucas Alvares Gomes 2015-04-28 18:00:39 +01:00
parent 8dad33164b
commit 79a8962a74
2 changed files with 72 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
doc/source/dev/drivers.rst
View File

@ -35,35 +35,78 @@ upstream commit) please consult the wiki page::
Node Vendor Passthru
--------------------
Drivers may implement a passthrough API, which becomes accessible via
HTTP POST at the `/v1/{NODE}/vendor_passthru?method={METHOD}` endpoint. Beyond
basic checking, Ironic does not introspect the message body and simply "passes
it through" to the relevant driver.
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.
It should be noted that, while this API end point is asynchronous, it is
serialized. Requests will return an HTTP status code 202 to indicate the
request was received and is being acted upon, but the request can not return a
BODY. While performing the request, a lock is held on the node, and other
requests will be delayed, and may fail with an HTTP 409 CONFLICT error.
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.
While performing the request, a lock is held on the node, and 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.
This endpoint is exposing 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.
Driver Vendor Passthru
----------------------
Drivers may also implement a similar API for requests not related to any node
at `/v1/drivers/{DRIVER}/vendor_passthru?method={METHOD}`. However, this API
endpoint is *synchronous*. Calls are passed to the driver, and return a BODY
with the response from the driver once the request is completed.
Drivers may implement an API for requests not related to any node,
at ``/v1/drivers/<driver name>/vendor_passthru?method={METHOD}``.
NOTE: Each open request to this endpoint consumes a worker thread within the
ironic-conductor process. This can lead to starvation of the threadpool, and a
denial of service. Driver authors are encouraged to avoid using this endpoint,
and, when necessary, make all requests to it return as quickly as possible.
A method:
Similarly, Ironic makes no guarantees about the semantics of the message BODY
sent to this endpoint. That is left up to each driver's author.
* 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.

5
doc/source/dev/vendor-passthru.rst
View File

@ -124,3 +124,8 @@ Both decorators accepts the same parameters:
Please avoid having a synchronous method for slow/long-running
operations **or** if the method does talk to a BMC; BMCs are flaky
and very easy to break.
.. WARNING::
Each asynchronous request consumes a worker thread in the
``ironic-conductor`` process. This can lead to starvation of the
thread pool, resulting in a denial of service.