Merge "Update the Vendor Passthru documentation"
This commit is contained in:
commit
b098c4a364
doc/source/dev
@ -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.
|
||||
|
@ -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.
|
||||
|
Loading…
x
Reference in New Issue
Block a user