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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
.. -*- rst -*-
=================
Drivers (drivers)
=================
.. versionchanged:: 1.30
The REST API now also exposes information about *dynamic* drivers.
Ironic has two types of drivers: *classic* drivers and *dynamic* drivers.
A *classic* driver is a Python object containing all the logic to manage the
bare metal nodes enrolled within Ironic. A driver may be loaded within one or
more ``ironic-conductor`` services. Each driver contains a pre-determined set
of instantiated interfaces. Each type of interface (eg, ``power`` or ``boot``)
performs a specific hardware function.
*Dynamic* drivers are supported via hardware types, which are Python classes
enabled via entry points. Unlike *classic* drivers, which have pre-determined
interfaces, a hardware type may support multiple types of interfaces. For
example, the ``ipmi`` hardware type may support multiple methods for enabling
node console. Which interface a node of a particular hardware type uses is
determined at runtime. This collection of interfaces is called a *dynamic*
driver. For more information about this, see the node API documentation.
The REST API exposes the list of drivers and which ``ironic-conductor``
processes have loaded that driver via the Driver resource (``/v1/drivers``
endpoint). This can be useful for operators to validate their configuration in
a heterogeneous hardware environment. Each ``ironic-conductor`` process may
load one or more drivers, and does not necessarily need to load the same
*classic* drivers as another ``ironic-conductor``. Each ``ironic-conductor``
with the same hardware types must have the same hardware interfaces enabled.
The REST API also exposes details about each driver, such as what properties
must be supplied to a node's ``driver_info`` for that driver to manage
hardware.
Lastly, some drivers may expose methods through a ``driver_vendor_passthru``
endpoint, allowing one to interact with the driver directly (i.e., without
knowing a specific node identifier). For example, this is used by the ironic
python agent ramdisk to get the UUID of the node being deployed/cleaned by
using MAC addresses of the node's network interfaces the agent has discovered.
List drivers
============
.. rest_method:: GET /v1/drivers
Lists all drivers.
.. versionadded:: 1.77
Added ``fields`` selector to query for particular fields.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- type: driver_type
- detail: driver_detail
- fields: fields
Response Parameters
-------------------
The response BODY contains a single key, "drivers", whose value is a list of
drivers supported by this Ironic service.
.. rest_parameters:: parameters.yaml
- drivers: drivers
- name: driver_name
- hosts: hosts
- type: response_driver_type
- links: links
- properties: driver_property_links
.. versionchanged:: 1.30
If the request has the "detail" URL parameter set to true, each
driver will also include the following fields.
.. rest_parameters:: parameters.yaml
- default_bios_interface: default_bios_interface
- default_boot_interface: default_boot_interface
- default_console_interface: default_console_interface
- default_deploy_interface: default_deploy_interface
- default_inspect_interface: default_inspect_interface
- default_management_interface: default_management_interface
- default_network_interface: default_network_interface
- default_power_interface: default_power_interface
- default_raid_interface: default_raid_interface
- default_rescue_interface: default_rescue_interface
- default_storage_interface: default_storage_interface
- default_vendor_interface: default_vendor_interface
- enabled_bios_interfaces: enabled_bios_interfaces
- enabled_boot_interfaces: enabled_boot_interfaces
- enabled_console_interfaces: enabled_console_interfaces
- enabled_deploy_interfaces: enabled_deploy_interfaces
- enabled_inspect_interfaces: enabled_inspect_interfaces
- enabled_management_interfaces: enabled_management_interfaces
- enabled_network_interfaces: enabled_network_interfaces
- enabled_power_interfaces: enabled_power_interfaces
- enabled_rescue_interfaces: enabled_rescue_interfaces
- enabled_raid_interfaces: enabled_raid_interfaces
- enabled_storage_interfaces: enabled_storage_interfaces
- enabled_vendor_interfaces: enabled_vendor_interfaces
Response Example
----------------
Example for a request with detail=false (the default):
.. literalinclude:: samples/drivers-list-response.json
:language: javascript
Example for a request with detail=true:
.. literalinclude:: samples/drivers-list-detail-response.json
:language: javascript
Show driver details
===================
.. rest_method:: GET /v1/drivers/{driver_name}
Shows details for a driver.
.. versionadded:: 1.77
Added ``fields`` selector to query for particular fields.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- driver_name: driver_ident
- fields: fields
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- name: driver_name
- hosts: hosts
- type: response_driver_type
- default_bios_interface: default_bios_interface
- default_boot_interface: default_boot_interface
- default_console_interface: default_console_interface
- default_deploy_interface: default_deploy_interface
- default_inspect_interface: default_inspect_interface
- default_management_interface: default_management_interface
- default_network_interface: default_network_interface
- default_power_interface: default_power_interface
- default_raid_interface: default_raid_interface
- default_rescue_interface: default_rescue_interface
- default_storage_interface: default_storage_interface
- default_vendor_interface: default_vendor_interface
- enabled_bios_interfaces: enabled_bios_interfaces
- enabled_boot_interfaces: enabled_boot_interfaces
- enabled_console_interfaces: enabled_console_interfaces
- enabled_deploy_interfaces: enabled_deploy_interfaces
- enabled_inspect_interfaces: enabled_inspect_interfaces
- enabled_management_interfaces: enabled_management_interfaces
- enabled_network_interfaces: enabled_network_interfaces
- enabled_power_interfaces: enabled_power_interfaces
- enabled_raid_interfaces: enabled_raid_interfaces
- enabled_rescue_interfaces: enabled_rescue_interfaces
- enabled_storage_interfaces: enabled_storage_interfaces
- enabled_vendor_interfaces: enabled_vendor_interfaces
- links: links
- properties: driver_property_links
Response Example
----------------
.. literalinclude:: samples/driver-get-response.json
:language: javascript
Show driver properties
======================
.. rest_method:: GET /v1/drivers/{driver_name}/properties
Shows the required and optional parameters that ``driver_name`` expects to be
supplied in the ``driver_info`` field for every Node it manages.
To check if all required parameters have been supplied to a Node, you should
query the ``/v1/nodes/{node_ident}/validate`` endpoint.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- driver_name: driver_ident
Response Example
----------------
The response BODY is a dictionary, but the keys are unique to each driver.
The structure of the response is ``property`` : ``description``.
The following example is returned from the ``agent_ipmitool`` driver.
.. literalinclude:: samples/driver-property-response.json
:language: javascript
Show driver logical disk properties
===================================
.. versionadded:: 1.12
.. rest_method:: GET /v1/drivers/{driver_name}/raid/logical_disk_properties
Show the required and optional parameters that ``driver_name`` expects to be
supplied in the node's ``raid_config`` field, if a RAID configuration change is
requested.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- driver_name: driver_ident
Response Example
----------------
The response BODY is a dictionary, but the keys are unique to each driver.
The structure of the response is ``property`` : ``description``.
The following example is returned from the ``agent_ipmitool`` driver.
.. literalinclude:: samples/driver-logical-disk-properties-response.json
:language: javascript
|
