Revision 0f2bd3f9 docs/quota-api-guide.rst
| b/docs/quota-api-guide.rst | ||
|---|---|---|
| 49 | 49 |
|
| 50 | 50 |
The system specifies user quotas for each available resource. Resources |
| 51 | 51 |
can be allocated from various sources. By default, users get resources |
| 52 |
from a single source, called ``system``. For each combination of user, |
|
| 52 |
from their user-specific `base projects', which are identified by the same |
|
| 53 |
uuid as the users. For each combination of user, |
|
| 53 | 54 |
source, and resource, the quota system keeps track of the maximum allowed |
| 54 | 55 |
value (limit) and the current actual usage. The former is controlled by |
| 55 | 56 |
the policy defined in Astakos; the latter is updated by the services that |
| ... | ... | |
| 69 | 70 |
|
| 70 | 71 |
A user can query their resources with this call. It returns in a nested |
| 71 | 72 |
dictionary structure, for each source and resource, three indicators. |
| 72 |
``limit`` and ``usage`` are as explained above. ``pending`` is related to the |
|
| 73 |
commissioning system explained below. Roughly, if ``pending`` is non zero, |
|
| 74 |
this indicates that some resource allocation process has started but not |
|
| 75 |
finished properly. |
|
| 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) |
|
| 76 | 83 |
|
| 77 | 84 |
**Response Codes**: |
| 78 | 85 |
|
| ... | ... | |
| 89 | 96 |
.. code-block:: javascript |
| 90 | 97 |
|
| 91 | 98 |
{
|
| 92 |
"system": {
|
|
| 99 |
"base_project_id": {
|
|
| 93 | 100 |
"cyclades.ram": {
|
| 94 | 101 |
"usage": 536870912, |
| 95 | 102 |
"limit": 1073741824, |
| 96 |
"pending": 0 |
|
| 103 |
"pending": 0, |
|
| 104 |
"project_usage": 536870912, |
|
| 105 |
"project_limit": 1073741824, |
|
| 106 |
"project_pending": 0 |
|
| 97 | 107 |
|
| 98 | 108 |
}, |
| 99 | 109 |
"cyclades.vm": {
|
| 100 | 110 |
"usage": 2, |
| 101 | 111 |
"limit": 2, |
| 102 |
"pending": 0 |
|
| 112 |
"pending": 0, |
|
| 113 |
"project_usage": 2, |
|
| 114 |
"project_limit: 2, |
|
| 115 |
"project_pending": 0 |
|
| 103 | 116 |
} |
| 104 | 117 |
}, |
| 105 | 118 |
"project:1": {
|
| 106 | 119 |
"cyclades.ram": {
|
| 107 | 120 |
"usage": 2147483648, |
| 108 | 121 |
"limit": 2147483648, |
| 109 |
"pending": 0 |
|
| 122 |
"pending": 0, |
|
| 123 |
"project_usage": 4147483648, |
|
| 124 |
"project_limit": 14147483648, |
|
| 125 |
"project_pending": 0 |
|
| 110 | 126 |
}, |
| 111 | 127 |
"cyclades.vm": {
|
| 112 | 128 |
"usage": 2, |
| 113 | 129 |
"limit": 5, |
| 114 |
"pending": 1 |
|
| 130 |
"pending": 1, |
|
| 131 |
"project_usage": 4, |
|
| 132 |
"project_limit": 10, |
|
| 133 |
"project_pending": 1 |
|
| 115 | 134 |
} |
| 116 | 135 |
} |
| 117 | 136 |
} |
| ... | ... | |
| 127 | 146 |
X-Auth-Token Service authentication token |
| 128 | 147 |
==================== ============================ |
| 129 | 148 |
|
| 130 |
A service can query the quotas for all resources related to it. By default,
|
|
| 131 |
it returns the quotas for all users, in the format explained above, indexed
|
|
| 132 |
by the user identifier (UUID). |
|
| 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).
|
|
| 133 | 152 |
|
| 134 | 153 |
Use the GET parameter ``?user=<uuid>`` to query for a single user. |
| 135 | 154 |
|
| ... | ... | |
| 150 | 169 |
|
| 151 | 170 |
{
|
| 152 | 171 |
"1a6165d0-5020-4b6d-a4ad-83476632a584": {
|
| 153 |
"system": {
|
|
| 172 |
"base_project_id": {
|
|
| 154 | 173 |
"cyclades.ram": {
|
| 155 | 174 |
"usage": 536870912, |
| 156 | 175 |
"limit": 1073741824, |
| 157 |
"pending": 0 |
|
| 176 |
"pending": 0, |
|
| 177 |
"project_usage": 536870912, |
|
| 178 |
"project_limit": 1073741824, |
|
| 179 |
"project_pending": 0 |
|
| 158 | 180 |
}, |
| 159 | 181 |
"cyclades.vm": {
|
| 160 | 182 |
"usage": 2, |
| 161 | 183 |
"limit": 2, |
| 162 |
"pending": 0 |
|
| 184 |
"pending": 0, |
|
| 185 |
"project_usage": 2, |
|
| 186 |
"project_limit: 2, |
|
| 187 |
"project_pending": 0 |
|
| 163 | 188 |
} |
| 164 | 189 |
}, |
| 165 | 190 |
"project:1": {
|
| 166 | 191 |
"cyclades.ram": {
|
| 167 | 192 |
"usage": 2147483648, |
| 168 | 193 |
"limit": 2147483648, |
| 169 |
"pending": 0 |
|
| 194 |
"pending": 0, |
|
| 195 |
"project_usage": 4147483648, |
|
| 196 |
"project_limit": 14147483648, |
|
| 197 |
"project_pending": 0 |
|
| 170 | 198 |
}, |
| 171 | 199 |
"cyclades.vm": {
|
| 172 | 200 |
"usage": 2, |
| 173 | 201 |
"limit": 5, |
| 174 |
"pending": 1 |
|
| 202 |
"pending": 1, |
|
| 203 |
"project_usage": 4, |
|
| 204 |
"project_limit": 10, |
|
| 205 |
"project_pending": 1 |
|
| 175 | 206 |
} |
| 176 | 207 |
} |
| 177 | 208 |
} |
| 178 | 209 |
} |
| 179 | 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 |
|
|
| 180 | 279 |
Commissions |
| 181 | 280 |
----------- |
| 182 | 281 |
|
| ... | ... | |
| 203 | 302 |
X-Auth-Token Service authentication token |
| 204 | 303 |
==================== ============================ |
| 205 | 304 |
|
| 206 |
A service issues a commission by providing a list of *provisions*, i.e. |
|
| 207 |
the intended allocation for a particular user (in general, ``holder``), |
|
| 208 |
``source``, and ``resource`` combination. |
|
| 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. |
|
| 209 | 312 |
|
| 210 | 313 |
The request body consists of a JSON dict (as in the example below), which |
| 211 | 314 |
apart from the provisions list can also contain the following optional |
| ... | ... | |
| 225 | 328 |
"name": "an optional description", |
| 226 | 329 |
"provisions": [ |
| 227 | 330 |
{
|
| 228 |
"holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad", |
|
| 229 |
"source": "system", |
|
| 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, |
|
| 230 | 339 |
"resource": "cyclades.vm", |
| 231 | 340 |
"quantity": 1 |
| 232 | 341 |
}, |
| 233 | 342 |
{
|
| 234 |
"holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad", |
|
| 235 |
"source": "system", |
|
| 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, |
|
| 236 | 351 |
"resource": "cyclades.ram", |
| 237 | 352 |
"quantity": 536870912 |
| 238 | 353 |
} |
| ... | ... | |
| 279 | 394 |
"code": 413, |
| 280 | 395 |
"data": {
|
| 281 | 396 |
"provision": {
|
| 282 |
"holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad", |
|
| 283 |
"source": "system",
|
|
| 397 |
"holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
|
|
| 398 |
"source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
|
|
| 284 | 399 |
"resource": "cyclades.vm", |
| 285 | 400 |
"quantity": 1 |
| 286 | 401 |
}, |
| ... | ... | |
| 357 | 472 |
"name": "an optional description", |
| 358 | 473 |
"provisions": [ |
| 359 | 474 |
{
|
| 360 |
"holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad", |
|
| 361 |
"source": "system",
|
|
| 475 |
"holder": "user:c02f315b-7d84-45bc-a383-552a3f97d2ad",
|
|
| 476 |
"source": "project:c02f315b-7d84-45bc-a383-552a3f97d2ad",
|
|
| 362 | 477 |
"resource": "cyclades.vm", |
| 363 | 478 |
"quantity": 1 |
| 364 | 479 |
}, |
| 365 | 480 |
{
|
| 366 |
"holder": "c02f315b-7d84-45bc-a383-552a3f97d2ad", |
|
| 367 |
"source": "system", |
|
| 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, |
|
| 368 | 495 |
"resource": "cyclades.ram", |
| 369 | 496 |
"quantity": 536870912 |
| 370 | 497 |
} |
Also available in: Unified diff