Statistics
| Branch: | Tag: | Revision:

root / docs / quota-api-guide.rst @ 0f2bd3f9

History | View | Annotate | Download (17.7 kB)

1
Resources
2
---------
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

    
10
Get Resource List
11
.................
12

    
13
**GET** /account/v1.0/resources
14

    
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.
18

    
19
**Response Codes**:
20

    
21
======  =====================
22
Status  Description
23
======  =====================
24
200     Success
25
500     Internal Server Error
26
======  =====================
27

    
28
**Example Successful Response**:
29

    
30
.. code-block:: javascript
31

    
32
  {
33
      "cyclades.vm": {
34
          "unit": null,
35
          "description": "Number of virtual machines",
36
          "service": "cyclades_compute",
37
          "allow_in_projects": true
38
          },
39
      "cyclades.ram": {
40
          "unit": "bytes",
41
          "description": "Virtual machine memory",
42
          "service": "cyclades_compute",
43
          "allow_in_projects": true
44
          }
45
  }
46

    
47
Quotas
48
------
49

    
50
The system specifies user quotas for each available resource. Resources
51
can be allocated from various sources. By default, users get resources
52
from their user-specific `base projects', which are identified by the same
53
uuid as the users. For each combination of user,
54
source, and resource, the quota system keeps track of the maximum allowed
55
value (limit) and the current actual usage. The former is controlled by
56
the policy defined in Astakos; the latter is updated by the services that
57
actually implement the resource each time an allocation or deallocation
58
takes place.
59

    
60
Get Quotas
61
..........
62

    
63
**GET** /account/v1.0/quotas
64

    
65
====================  =========================
66
Request Header Name   Value
67
====================  =========================
68
X-Auth-Token          User authentication token
69
====================  =========================
70

    
71
A user can query their resources with this call. It returns in a nested
72
dictionary structure, for each source and resource, three indicators.
73
``limit`` and ``usage`` are as explained above. ``pending`` is related to
74
the commissioning system explained below. Roughly, if ``pending`` is non
75
zero, this indicates that some resource allocation process has started but
76
not finished properly. The project-level indicators ``project_limit``,
77
``project_usage`` and ``project_pending`` are included in the resource
78
dictionaries, too. The project quota must be taken into account in order to
79
compute the `effective` quota limit::
80

    
81
  taken_by_others = project_usage - usage
82
  effective_limit = min(limit, project_limit - taken_by_others)
83

    
84
**Response Codes**:
85

    
86
======  ============================
87
Status  Description
88
======  ============================
89
200     Success
90
401     Unauthorized (Missing token)
91
500     Internal Server Error
92
======  ============================
93

    
94
**Example Successful Response**:
95

    
96
.. code-block:: javascript
97

    
98
  {
99
      "base_project_id": {
100
          "cyclades.ram": {
101
              "usage": 536870912,
102
              "limit": 1073741824,
103
              "pending": 0,
104
              "project_usage": 536870912,
105
              "project_limit": 1073741824,
106
              "project_pending": 0
107

    
108
          },
109
          "cyclades.vm": {
110
              "usage": 2,
111
              "limit": 2,
112
              "pending": 0,
113
              "project_usage": 2,
114
              "project_limit: 2,
115
              "project_pending": 0
116
          }
117
      },
118
      "project:1": {
119
          "cyclades.ram": {
120
              "usage": 2147483648,
121
              "limit": 2147483648,
122
              "pending": 0,
123
              "project_usage": 4147483648,
124
              "project_limit": 14147483648,
125
              "project_pending": 0
126
          },
127
          "cyclades.vm": {
128
              "usage": 2,
129
              "limit": 5,
130
              "pending": 1,
131
              "project_usage": 4,
132
              "project_limit": 10,
133
              "project_pending": 1
134
          }
135
      }
136
  }
137

    
138
Get Quotas per Service
139
......................
140

    
141
**GET** /account/v1.0/service_quotas
142

    
143
====================  ============================
144
Request Header Name   Value
145
====================  ============================
146
X-Auth-Token          Service authentication token
147
====================  ============================
148

    
149
A service can query the user quotas for all resources related to it. By
150
default, it returns the quotas for all users, in the format explained above,
151
indexed by the user identifier (UUID).
152

    
153
Use the GET parameter ``?user=<uuid>`` to query for a single user.
154

    
155

    
156
**Response Codes**:
157

    
158
======  ============================
159
Status  Description
160
======  ============================
161
200     Success
162
401     Unauthorized (Missing token)
163
500     Internal Server Error
164
======  ============================
165

    
166
**Example Successful Response**:
167

    
168
.. code-block:: javascript
169

    
170
  {
171
      "1a6165d0-5020-4b6d-a4ad-83476632a584": {
172
          "base_project_id": {
173
              "cyclades.ram": {
174
                  "usage": 536870912,
175
                  "limit": 1073741824,
176
                  "pending": 0,
177
                  "project_usage": 536870912,
178
                  "project_limit": 1073741824,
179
                  "project_pending": 0
180
              },
181
              "cyclades.vm": {
182
                  "usage": 2,
183
                  "limit": 2,
184
                  "pending": 0,
185
                  "project_usage": 2,
186
                  "project_limit: 2,
187
                  "project_pending": 0
188
              }
189
          },
190
          "project:1": {
191
              "cyclades.ram": {
192
                  "usage": 2147483648,
193
                  "limit": 2147483648,
194
                  "pending": 0,
195
                  "project_usage": 4147483648,
196
                  "project_limit": 14147483648,
197
                  "project_pending": 0
198
              },
199
              "cyclades.vm": {
200
                  "usage": 2,
201
                  "limit": 5,
202
                  "pending": 1,
203
                  "project_usage": 4,
204
                  "project_limit": 10,
205
                  "project_pending": 1
206
              }
207
          }
208
      }
209
  }
210

    
211
**GET** /account/v1.0/service_project_quotas
212

    
213
====================  ============================
214
Request Header Name   Value
215
====================  ============================
216
X-Auth-Token          Service authentication token
217
====================  ============================
218

    
219
A service can also query the project quotas for all resources related to it.
220
By default, it returns the quotas for all projects, in the format explained
221
above, indexed by the project identifier (UUID).
222

    
223
Use the GET parameter ``?project=<uuid>`` to query for a single project.
224

    
225

    
226
**Response Codes**:
227

    
228
======  ============================
229
Status  Description
230
======  ============================
231
200     Success
232
401     Unauthorized (Missing token)
233
500     Internal Server Error
234
======  ============================
235

    
236
**Example Successful Response**:
237

    
238
.. code-block:: javascript
239

    
240
  {
241
      "base_project_id": {
242
          "cyclades.ram": {
243
              "project_usage": 536870912,
244
              "project_limit": 1073741824,
245
              "project_pending": 0
246
          },
247
          "cyclades.vm": {
248
              "project_usage": 2,
249
              "project_limit: 2,
250
              "project_pending": 0
251
          }
252
      },
253
      "base_project2_id": {
254
          "cyclades.ram": {
255
              "project_usage": 0,
256
              "project_limit": 1073741824,
257
              "project_pending": 0
258
          },
259
          "cyclades.vm": {
260
              "project_usage": 0,
261
              "project_limit: 2,
262
              "project_pending": 0
263
          }
264
      },
265
      "project:1": {
266
          "cyclades.ram": {
267
              "project_usage": 4147483648,
268
              "project_limit": 14147483648,
269
              "project_pending": 0
270
          },
271
          "cyclades.vm": {
272
              "project_usage": 4,
273
              "project_limit": 10,
274
              "project_pending": 1
275
          }
276
      }
277
  }
278

    
279
Commissions
280
-----------
281

    
282
When a resource allocation is about to take place, the service that performs
283
this operation can query the quota system to find out whether the planned
284
allocation would surpass some defined limits. If this is not the case, the
285
quota system registers this pending allocation. Upon the actual allocation
286
of resources, the service informs the quota system to definitely update the
287
usage.
288

    
289
Thus, changing quotas consists of two steps: in the first, the service
290
issues a *commission*, indicating which extra resources will be given to
291
particular users; in the second, it finalizes the commission by *accepting*
292
it (or *rejecting*, if the allocation did not actually take place).
293

    
294
Issue Commission
295
................
296

    
297
**POST** /account/v1.0/commissions
298

    
299
====================  ============================
300
Request Header Name   Value
301
====================  ============================
302
X-Auth-Token          Service authentication token
303
====================  ============================
304

    
305
A service issues a commission by providing a list of *provisions*, i.e. the
306
intended allocation for a particular user and project (in general,
307
``holder``), ``source``, and ``resource`` combination. Users must be
308
specified with ``user:<uuid>`` and projects with ``project:<uuid>``. When
309
charging a user/project pair for a given resource, the intended use is to
310
also charge the project separately (by including a provision with the
311
project as holder and ``null`` as source), as in the example below.
312

    
313
The request body consists of a JSON dict (as in the example below), which
314
apart from the provisions list can also contain the following optional
315
fields:
316

    
317
 * ``name``: An optional description of the operation
318
 * ``force``: Succeed even if a limit is surpassed
319
 * ``auto_accept``: Perform the two steps at once
320

    
321
**Example Request**:
322

    
323
.. code-block:: javascript
324

    
325
  {
326
      "force": false,
327
      "auto_accept": false,
328
      "name": "an optional description",
329
      "provisions": [
330
          {
331
              "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
332
              "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
333
              "resource": "cyclades.vm",
334
              "quantity": 1
335
          },
336
          {
337
              "holder": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
338
              "source": null,
339
              "resource": "cyclades.vm",
340
              "quantity": 1
341
          },
342
          {
343
              "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
344
              "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
345
              "resource": "cyclades.ram",
346
              "quantity": 536870912
347
          },
348
          {
349
              "holder": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
350
              "source": null,
351
              "resource": "cyclades.ram",
352
              "quantity": 536870912
353
          }
354
      ]
355
  }
356

    
357
**Response Codes**:
358

    
359
======  =======================================================
360
Status  Description
361
======  =======================================================
362
201     Success
363
400     Commission failed due to invalid input data
364
401     Unauthorized (Missing token)
365
404     Cannot find one of the target holdings
366
413     A quantity fell below zero in one of the holdings
367
413     A quantity exceeded the capacity in one of the holdings
368
500     Internal Server Error
369
======  =======================================================
370

    
371
On a successful commission, the call responds with a ``serial``, an identifier
372
for the commission. On failure, in the case of ``overLimit`` (413) or
373
``itemNotFound`` (404), the returned cloudFault contains an extra field
374
``data`` with additional application-specific information. It contains at
375
least the ``provision`` that is to blame and the actual ``name`` of the
376
exception raised. In the case of ``overLimit``, ``limit`` and ``usage`` are
377
also included.
378

    
379
**Example Successful Response**:
380

    
381
.. code-block:: javascript
382

    
383
  {
384
      "serial": 57
385
  }
386

    
387
**Example Failure Response**:
388

    
389
.. code-block:: javascript
390

    
391
  {
392
      "overLimit": {
393
          "message": "a human-readable error message",
394
          "code": 413,
395
          "data": {
396
              "provision": {
397
                  "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
398
                  "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
399
                  "resource": "cyclades.vm",
400
                  "quantity": 1
401
              },
402
              "name": "NoCapacityError",
403
              "limit": 2,
404
              "usage": 2
405
          }
406
      }
407
  }
408

    
409
Get Pending Commissions
410
.......................
411

    
412
**GET** /account/v1.0/commissions
413

    
414
====================  ============================
415
Request Header Name   Value
416
====================  ============================
417
X-Auth-Token          Service authentication token
418
====================  ============================
419

    
420
The service can query the quota system for all *pending* commissions
421
initiated by itself, that is, all commissions that have been issued
422
but not accepted or rejected (see below). The call responds with the list
423
of the serials of all pending commissions.
424

    
425
**Response Codes**:
426

    
427
======  ============================
428
Status  Description
429
======  ============================
430
200     Success
431
401     Unauthorized (Missing token)
432
500     Internal Server Error
433
======  ============================
434

    
435
**Example Successful Response**:
436

    
437
.. code-block:: javascript
438

    
439
  [<serial>, ...]
440

    
441
Get the Description of a Commission
442
...................................
443

    
444
**GET** /account/v1.0/commissions/<serial>
445

    
446
====================  ============================
447
Request Header Name   Value
448
====================  ============================
449
X-Auth-Token          Service authentication token
450
====================  ============================
451

    
452
This call allows a service to retrieve information for a pending commission.
453

    
454
**Response Codes**:
455

    
456
======  ============================
457
Status  Description
458
======  ============================
459
200     Success
460
401     Unauthorized (Missing token)
461
404     Commission Not Found
462
500     Internal Server Error
463
======  ============================
464

    
465
**Example Successful Response**:
466

    
467
.. code-block:: javascript
468

    
469
  {
470
      "serial": 57,
471
      "issue_time": "2013-04-08T10:19:15.0373+00:00",
472
      "name": "an optional description",
473
      "provisions": [
474
          {
475
              "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
476
              "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
477
              "resource": "cyclades.vm",
478
              "quantity": 1
479
          },
480
          {
481
              "holder": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
482
              "source": null,
483
              "resource": "cyclades.vm",
484
              "quantity": 1
485
          },
486
          {
487
              "holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
488
              "source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
489
              "resource": "cyclades.ram",
490
              "quantity": 536870912
491
          },
492
          {
493
              "holder": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
494
              "source": null,
495
              "resource": "cyclades.ram",
496
              "quantity": 536870912
497
          }
498
      ]
499
  }
500

    
501
Accept or Reject a Commission
502
.............................
503

    
504
**POST** /account/v1.0/commissions/<serial>/action
505

    
506
====================  ============================
507
Request Header Name   Value
508
====================  ============================
509
X-Auth-Token          Service authentication token
510
====================  ============================
511

    
512
With this call a service can *accept* or *reject* a pending commission, that
513
is, finalize the registered usage or undo commission issued.
514
The system guarantees that a commission can always be later accepted
515
or rejected, no matter what other commissions have taken place in the meantime.
516

    
517
To accept, include in the request body a field indexed by ``accept``;
518
likewise for rejecting.
519

    
520
**Example Requests**:
521

    
522
.. code-block:: javascript
523

    
524
  {
525
      "accept": ""
526
  }
527

    
528
  {
529
      "reject": ""
530
  }
531

    
532
**Response Codes**:
533

    
534
======  ============================
535
Status  Description
536
======  ============================
537
200     Success
538
401     Unauthorized (Missing token)
539
404     Commission Not Found
540
500     Internal Server Error
541
======  ============================
542

    
543
Accept or Reject Multiple Commissions
544
.....................................
545

    
546
**POST** /account/v1.0/commissions/action
547

    
548
====================  ============================
549
Request Header Name   Value
550
====================  ============================
551
X-Auth-Token          Service authentication token
552
====================  ============================
553

    
554
This allows to accept and reject multiple commissions in the same time,
555
by including the list of serials to accept and the list of serials to reject
556
in the request body.
557

    
558
**Example Request**:
559

    
560
.. code-block:: javascript
561

    
562
  {
563
      "accept": [56, 57],
564
      "reject": [56, 58, 59]
565
  }
566

    
567
The response includes the list of serials that have been actually
568
``accepted`` or ``rejected`` and those that ``failed``. The latter
569
consists of a list of pairs. The first element of the pair is a serial
570
that failed, the second element is a cloudFault describing the failure.
571

    
572
**Response Codes**:
573

    
574
======  ============================
575
Status  Description
576
======  ============================
577
200     Success
578
401     Unauthorized (Missing token)
579
500     Internal Server Error
580
======  ============================
581

    
582
**Example Successful Response**:
583

    
584
.. code-block:: javascript
585

    
586
  { "accepted": [57],
587
    "rejected": [59],
588
    "failed": [
589
        [56, {
590
                 "badRequest": {
591
                     "message": "cannot both accept and reject serial 56",
592
                     "code": 400
593
                     }
594
                 }
595
        ],
596
        [58, {
597
                 "itemNotFound": {
598
                     "message": "serial 58 does not exist",
599
                     "code": 404
600
                     }
601
                 }
602
        ]
603
    ]
604
  }