diff --git a/doc/source/dev/drivers.rst b/doc/source/dev/drivers.rst index e212a373b2..eb9e640c29 100644 --- a/doc/source/dev/drivers.rst +++ b/doc/source/dev/drivers.rst @@ -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//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//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//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//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. diff --git a/doc/source/dev/vendor-passthru.rst b/doc/source/dev/vendor-passthru.rst index b3e7ed57e2..1008fbb6a5 100644 --- a/doc/source/dev/vendor-passthru.rst +++ b/doc/source/dev/vendor-passthru.rst @@ -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.