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
|
=====================
RESTful Web API (v1)
=====================
API Versioning
==============
Starting with the Kilo release ironic supports versioning of API. Version is
defined as a string of 2 integers separated by a dot: **X.Y**. Here ``X`` is a
major version, always equal to ``1`` at the moment of writing, ``Y`` is
a minor version. Server minor version is increased every time the API behavior
is changed (note `Exceptions from Versioning`_). `Nova versioning
documentation`_ has a nice guide on when to bump an API version.
Server indicates its minimum and maximum supported API versions in the
``X-OpenStack-Ironic-API-Minimum-Version`` and
``X-OpenStack-Ironic-API-Maximum-Version`` headers respectively, returned
with every response. Client may request a specific API version by providing
``X-OpenStack-Ironic-API-Version`` header with request.
If no version is requested by the client, minimum supported version - **1.1**,
is assumed. The client is only exposed to those API features that are supported
in the requested (explicitly or implicitly) API version (again note `Exceptions
from Versioning`_, they are not covered by this rule).
We recommend clients requiring stable API to always request a specific version
of API. However, a special value ``latest`` can be requested instead, which
always requests the newest supported API version.
.. _Nova versioning documentation: http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion
API Versions History
--------------------
**1.11** (breaking change)
Newly registered nodes begin in the ``enroll`` provision state by default,
instead of ``available``. To get them to the ``available`` state,
the ``manage`` action must first be ran, to verify basic hardware control.
On success the node moves to ``manageable`` provision state, then the
``provide`` action must be run, which will clean the node and
make it available.
**1.10**
Logical node names support all RFC 3986 unreserved characters.
Previously only valid fully qualified domain names could be used.
**1.9**
Add ability to filter nodes by provision state.
**1.8**
Add ability to return a subset of resource fields.
**1.7**
Add node ``clean_step`` field.
**1.6**
Add :ref:`inspection` process: introduce ``inspecting`` and ``inspectfail``
provision states, and ``inspect`` action that can be used when a node is in
``manageable`` provision state.
**1.5**
Add logical node names that can be used to address a node in addition to
the node UUID. Name is expected to be a valid `fully qualified domain
name`_ in this version of API.
**1.4**
Add ``manageable`` state and ``manage`` transition, which can be used to
move a node to ``manageable`` state from ``available``.
The node cannot be deployed in ``managable`` state.
This change is mostly a preparation for future inspection work
and introduction of ``enroll`` provision state.
**1.3**
Add node ``driver_internal_info`` field.
**1.2** (breaking change)
Renamed NOSTATE (``None`` in Python, ``null`` in JSON) node state to
``available``. This is needed to reduce confusion around ``None`` state,
especially when future additions to the state machine land.
**1.1**
This was the initial version when API versioning was introduced.
Includes the following changes from Kilo release cycle:
* Add node ``maintenance_reason`` field and an API endpoint to
set/unset the node maintenance mode.
* Add sync and async support for vendor passthru methods.
* Vendor passthru endpoints support different HTTP methods, not only
``POST``.
* Make vendor methods discoverable via the Ironic API.
* Add logic to store the config drive passed by Nova.
This has been the minimum supported version since versioning was
introduced.
**1.0**
This version denotes Juno API and was never explicitly supported, as API
versioning was not implemented in Juno, and **1.1** became the minimum
supported version in Kilo.
.. _fully qualified domain name: https://en.wikipedia.org/wiki/Fully_qualified_domain_name
Exceptions from Versioning
--------------------------
The following API-visible things are not covered by the API versioning:
* Current node state is always exposed as it is, even if not supported by the
requested API version, with exception of ``available`` state, which is
returned in version 1.1 as ``None`` (in Python) or ``null`` (in JSON).
* Data within free-form JSON attributes: ``properties``, ``driver_info``,
``instance_info``, ``driver_internal_info`` fields on a node object;
``extra`` fields on all objects.
* Addition of new drivers.
* All vendor passthru methods.
Chassis
=======
.. rest-controller:: ironic.api.controllers.v1.chassis:ChassisController
:webprefix: /v1/chassis
.. autotype:: ironic.api.controllers.v1.chassis.ChassisCollection
:members:
.. autotype:: ironic.api.controllers.v1.chassis.Chassis
:members:
Drivers
=======
.. rest-controller:: ironic.api.controllers.v1.driver:DriversController
:webprefix: /v1/drivers
.. rest-controller:: ironic.api.controllers.v1.driver:DriverPassthruController
:webprefix: /v1/drivers/(driver_name)/vendor_passthru
.. autotype:: ironic.api.controllers.v1.driver.DriverList
:members:
.. autotype:: ironic.api.controllers.v1.driver.Driver
:members:
Links
=====
.. autotype:: ironic.api.controllers.link.Link
:members:
Nodes
=====
.. rest-controller:: ironic.api.controllers.v1.node:NodesController
:webprefix: /v1/nodes
.. rest-controller:: ironic.api.controllers.v1.node:NodeMaintenanceController
:webprefix: /v1/nodes/(node_ident)/maintenance
.. rest-controller:: ironic.api.controllers.v1.node:BootDeviceController
:webprefix: /v1/nodes/(node_ident)/management/boot_device
.. rest-controller:: ironic.api.controllers.v1.node:NodeStatesController
:webprefix: /v1/nodes/(node_ident)/states
.. rest-controller:: ironic.api.controllers.v1.node:NodeConsoleController
:webprefix: /v1/nodes/(node_ident)/states/console
.. rest-controller:: ironic.api.controllers.v1.node:NodeVendorPassthruController
:webprefix: /v1/nodes/(node_ident)/vendor_passthru
.. autotype:: ironic.api.controllers.v1.node.ConsoleInfo
:members:
.. autotype:: ironic.api.controllers.v1.node.Node
:members:
.. autotype:: ironic.api.controllers.v1.node.NodeCollection
:members:
.. autotype:: ironic.api.controllers.v1.node.NodeStates
:members:
Ports
=====
.. rest-controller:: ironic.api.controllers.v1.port:PortsController
:webprefix: /v1/ports
.. autotype:: ironic.api.controllers.v1.port.PortCollection
:members:
.. autotype:: ironic.api.controllers.v1.port.Port
:members:
|
