Revision 2cb83537
b/docs/quota-api-guide.rst | ||
---|---|---|
1 | 1 |
Resources |
2 | 2 |
--------- |
3 | 3 |
|
4 |
Synnefo services offer *resources* to their users. Each type of resource is |
|
5 |
registered in Astakos with a unique name. By convention, these names start |
|
6 |
with the service name, e.g. ``cyclades.vm`` is a resource representing the |
|
7 |
virtual machines offered by Cyclades. |
|
8 |
|
|
9 |
|
|
4 | 10 |
Get Resource List |
5 | 11 |
................. |
6 | 12 |
|
7 | 13 |
**GET** /astakos/api/resources |
8 | 14 |
|
9 |
**Normal Response Code**: 200 |
|
15 |
This call returns a description for each resource available in the system. |
|
16 |
The response consists of a dictionary, indexed by the resource name, which |
|
17 |
contains a number of attributes for each resource. |
|
10 | 18 |
|
11 |
**Error Response Codes**:
|
|
19 |
**Response Codes**: |
|
12 | 20 |
|
13 | 21 |
====== ===================== |
14 | 22 |
Status Description |
15 | 23 |
====== ===================== |
24 |
200 Success |
|
16 | 25 |
500 Internal Server Error |
17 | 26 |
====== ===================== |
18 | 27 |
|
... | ... | |
36 | 45 |
Quotas |
37 | 46 |
------ |
38 | 47 |
|
48 |
The system specifies user quotas for each available resource. Resources |
|
49 |
can be allocated from various sources. By default, users get resources |
|
50 |
from a single source, called ``system``. For each combination of user, |
|
51 |
source, and resource, the quota system keeps track of the maximum allowed |
|
52 |
value (limit) and the current actual usage. The former is controlled by |
|
53 |
the policy defined in Astakos; the latter is updated by the services that |
|
54 |
actually implement the resource each time an allocation or deallocation |
|
55 |
takes place. |
|
56 |
|
|
39 | 57 |
Get Quotas |
40 | 58 |
.......... |
41 | 59 |
|
... | ... | |
47 | 65 |
X-Auth-Token User authentication token |
48 | 66 |
==================== ========================= |
49 | 67 |
|
50 |
**Normal Response Code**: 200 |
|
68 |
A user can query their resources with this call. It returns in a nested |
|
69 |
dictionary structure, for each source and resource, three indicators. |
|
70 |
``limit`` and ``usage`` are as explained above. ``pending`` is related to the |
|
71 |
commissioning system explained below. Roughly, if ``pending`` is non zero, |
|
72 |
this indicates that some resource allocation process has started but not |
|
73 |
finished properly. |
|
51 | 74 |
|
52 |
**Error Response Codes**:
|
|
75 |
**Response Codes**: |
|
53 | 76 |
|
54 | 77 |
====== ============================ |
55 | 78 |
Status Description |
56 | 79 |
====== ============================ |
80 |
200 Success |
|
57 | 81 |
401 Unauthorized (Missing token) |
58 | 82 |
500 Internal Server Error |
59 | 83 |
====== ============================ |
... | ... | |
101 | 125 |
X-Auth-Token Service authentication token |
102 | 126 |
==================== ============================ |
103 | 127 |
|
104 |
Optional GET parameter: ?user=<uuid> |
|
128 |
A service can query the quotas for all resources related to it. By default, |
|
129 |
it returns the quotas for all users, in the format explained above, indexed |
|
130 |
by the user identifier (UUID). |
|
131 |
|
|
132 |
Use the GET parameter ``?user=<uuid>`` to query for a single user. |
|
105 | 133 |
|
106 |
**Normal Response Code**: 200 |
|
107 | 134 |
|
108 |
**Error Response Codes**:
|
|
135 |
**Response Codes**: |
|
109 | 136 |
|
110 | 137 |
====== ============================ |
111 | 138 |
Status Description |
112 | 139 |
====== ============================ |
140 |
200 Success |
|
113 | 141 |
401 Unauthorized (Missing token) |
114 | 142 |
500 Internal Server Error |
115 | 143 |
====== ============================ |
... | ... | |
150 | 178 |
Commissions |
151 | 179 |
----------- |
152 | 180 |
|
181 |
When a resource allocation is about to take place, the service that performs |
|
182 |
this operation can query the quota system to find out whether the planned |
|
183 |
allocation would surpass some defined limits. If this is not the case, the |
|
184 |
quota system registers this pending allocation. Upon the actual allocation |
|
185 |
of resources, the service informs the quota system to definitely update the |
|
186 |
usage. |
|
187 |
|
|
188 |
Thus, changing quotas consists of two steps: in the first, the service |
|
189 |
issues a *commission*, indicating which extra resources will be given to |
|
190 |
particular users; in the second, it finalizes the commission by *accepting* |
|
191 |
it (or *rejecting*, if the allocation did not actually take place). |
|
192 |
|
|
153 | 193 |
Issue Commission |
154 | 194 |
................ |
155 | 195 |
|
... | ... | |
161 | 201 |
X-Auth-Token Service authentication token |
162 | 202 |
==================== ============================ |
163 | 203 |
|
164 |
**Normal Response Code**: 201 |
|
204 |
A service issues a commission by providing a list of *provisions*, i.e. |
|
205 |
the intended allocation for a particular user (in general, ``holder``), |
|
206 |
``source``, and ``resource`` combination. |
|
165 | 207 |
|
166 |
**Error Response Codes**: |
|
208 |
The request body consists of a JSON dict (as in the example below), which |
|
209 |
apart from the provisions list can also contain the following optional |
|
210 |
fields: |
|
167 | 211 |
|
168 |
====== ======================================================= |
|
169 |
Status Description |
|
170 |
====== ======================================================= |
|
171 |
400 Commission failed due to invalid input data |
|
172 |
401 Unauthorized (Missing token) |
|
173 |
404 Cannot find one of the target holdings |
|
174 |
413 A quantity fell below zero in one of the holdings |
|
175 |
413 A quantity exceeded the capacity in one of the holdings |
|
176 |
500 Internal Server Error |
|
177 |
====== ======================================================= |
|
212 |
* ``name``: An optional description of the operation |
|
213 |
* ``force``: Succeed even if a limit is surpassed |
|
214 |
* ``auto_accept``: Perform the two steps at once |
|
178 | 215 |
|
179 | 216 |
**Example Request**: |
180 | 217 |
|
... | ... | |
200 | 237 |
] |
201 | 238 |
} |
202 | 239 |
|
240 |
**Response Codes**: |
|
241 |
|
|
242 |
====== ======================================================= |
|
243 |
Status Description |
|
244 |
====== ======================================================= |
|
245 |
201 Success |
|
246 |
400 Commission failed due to invalid input data |
|
247 |
401 Unauthorized (Missing token) |
|
248 |
404 Cannot find one of the target holdings |
|
249 |
413 A quantity fell below zero in one of the holdings |
|
250 |
413 A quantity exceeded the capacity in one of the holdings |
|
251 |
500 Internal Server Error |
|
252 |
====== ======================================================= |
|
253 |
|
|
254 |
On a successful commission, the call responds with a ``serial``, an identifier |
|
255 |
for the commission. On failure, in the case of ``overLimit`` (413) or |
|
256 |
``itemNotFound`` (404), the returned cloudFault contains an extra field |
|
257 |
``data`` with additional application-specific information. It contains at |
|
258 |
least the ``provision`` that is to blame and the actual ``name`` of the |
|
259 |
exception raised. In case of ``NoCapacityError``, ``limit`` and ``usage`` are |
|
260 |
also included; in case of ``NoQuantityError`` (that is, when attempting to |
|
261 |
release a value greater than what is registered), the ``available`` quantity |
|
262 |
is provided. |
|
263 |
|
|
203 | 264 |
**Example Successful Response**: |
204 | 265 |
|
205 | 266 |
.. code-block:: javascript |
... | ... | |
241 | 302 |
X-Auth-Token Service authentication token |
242 | 303 |
==================== ============================ |
243 | 304 |
|
244 |
**Normal Response Code**: 200 |
|
305 |
The service can query the quota system for all *pending* commissions |
|
306 |
initiated by itself, that is, all commissions that have been issued |
|
307 |
but not accepted or rejected (see below). The call responds with the list |
|
308 |
of the serials of all pending commissions. |
|
245 | 309 |
|
246 |
**Error Response Codes**:
|
|
310 |
**Response Codes**: |
|
247 | 311 |
|
248 | 312 |
====== ============================ |
249 | 313 |
Status Description |
250 | 314 |
====== ============================ |
315 |
200 Success |
|
251 | 316 |
401 Unauthorized (Missing token) |
252 | 317 |
500 Internal Server Error |
253 | 318 |
====== ============================ |
... | ... | |
269 | 334 |
X-Auth-Token Service authentication token |
270 | 335 |
==================== ============================ |
271 | 336 |
|
272 |
**Normal Response Code**: 200
|
|
337 |
This call allows a service to retrieve information for a pending commission.
|
|
273 | 338 |
|
274 |
**Error Response Codes**:
|
|
339 |
**Response Codes**: |
|
275 | 340 |
|
276 | 341 |
====== ============================ |
277 | 342 |
Status Description |
278 | 343 |
====== ============================ |
344 |
200 Success |
|
279 | 345 |
401 Unauthorized (Missing token) |
280 | 346 |
404 Commission Not Found |
281 | 347 |
500 Internal Server Error |
... | ... | |
316 | 382 |
X-Auth-Token Service authentication token |
317 | 383 |
==================== ============================ |
318 | 384 |
|
319 |
**Normal Response Code**: 200 |
|
385 |
With this call a service can *accept* or *reject* a pending commission, that |
|
386 |
is, finalize the registered usage or undo commission issued. |
|
387 |
The system guarantees that a commission can always be later accepted |
|
388 |
or rejected, no matter what other commissions have taken place in the meantime. |
|
320 | 389 |
|
321 |
**Error Response Codes**: |
|
322 |
|
|
323 |
====== ============================ |
|
324 |
Status Description |
|
325 |
====== ============================ |
|
326 |
401 Unauthorized (Missing token) |
|
327 |
404 Commission Not Found |
|
328 |
500 Internal Server Error |
|
329 |
====== ============================ |
|
390 |
To accept, include in the request body a field indexed by ``accept``; |
|
391 |
likewise for rejecting. |
|
330 | 392 |
|
331 | 393 |
**Example Requests**: |
332 | 394 |
|
... | ... | |
340 | 402 |
"reject": "" |
341 | 403 |
} |
342 | 404 |
|
405 |
**Response Codes**: |
|
406 |
|
|
407 |
====== ============================ |
|
408 |
Status Description |
|
409 |
====== ============================ |
|
410 |
200 Success |
|
411 |
401 Unauthorized (Missing token) |
|
412 |
404 Commission Not Found |
|
413 |
500 Internal Server Error |
|
414 |
====== ============================ |
|
415 |
|
|
343 | 416 |
Accept or Reject Multiple Commissions |
344 | 417 |
..................................... |
345 | 418 |
|
... | ... | |
351 | 424 |
X-Auth-Token Service authentication token |
352 | 425 |
==================== ============================ |
353 | 426 |
|
354 |
**Normal Response Code**: 200 |
|
355 |
|
|
356 |
**Error Response Codes**: |
|
357 |
|
|
358 |
====== ============================ |
|
359 |
Status Description |
|
360 |
====== ============================ |
|
361 |
401 Unauthorized (Missing token) |
|
362 |
500 Internal Server Error |
|
363 |
====== ============================ |
|
427 |
This allows to accept and reject multiple commissions in the same time, |
|
428 |
by including the list of serials to accept and the list of serials to reject |
|
429 |
in the request body. |
|
364 | 430 |
|
365 | 431 |
**Example Request**: |
366 | 432 |
|
... | ... | |
371 | 437 |
"reject": [56, 58, 59] |
372 | 438 |
} |
373 | 439 |
|
440 |
The response includes the list of serials that have been actually |
|
441 |
``accepted`` or ``rejected`` and those that ``failed``. The latter |
|
442 |
consists of a list of pairs. The first element of the pair is a serial |
|
443 |
that failed, the second element is a cloudFault describing the failure. |
|
444 |
|
|
445 |
**Response Codes**: |
|
446 |
|
|
447 |
====== ============================ |
|
448 |
Status Description |
|
449 |
====== ============================ |
|
450 |
200 Success |
|
451 |
401 Unauthorized (Missing token) |
|
452 |
500 Internal Server Error |
|
453 |
====== ============================ |
|
454 |
|
|
374 | 455 |
**Example Successful Response**: |
375 | 456 |
|
376 | 457 |
.. code-block:: javascript |
Also available in: Unified diff