1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
.. _vendor-passthru:
==============
Vendor Methods
==============
This document is a quick tutorial on writing vendor specific methods to
a driver.
The first thing to note is that the Ironic API supports two vendor
endpoints: A driver vendor passthru and a node vendor passthru.
* The driver vendor passthru allows drivers to expose a custom top-level
functionality which is not specific to a Node. For example, let's say
the driver `pxe_ipmitool` exposed a method called `authentication_types`
that would return what are the authentication types supported. It could
be accessed via the Ironic API like:
::
GET http://<address>:<port>/v1/drivers/pxe_ipmitool/vendor_passthru/authentication_types
* The node vendor passthru allows drivers to expose custom functionality
on per-node basis. For example the same driver `pxe_ipmitool` exposing a
method called `send_raw` that would send raw bytes to the BMC, the method
also receives a parameter called `raw_bytes` which the value would be
the bytes to be sent. It could be accessed via the Ironic API like:
::
POST {'raw_bytes': '0x01 0x02'} http://<address>:<port>/v1/nodes/<node UUID>/vendor_passthru/send_raw
Writing Vendor Methods
======================
Writing a custom vendor method in Ironic should be simple. The first thing
to do is write a class inheriting from the `VendorInterface`_ class:
.. code-block:: python
class ExampleVendor(VendorInterface)
def get_properties(self):
return {}
def validate(self, task, **kwargs):
pass
The `get_properties` is a method that all driver interfaces have, it
should return a dictionary of <property>:<description> telling in the
description whether that property is required or optional so the node
can be manageable by that driver. For example, a required property for a
`ipmi` driver would be `ipmi_address` which is the IP address or hostname
of the node. We are returning an empty dictionary in our example to make
it simpler.
The `validate` method is responsible for validating the parameters passed
to the vendor methods. Ironic will not introspect into what is passed
to the drivers, it's up to the developers writing the vendor method to
validate that data.
Let's extend the `ExampleVendor` class to support two methods, the
`authentication_types` which will be exposed on the driver vendor
passthru endpoint; And the `send_raw` method that will be exposed on
the node vendor passthru endpoint:
.. code-block:: python
class ExampleVendor(VendorInterface)
def get_properties(self):
return {}
def validate(self, task, method, **kwargs):
if method == 'send_raw':
if 'raw_bytes' not in kwargs:
raise MissingParameterValue()
@base.driver_passthru(['GET'], async=False)
def authentication_types(self, context, **kwargs):
return {"types": ["NONE", "MD5", "MD2"]}
@base.passthru(['POST'])
def send_raw(self, task, **kwargs):
raw_bytes = kwargs.get('raw_bytes')
...
That's it!
Writing a node or driver vendor passthru method is pretty much the
same, the only difference is how you decorate the methods and the first
parameter of the method (ignoring self). A method decorated with the
`@passthru` decorator should expect a Task object as first parameter and
a method decorated with the `@driver_passthru` decorator should expect
a Context object as first parameter.
Both decorators accept these parameters:
* http_methods: A list of what the HTTP methods supported by that vendor
function. To know what HTTP method that function was invoked with, a
`http_method` parameter will be present in the `kwargs`. Supported HTTP
methods are *POST*, *PUT*, *GET* and *PATCH*.
* method: By default the method name is the name of the python function,
if you want to use a different name this parameter is where this name
can be set. For example:
.. code-block:: python
@passthru(['PUT'], method="alternative_name")
def name(self, task, **kwargs):
...
* description: A string containing a nice description about what that
method is supposed to do. Defaults to "" (empty string).
.. _VendorInterface: ../api/ironic.drivers.base.html#ironic.drivers.base.VendorInterface
* async: A boolean value to determine whether this method should run
asynchronously or synchronously. Defaults to True (Asynchronously).
The node vendor passthru decorator (`@passthru`) also accepts the following
parameter:
* require_exclusive_lock: A boolean value determining whether this method
should require an exclusive lock on a node between validate() and the
beginning of method execution. For synchronous methods, the lock on the node
would also be kept for the duration of method execution. Defaults to True.
.. WARNING::
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.
Backwards Compatibility
=======================
There is no requirement that changes to a vendor method be backwards
compatible. However, for your users' sakes, we highly recommend that
you do so.
If you are changing the exceptions being raised, you might want to ensure
that the same HTTP code is being returned to the user.
For non-backwards compatibility, please make sure you add a release
note that indicates this.
|
