Browse Source

Merge "Endpoint to list introspection statuses"

Jenkins 2 years ago
parent
commit
a68360f960
1 changed files with 299 additions and 0 deletions
  1. 299
    0
      specs/list-introspection-statuses.rst

+ 299
- 0
specs/list-introspection-statuses.rst View File

@@ -0,0 +1,299 @@
1
+..
2
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
3
+ License.
4
+
5
+ http://creativecommons.org/licenses/by/3.0/legalcode
6
+
7
+===========================
8
+List introspection statuses
9
+===========================
10
+
11
+`List introspection statuses RFE`_
12
+
13
+.. _List introspection statuses RFE: https://bugs.launchpad.net/ironic-\
14
+                                     inspector/+bug/1525238
15
+
16
+There is no way a user can get the list of all introspection statuses from the
17
+ironic inspector service besides first fetching a list of nodes from the ironic
18
+service. The ironic inspector misses an API endpoint to serve this information.
19
+The purpose of this spec is to describe such an endpoint.
20
+
21
+
22
+Problem description
23
+===================
24
+
25
+A user should be able to obtain a list of introspection statuses managed by
26
+ironic inspector through a dedicated API endpoint. The introspection status
27
+list item should provide *basic* status information about particular node
28
+introspection status and a link to the full introspection status endpoint. The
29
+list of the status items should be `paginated`_. It should be possible to
30
+filter the status list based on the ``started_at``, ``finished_at`` and
31
+``state`` node introspection status attributes.
32
+
33
+.. _paginated:  http://developer.openstack.org/api-ref/baremetal/index.html\
34
+                ?expanded=list-nodes-detail#list-nodes
35
+
36
+
37
+Proposed change
38
+===============
39
+
40
+The endpoint should reside at ``GET@/v1/introspection`` path yielding the list
41
+of introspection statuses, encoded in *JSON*. The endpoint should consider
42
+these queries affecting the pagination and filtering of the list:
43
+
44
+Pagination
45
+----------
46
+
47
+``?marker=<uuid>&limit=<number>`` The default and maximum value of the limit
48
+query is configurable as ``CONF.api_max_limit = 1000``. The default ordering of
49
+the resources for the pagination is based on the ``started_at, uuid`` tuple,
50
+newer items first. The pagination is always in effect to avoid exhausting
51
+server resources. With no marker specified, the user always receives first
52
+``CONF.api_max_limit`` statuses. Sorting keys can be changed through the query
53
+``?sort=<key[:asc|desc]>[,<key[:asc|desc]>...]``. The key can be any of the
54
+``started_at, finished_at, state, error, uuid`` attributes. It is possible to
55
+change the `sorting direction`_ through the ``[:asc|desc]`` sort key query
56
+direction suffix.
57
+
58
+.. _sorting direction: https://specs.openstack.org/openstack/openstack-specs/\
59
+                       specs/cli-sorting-args.html
60
+
61
+State query
62
+-----------
63
+
64
+``?state=<op>:<state_name>[,<state_name>...]`` Only return items matching the
65
+states specified; acts as a *set*. Allowed operators: ``=in: =nin:`` the latter
66
+meaning not in. Recognized state name values are as per the `HA Inspector
67
+spec`_ and as further amended with the `introspection state patch`_:
68
+``starting, waiting, processing, finished, reapplying, enrolling, error``.
69
+Just the first occurrence of the ``state`` query string field is considered,
70
+any repetitions are ignored.
71
+
72
+.. _HA inspector spec: https://specs.openstack.org/openstack/ironic-inspector
73
+                       -specs/specs/HA_inspector.html
74
+.. _introspection state patch: https://review.openstack.org/#/c/348943/
75
+
76
+Time query
77
+----------
78
+
79
+* ``?started_at=<op>:<time>[&started_at=...]``
80
+* ``?finished_at=(<op>:<time>)|null[&finished_at=...]``
81
+
82
+Return only items in specified time intervals. Values are `ISO8601 time stamp`_
83
+The default value ``finished_at=null`` meaning unfinished introspections.
84
+Allowed operators are: ``=gt: =ge: =lt: =le:`` See also the `API working group
85
+filtering specification`_.
86
+
87
+.. _ISO8601 time stamp: https://en.wikipedia.org/wiki/ISO_8601
88
+
89
+.. _API working group filtering specification: http://specs.openstack.org/\
90
+                                               openstack/api-wg/guidelines/\
91
+                                               pagination_filter_sort.html\
92
+                                               #time-based-filtering-queries
93
+
94
+Status item
95
+-----------
96
+
97
+The basic information about a node introspection status the endpoint serves,
98
+encoded in a JSON dictionary with these items:
99
+
100
+* ``uuid: <node_uuid>``
101
+* ``finished: true|false``
102
+* ``started_at: <time>``
103
+* ``finished_at: <time>|null`` the latter in case unfinished
104
+* ``state: <state_name>``
105
+* ``links``: a dictionary with the items:
106
+
107
+  * ``href: <introspection_url>``
108
+  * ``rel: self``
109
+
110
+
111
+Alternatives
112
+------------
113
+
114
+Maintain the status quo of fetching all nodes from the ironic service before
115
+visiting each node in the inspector service to obtain the node introspection
116
+status.
117
+
118
+
119
+Data model impact
120
+-----------------
121
+
122
+None
123
+
124
+HTTP API impact
125
+---------------
126
+
127
+Get list of introspection statuses
128
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
129
+
130
+With pagination and filtering:
131
+
132
+* Method: ``GET``
133
+* Path: ``/v1/introspection``
134
+
135
+Optional query string fields:
136
+  * ``?marker=<uuid>&limit=<number>`` pagination
137
+  * ``?sort=<key[:asc|desc]>[&sort=...]`` pagination, sorting keys
138
+  * ``?state=<op>:<state_name>[,<state_name>...]`` filtering, set-like
139
+  * ``started_at=<op>:<time>[&started_at=...]`` filtering, time interval
140
+  * ``finished_at=(<op>:<time>)|null[&finished_at=...]`` filtering, time
141
+    interval
142
+
143
+Response codes:
144
+
145
+* Normal http response code: ``200``
146
+* ``400`` for an invalid query string
147
+* ``404`` marker not found or invalid state
148
+
149
+JSON schema definition for the response data::
150
+
151
+    [
152
+      {
153
+        'uuid': '<node_uuid>',
154
+        'state': '<state_name>,
155
+        'finished': true/false,
156
+        'started_at': '<time>',
157
+        'finished_at': '<time>'|null,
158
+        'links': [{
159
+          'href': '<url_to_node_uuid_introspection_detail>',
160
+          'rel: 'self'
161
+        }]
162
+      },
163
+      ...
164
+    ]
165
+
166
+Example use cases:
167
+
168
+* ``GET@/v1/introspection?finished_at=2016-09-21/&limit=50`` all introspections
169
+  finished after 29th of September, 00:00 UTC, no matter the state, limited to
170
+  50
171
+* ``GET@/v1/introspection?finished_at=ge:15:30&state=error&sort=error:asc``
172
+  only error introspections since 15:30 Today, alphabetically
173
+  sorted by the error message
174
+* ``GET@/v1/introspection?finished_at=null``
175
+  pending introspections
176
+* ``GET@/v1/introspection?started_at=ge:15:30&state=waiting``
177
+  introspections that have been waiting since 15:30 Today
178
+
179
+Client (CLI) impact
180
+-------------------
181
+
182
+This change should be adopted by the python ironic inspector client project as
183
+well. The CLI should include a new subcommand with optional switches reflecting
184
+the API optional queries::
185
+
186
+    openstack baremetal introspection statuses \
187
+      [--states=<op>:<state_name>[,<state_name>...]]
188
+      [--started-at=(<op>:<time>)[,<op>:<time>...]]
189
+      [--finished-at=(<op>:<time>)|null[,(<op>:<time>)|null...]]
190
+      [--marker=<node_uuid>]
191
+      [--limit=<number>]
192
+      [--sort=<key[:asc|desc]>[,<key[:asc|desc]>...]]
193
+
194
+Without the pagination parameters, the command should return a complete list.
195
+The output should be formatted in a table as is usual for the ``openstack``
196
+commands.
197
+
198
+
199
+Ironic python agent impact
200
+--------------------------
201
+
202
+None
203
+
204
+Performance and scalability impact
205
+----------------------------------
206
+
207
+Filtering together with the pagination may have positive effect on the
208
+server-side resources utilization.
209
+
210
+
211
+Security impact
212
+---------------
213
+
214
+None
215
+
216
+Deployer impact
217
+---------------
218
+
219
+Due to the `Pagination`_, a new config option ``CONF.api_max_limit = 1000`` is
220
+introduced to limit the amount of items an API endpoint can return in a single
221
+request. This is to prevent server resource exhaustion.
222
+
223
+This new endpoint has an immediate impact and cannot be switched off in the
224
+ironic inspector service.
225
+
226
+Existing API clients, such as the python ironic inspector client, should
227
+continue working without any impact as the endpoint is new. Those would of
228
+course miss the feature altogether.
229
+
230
+The deployer is advised to update both the server and client sides, preferably
231
+in that order.
232
+
233
+Developer impact
234
+----------------
235
+
236
+Developers are suggested to adopt this endpoint instead of having to retrieve
237
+list of nodes from the ironic service before obtaining introspection statuses
238
+from the inspector service.
239
+
240
+
241
+Implementation
242
+==============
243
+
244
+Assignees
245
+---------
246
+
247
+* Milan Kovacik, #milan, <vetrisko>
248
+* Dmitry Tantsur, #dtantsur, <divius>
249
+
250
+Primary assignee: <vetrisko>
251
+
252
+Work Items
253
+----------
254
+
255
+This feature can be implemented in more patches, for instance, landing
256
+pagination before state-based and time-based filtering might make the most
257
+sense for both the ironic inspector and python ironic inspector client
258
+projects.
259
+
260
+A `partial implementation`_ of the status list API endpoint for the ironic
261
+inspector project is currently blocked by this specification landing. It
262
+supports time-based filtering and pagination already.
263
+
264
+.. _partial implementation: https://review.openstack.org/#/c/344921
265
+
266
+Dependencies
267
+============
268
+
269
+This feature can be implemented without any dependencies although it would be
270
+reasonable to depend on the `introspection state patch`_ to limit code
271
+rewrites.
272
+
273
+
274
+Testing
275
+=======
276
+
277
+Functional and unit-testing with both the ironic inspector server and python
278
+ironic inspector client projects.
279
+
280
+
281
+References
282
+==========
283
+
284
+* `List introspection statuses RFE`_
285
+* `State query for list introspection statuses RFE`_
286
+* `HA inspector spec`_
287
+* `Introspection state patch`_
288
+* `Flask query handling`_
289
+* `Partial implementation`_ of the list API endpoint for the inspector
290
+* `API working group filtering specification`_
291
+* Global CLI `sorting direction`_ guidelines
292
+
293
+.. _State query for list introspection statuses RFE: https://bugs\
294
+                                                     .launchpad.net/\
295
+                                                     ironic-inspector/\
296
+                                                     +bug/1625183
297
+
298
+.. _Flask query handling: http://flask.pocoo.org/docs/0.11/api/#flask.\
299
+                          Request.args

Loading…
Cancel
Save