root / docs / cyclades-api-guide.rst @ e7f266c3
History | View | Annotate | Download (93.6 kB)
1 |
.. _cyclades-api-guide: |
---|---|
2 |
|
3 |
API Guide |
4 |
********* |
5 |
|
6 |
`Cyclades <cyclades.html>`_ is the compute service developed by `GRNET |
7 |
<http://www.grnet.gr>`_ as part of the `synnefo <http://www.synnefo.org>`_ |
8 |
software, that implements an extension of the `OpenStack Compute API v2 |
9 |
<http://docs.openstack.org/api/openstack-compute/2/content>`_. |
10 |
|
11 |
This document's goals are: |
12 |
|
13 |
* Define the Cyclades/Compute ReST API |
14 |
* Clarify the differences between Cyclades and OOS Compute |
15 |
|
16 |
Users and developers who wish to access a synnefo Cyclades service through its |
17 |
ReST API are adviced to use the `kamaki <http://docs.dev.grnet.gr/kamaki>`_ |
18 |
command-line client and associated python library, instead of making direct |
19 |
calls. |
20 |
|
21 |
Overview |
22 |
======== |
23 |
|
24 |
* It is not defined if requests for invalid URLs should return 404 or a Fault. |
25 |
We return a BadRequest Fault. |
26 |
* It is not defined if requests with a wrong HTTP method should return 405 or a |
27 |
Fault. We return a BadRequest Fault. |
28 |
|
29 |
|
30 |
General API Information |
31 |
======================= |
32 |
|
33 |
Authentication |
34 |
-------------- |
35 |
|
36 |
* Authentication support is missing. |
37 |
|
38 |
|
39 |
Request/Response Types |
40 |
---------------------- |
41 |
|
42 |
* We only support JSON Requests and JSON/XML Responses. XML Requests are not |
43 |
supported for now. |
44 |
|
45 |
|
46 |
Content Compression |
47 |
------------------- |
48 |
|
49 |
* Optional content compression support is missing. |
50 |
|
51 |
|
52 |
Persistent Connections |
53 |
---------------------- |
54 |
|
55 |
* Deployment note: "To prevent abuse, HTTP sessions have a timeout of 20 |
56 |
seconds before being closed." |
57 |
|
58 |
|
59 |
Links and References |
60 |
-------------------- |
61 |
|
62 |
* Full URI references support is missing. |
63 |
* Self and bookmark links support is missing. |
64 |
|
65 |
|
66 |
Paginated Collections |
67 |
--------------------- |
68 |
|
69 |
* Pagination support is missing. |
70 |
|
71 |
|
72 |
Caching |
73 |
------- |
74 |
|
75 |
* We do not return cached responses. |
76 |
|
77 |
|
78 |
Limits |
79 |
------ |
80 |
|
81 |
* Limits support is missing. |
82 |
|
83 |
|
84 |
Efficient Polling with the Changes-Since Parameter |
85 |
-------------------------------------------------- |
86 |
|
87 |
* Effectively limit support of the changes-since parameter in **List Servers** |
88 |
and **List Images**. |
89 |
* Assume that garbage collection of deleted servers will only affect servers |
90 |
deleted ``POLL_TIME`` seconds in the past or earlier. Else loose the |
91 |
information of a server getting deleted. |
92 |
* Images do not support a deleted state, so deletions cannot be tracked. |
93 |
|
94 |
|
95 |
Versions |
96 |
-------- |
97 |
|
98 |
* Version MIME type support is missing. |
99 |
* Versionless requests are not supported. |
100 |
* We hardcode the ``updated`` field in versions list |
101 |
* Deployment note: The Atom metadata needs to be fixed |
102 |
|
103 |
|
104 |
Extensions |
105 |
---------- |
106 |
|
107 |
* Extensions support is missing. |
108 |
|
109 |
|
110 |
Faults |
111 |
------ |
112 |
|
113 |
|
114 |
API Operations |
115 |
============== |
116 |
|
117 |
Servers |
118 |
------- |
119 |
|
120 |
* ``hostId`` is always empty. |
121 |
* ``affinityId`` is not returned. |
122 |
* ``progress`` is always returned. |
123 |
* ``self`` and ``bookmark`` atom links are not returned. |
124 |
* **Get Server Details** will also return servers with a DELETED state. |
125 |
* **Create Server** does not support setting the password in the request. |
126 |
|
127 |
List Servers |
128 |
............ |
129 |
|
130 |
=================== ====== ======== ========== |
131 |
URI Method Cyclades OS Compute |
132 |
=================== ====== ======== ========== |
133 |
``/servers`` GET ✔ ✔ |
134 |
``/servers/detail`` GET ✔ ✔ |
135 |
=================== ====== ======== ========== |
136 |
|
137 |
* Both requests return a list of servers. The first returns just ``id`` and |
138 |
``name``, while the second returns the full collections of server attributes. |
139 |
|
140 |
================= =================================== ======== ========== |
141 |
Request Parameter Value Cyclades OS Compute |
142 |
================= =================================== ======== ========== |
143 |
json Respond in json default **✘** |
144 |
xml Respond in xml ✔ **✘** |
145 |
changes-since Servers delete since that timestamp ✔ ✔ |
146 |
image Image reference **✘** ✔ |
147 |
flavor VM flavor reference **✘** ✔ |
148 |
server Server flavor reference **✘** ✔ |
149 |
status Server status **✘** ✔ |
150 |
marker Last list last ID **✘** ✔ |
151 |
limit Page size **✘** ✔ |
152 |
================= =================================== ======== ========== |
153 |
|
154 |
* **json** and **xml** parameters are mutually exclusive. If none supported, |
155 |
the response will be formated in json. |
156 |
|
157 |
* **status** refers to the `server status <#status-ref>`_ |
158 |
|
159 |
* **changes-since** must be an ISO8601 date string |
160 |
|
161 |
| |
162 |
|
163 |
============== ========================= ======== ========== |
164 |
Request Header Value Cyclades OS Compute |
165 |
============== ========================= ======== ========== |
166 |
X-Auth-Token User authentication token required required |
167 |
============== ========================= ======== ========== |
168 |
|
169 |
| |
170 |
|
171 |
=========================== ===================== |
172 |
Return Code Description |
173 |
=========================== ===================== |
174 |
200 (OK) Request succeeded |
175 |
304 (No servers since date) Can be returned if ``changes-since`` is given |
176 |
400 (Bad Request) Invalid or malformed ``changes-since`` parameter |
177 |
401 (Unauthorized) Missing or expired user token |
178 |
403 (Forbidden) User is not allowed to perform this operation |
179 |
500 (Internal Server Error) The request cannot be completed because of an |
180 |
\ internal error |
181 |
503 (Service Unavailable) The server is not currently available |
182 |
=========================== ===================== |
183 |
|
184 |
|
185 |
The response data format is a list of servers under the ``servers`` label. A |
186 |
server may have the fields presented bellow: |
187 |
|
188 |
================= ====================== ======== ========== |
189 |
Server Attributes Description Cyclades OS Compute |
190 |
================= ====================== ======== ========== |
191 |
id The server id ✔ ✔ |
192 |
name The server name ✔ ✔ |
193 |
hostId Server playground empty ✔ |
194 |
created Creation date ✔ ✔ |
195 |
updated Creation date ✔ ✔ |
196 |
flavorRef The flavor id ✔ **✘** |
197 |
flavor The flavor id **✘** ✔ |
198 |
imageRef The image id ✔ **✘** |
199 |
image The image id **✘** ✔ |
200 |
progress Build progress ✔ ✔ |
201 |
status Server status ✔ ✔ |
202 |
attachments Network interfaces ✔ **✘** |
203 |
addresses Network interfaces **✘** ✔ |
204 |
metadata Server custom metadata ✔ ✔ |
205 |
================= ====================== ======== ========== |
206 |
|
207 |
* **hostId** is not used in Cyclades, but is returned as an empty string for compatibility |
208 |
|
209 |
|
210 |
* **progress** is changing while the server is building up and has values |
211 |
between 0 and 100. When it reaches 100 the server is built. |
212 |
|
213 |
|
214 |
* **status** refers to `the status <#status-ref>`_ of the server |
215 |
|
216 |
* **metadata** are custom key:value pairs used to specify various attributes of |
217 |
the VM (e.g. OS, super user, etc.) |
218 |
|
219 |
|
220 |
* **attachments** in Cyclades are lists of network interfaces (nics). |
221 |
**Attachments** are different to OS Compute's **addresses**. The former is a |
222 |
list of the server's `network interface connections <#nic-ref>`_ while the |
223 |
later is just a list of networks. Thus, a Cyclades virtual server may be |
224 |
connected to the same network through more than one distinct network interfaces |
225 |
(e.g. server 43 is connected to network 101 with nic-43-1 and nic-43-2 in the |
226 |
example bellow). |
227 |
|
228 |
* **Network Interfaces (NICs)** contain information about a server's connection |
229 |
to a network. Each nic is identified by an id of the form |
230 |
nic-<server-id>-<ordinal-number> and may contain a ``network_id``, a |
231 |
``mac_address``, ``ipv4`` and ``ipv6`` addresses and the ``firewallProfile`` of |
232 |
the connection. |
233 |
|
234 |
**Example List Servers: JSON** |
235 |
|
236 |
.. code-block:: javascript |
237 |
|
238 |
{ |
239 |
'servers': |
240 |
{'values': [ |
241 |
{ |
242 |
'attachments': {'values': [ |
243 |
{ |
244 |
'id': 'nic-42-0', |
245 |
'network_id': '101', |
246 |
'mac_address': 'aa:00:00:49:2e:7e', |
247 |
'firewallProfile': DISABLED, |
248 |
'ipv4': '192.168.4.5', |
249 |
'ipv6': '2001:648:2ffc:1222:a800:ff:fef5:3f5b' |
250 |
} |
251 |
]}, |
252 |
'created': '2011-04-19T10:18:52.085737+00:00', |
253 |
'flavorRef': 1, |
254 |
'hostId': '', |
255 |
'id': 42, |
256 |
'imageRef': 3, |
257 |
'metadata': {'values': {'foo': 'bar'}}, |
258 |
'name': 'My Server', |
259 |
'status': 'ACTIVE', |
260 |
'updated': u'2011-05-29T14:07:07.037602+00:00' |
261 |
}, |
262 |
{ |
263 |
'attachments': {'values': [ |
264 |
{ |
265 |
'id': 'nic-43-0', |
266 |
'mac': 'aa:00:00:91:2f:df', |
267 |
'network_id': '1', |
268 |
'ipv4': '192.168.32.2' |
269 |
}, |
270 |
{ |
271 |
'id': 'nic-43-1', |
272 |
'network_id': '101', |
273 |
'mac_address': 'aa:00:00:49:2g:7f', |
274 |
'firewallProfile': DISABLED, |
275 |
'ipv4': '192.168.32.6', |
276 |
'ipv6': '2001:648:2ffc:1222:a800:ff:fef5:3f5c' |
277 |
}, |
278 |
{ |
279 |
'id': 'nic-43-2', |
280 |
'network_id': '101', |
281 |
'mac_address': 'aa:00:00:51:2h:7f', |
282 |
'firewallProfile': DISABLED, |
283 |
'ipv4': '192.168.32.7', |
284 |
'ipv6': '2001:638:2eec:1222:a800:ff:fef5:3f5c' |
285 |
} |
286 |
]}, |
287 |
'created': '2011-05-02T20:51:08.527759+00:00', |
288 |
'flavorRef': 1, |
289 |
'hostId': '', |
290 |
'id': 43, |
291 |
'imageRef': 3, |
292 |
'name': 'Other Server', |
293 |
'description': 'A sample server to showcase server requests', |
294 |
'progress': 0, |
295 |
'status': 'ACTIVE', |
296 |
'updated': '2011-05-29T14:59:11.267087+00:00' |
297 |
} |
298 |
] |
299 |
} |
300 |
} |
301 |
|
302 |
|
303 |
Create Server |
304 |
............. |
305 |
|
306 |
=================== ====== ======== ========== |
307 |
URI Method Cyclades OS Compute |
308 |
=================== ====== ======== ========== |
309 |
``/servers`` POST ✔ ✔ |
310 |
=================== ====== ======== ========== |
311 |
|
312 |
| |
313 |
|
314 |
================= =============== |
315 |
Request Parameter Value |
316 |
================= =============== |
317 |
json Respond in json |
318 |
xml Respond in xml |
319 |
================= =============== |
320 |
|
321 |
| |
322 |
|
323 |
============== ========================= ======== ========== |
324 |
Request Header Value Cyclades OS Compute |
325 |
============== ========================= ======== ========== |
326 |
X-Auth-Token User authentication token required required |
327 |
============== ========================= ======== ========== |
328 |
|
329 |
The request body is json formated. It consists of a ``server`` tag over the |
330 |
following attributes: |
331 |
|
332 |
=========== ==================== ======== ========== |
333 |
Name Description Cyclades OS Compute |
334 |
=========== ==================== ======== ========== |
335 |
name The server name ✔ ✔ |
336 |
imageRef Image id ✔ ✔ |
337 |
flavorRef Resources flavor ✔ ✔ |
338 |
personality Personality contents ✔ ✔ |
339 |
metadata Custom metadata ✔ ✔ |
340 |
=========== ==================== ======== ========== |
341 |
|
342 |
* **name** can be any string |
343 |
|
344 |
* **imageRed** and **flavorRed** should refer to existing images and hardware |
345 |
flavors accessible by the user |
346 |
|
347 |
* **metadata** are key:value pairs of custom server-specific metadata. There |
348 |
are no semantic limitations. |
349 |
|
350 |
* **personality** (optional) is a list of personality injections. A personality injection is a small set of changes to a virtual server. Each change modifies a |
351 |
file on the virtual server, by injecting some data in it. The injected data |
352 |
(``content``) should exceed 10240 *bytes* in size and must be base64 encoded. A personality injection contains the following attributes: |
353 |
|
354 |
======== =================== ======== ========== |
355 |
Name Description Cyclades OS Compute |
356 |
======== =================== ======== ========== |
357 |
path File path on server ✔ ✔ |
358 |
contents Data to inject ✔ ✔ |
359 |
group User group ✔ **✘** |
360 |
mode File access mode ✔ **✘** |
361 |
owner File owner ✔ **✘** |
362 |
======== =================== ======== ========== |
363 |
|
364 |
| |
365 |
|
366 |
=========================== ===================== |
367 |
Return Code Description |
368 |
=========================== ===================== |
369 |
200 (OK) Request succeeded |
370 |
400 (Bad Request) Malformed request data |
371 |
401 (Unauthorized) Missing or expired user token |
372 |
403 (Forbidden) User is not allowed to perform this operation |
373 |
404 (Not Found) Image or Flavor not found |
374 |
413 (Over Limit) Exceeded some resource limit (#VMs, personality |
375 |
size, etc.) |
376 |
415 (Bad Media Type) |
377 |
500 (Internal Server Error) The request cannot be completed because of an |
378 |
\ internal error |
379 |
503 (Service Unavailable) No available backends or service currently |
380 |
\ unavailable |
381 |
=========================== ===================== |
382 |
|
383 |
| |
384 |
|
385 |
In case of a 200 return code, the Response Data are json-formated and consist |
386 |
of a `list of attributes <#server-ref>`_ under the ``server`` tag: |
387 |
|
388 |
For example:: |
389 |
|
390 |
{"server": { |
391 |
"id": 28130 |
392 |
"status": "BUILD", |
393 |
"updated": "2013-04-10T13:52:18.140686+00:00", |
394 |
"hostId": "", |
395 |
"name": "My Server Name: Example Name", |
396 |
"imageRef": "da7a211f-1db5-444a-938b-f901ce81a3e6", |
397 |
"created": "2013-04-10T13:52:17.085402+00:00", |
398 |
"flavorRef": 289, |
399 |
"adminPass": "fKCqlZe2at", |
400 |
"suspended": false, |
401 |
"progress": 0, |
402 |
}} |
403 |
|
404 |
Get Server Stats |
405 |
................ |
406 |
|
407 |
This operation returns URLs to graphs showing CPU and Network statistics. A |
408 |
``refresh`` attribute is returned as well that is the recommended refresh rate |
409 |
of the stats for the clients. |
410 |
|
411 |
.. note:: This operation is not included in OS Compute v2. |
412 |
|
413 |
============================== ====== ======== ========== |
414 |
URI Method Cyclades OS Compute |
415 |
============================== ====== ======== ========== |
416 |
``/servers/<server-id>/stats`` GET ✔ **✘** |
417 |
============================== ====== ======== ========== |
418 |
|
419 |
* **server-id** is the identifier of the virtual server |
420 |
|
421 |
| |
422 |
|
423 |
============== ========================= |
424 |
Request Header Value |
425 |
============== ========================= |
426 |
X-Auth-Token User authentication token |
427 |
============== ========================= |
428 |
|
429 |
| |
430 |
|
431 |
================= =============== |
432 |
Request Parameter Value |
433 |
================= =============== |
434 |
json Respond in json |
435 |
xml Respond in xml |
436 |
================= =============== |
437 |
|
438 |
* **json** and **xml** parameters are mutually exclusive. If none supported, |
439 |
the response will be formated in json. |
440 |
|
441 |
| |
442 |
|
443 |
=========================== ===================== |
444 |
Return Code Description |
445 |
=========================== ===================== |
446 |
200 (OK) Request succeeded |
447 |
400 (Bad Request) Invalid server ID or Server deleted |
448 |
401 (Unauthorized) Missing or expired user token |
449 |
403 (Forbidden) Administratively suspended server |
450 |
404 (Not Found) Server not found |
451 |
500 (Internal Server Error) The request cannot be completed because of an |
452 |
\ internal error |
453 |
503 (Service Unavailable) The server is not currently available |
454 |
=========================== ===================== |
455 |
|
456 |
| |
457 |
|
458 |
================== ====================== |
459 |
Response Parameter Description |
460 |
================== ====================== |
461 |
serverRef Server ID |
462 |
refresh Refresh frequency |
463 |
cpuBar Latest CPU load graph URL |
464 |
cpuTimeSeries CPU load / time graph URL |
465 |
netBar Latest Network load graph URL |
466 |
netTimeSeries Network load / time graph URL |
467 |
================== ====================== |
468 |
|
469 |
**Example Get Server Stats Response: JSON**: |
470 |
|
471 |
.. code-block:: javascript |
472 |
|
473 |
{ |
474 |
"stats": { |
475 |
"serverRef": 1, |
476 |
"refresh": 60, |
477 |
"cpuBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png", |
478 |
"cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png", |
479 |
"netBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png", |
480 |
"netTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png" |
481 |
} |
482 |
} |
483 |
|
484 |
**Example Get Network Details Response: XML**: |
485 |
|
486 |
.. code-block:: xml |
487 |
|
488 |
<?xml version="1.0" encoding="UTF-8"?> |
489 |
<stats xmlns="http://docs.openstack.org/compute/api/v1.1"\ |
490 |
xmlns:atom="http://www.w3.org/2005/Atom" |
491 |
serverRef="1" |
492 |
refresh="60" |
493 |
cpuBar="https://www.example.com/stats/snf-42/cpu-bar/", |
494 |
netTimeSeries="https://example.com/stats/snf-42/net-ts/", |
495 |
netBar="https://example.com/stats/snf-42/net-bar/", |
496 |
cpuTimeSeries="https://www.example.com/stats/snf-42/cpu-ts/" |
497 |
</stats> |
498 |
|
499 |
Get Server Diagnostics |
500 |
...................... |
501 |
|
502 |
This operation returns diagnostic information for a server. |
503 |
|
504 |
.. note:: This operation is not included in OS Compute v2. |
505 |
|
506 |
==================================== ====== ======== ========== |
507 |
URI Method Cyclades OS Compute |
508 |
==================================== ====== ======== ========== |
509 |
``/servers/<server-id>/diagnostics`` GET ✔ **✘** |
510 |
==================================== ====== ======== ========== |
511 |
|
512 |
* **server-id** is the identifier of the virtual server |
513 |
|
514 |
| |
515 |
|
516 |
============== ========================= |
517 |
Request Header Value |
518 |
============== ========================= |
519 |
X-Auth-Token User authentication token |
520 |
============== ========================= |
521 |
|
522 |
| |
523 |
|
524 |
=========================== ===================== |
525 |
Return Code Description |
526 |
=========================== ===================== |
527 |
200 (OK) Request succeeded |
528 |
400 (Bad Request) Invalid server ID or Server deleted |
529 |
401 (Unauthorized) Missing or expired user token |
530 |
403 (Forbidden) Administratively suspended server |
531 |
404 (Not Found) Server not found |
532 |
500 (Internal Server Error) The request cannot be completed because of an |
533 |
\ internal error |
534 |
503 (Service Unavailable) The server is not currently available |
535 |
=========================== ===================== |
536 |
|
537 |
If a 200 code is returned, the response body contains a list of items. Each |
538 |
item is a diagnostic entry and consists of the attributes presented bellow: |
539 |
|
540 |
==================== =========== |
541 |
Diagnostic attribute Description |
542 |
==================== =========== |
543 |
level Debug level |
544 |
created Log entry timestamp |
545 |
source Log source proccess |
546 |
source_date Log source date |
547 |
message Log description |
548 |
details Detailed log description |
549 |
==================== =========== |
550 |
|
551 |
For example: |
552 |
|
553 |
.. code-block:: javascript |
554 |
|
555 |
[ |
556 |
{ |
557 |
"level": "DEBUG", |
558 |
"created": "2013-04-09T15:25:53.965144+00:00", |
559 |
"source": "image-helper-task-start", |
560 |
"source_date": "2013-04-09T15:25:53.954695+00:00", |
561 |
"message": "FixPartitionTable", |
562 |
"details": null |
563 |
}, { |
564 |
"level": "DEBUG", |
565 |
"created": "2013-04-09T15:25:46.413718+00:00", |
566 |
"source": "image-info", |
567 |
"source_date": "2013-04-09T15:25:46.404477+00:00", |
568 |
"message": "Starting customization VM...", |
569 |
"details": null |
570 |
}, { |
571 |
"level": "DEBUG", |
572 |
"created": "2013-04-09T15:25:46.207038+00:00", |
573 |
"source": "image-info", |
574 |
"source_date": "2013-04-09T15:25:46.197183+00:00", |
575 |
"message": "Image copy finished.", |
576 |
"details": "All operations finished as they should. No errors reported." |
577 |
} |
578 |
] |
579 |
|
580 |
Get Server Details |
581 |
.................. |
582 |
|
583 |
======================== ====== ======== ========== |
584 |
URI Method Cyclades OS Compute |
585 |
======================== ====== ======== ========== |
586 |
``/servers/<server id>`` GET ✔ ✔ |
587 |
======================== ====== ======== ========== |
588 |
|
589 |
* **server-id** is the identifier of the virtual server |
590 |
|
591 |
| |
592 |
|
593 |
============== ========================= ======== ========== |
594 |
Request Header Value Cyclades OS Compute |
595 |
============== ========================= ======== ========== |
596 |
X-Auth-Token User authentication token required required |
597 |
============== ========================= ======== ========== |
598 |
|
599 |
| |
600 |
|
601 |
=========================== ===================== |
602 |
Return Code Description |
603 |
=========================== ===================== |
604 |
200 (OK) Request succeeded |
605 |
400 (Bad Request) Malformed server id |
606 |
401 (Unauthorized) Missing or expired user token |
607 |
403 (Forbidden) Administratively suspended server |
608 |
404 (Not Found) Server not found |
609 |
500 (Internal Server Error) The request cannot be completed because of an |
610 |
\ internal error |
611 |
503 (Service Unavailable) No available backends or service currently |
612 |
\ unavailable |
613 |
=========================== ===================== |
614 |
|
615 |
| |
616 |
|
617 |
The response data format is a list of servers under the ``servers`` label. A |
618 |
server may have the fields presented bellow: |
619 |
|
620 |
================= ====================== ======== ========== |
621 |
Server Attributes Description Cyclades OS Compute |
622 |
================= ====================== ======== ========== |
623 |
id The server id ✔ ✔ |
624 |
name The server name ✔ ✔ |
625 |
hostId Server playground empty ✔ |
626 |
created Creation date ✔ ✔ |
627 |
updated Creation date ✔ ✔ |
628 |
flavorRef The flavor id ✔ **✘** |
629 |
flavor The flavor id **✘** ✔ |
630 |
imageRef The image id ✔ **✘** |
631 |
image The image id **✘** ✔ |
632 |
progress Build progress ✔ ✔ |
633 |
status Server status ✔ ✔ |
634 |
suspended If server is suspended ✔ **✘** |
635 |
attachments Network interfaces ✔ **✘** |
636 |
addresses Network interfaces **✘** ✔ |
637 |
metadata Server custom metadata ✔ ✔ |
638 |
diagnostics Diagnostic information ✔ **✘** |
639 |
================= ====================== ======== ========== |
640 |
|
641 |
| |
642 |
|
643 |
* **hostId** is not used in Cyclades, but is returned as an empty string for compatibility |
644 |
|
645 |
* **progress** is changing while the server is building up and has values |
646 |
between 0 and 100. When it reaches 100 the server is built. |
647 |
|
648 |
* **status** refers to `the status <#status-ref>`_ of the server |
649 |
|
650 |
* **metadata** are custom key:value pairs used to specify various attributes of |
651 |
the VM (e.g. OS, super user, etc.) |
652 |
|
653 |
* **attachments** in Cyclades are lists of network interfaces (NICs). |
654 |
**Attachments** are different to OS Compute's **addresses**. The former is a |
655 |
list of the server's `network interface connections <#nic-ref>`_ while the |
656 |
later is just a list of networks. Thus, a Cyclades virtual server may be |
657 |
connected to the same network through more than one distinct network |
658 |
interfaces. |
659 |
|
660 |
* **diagnostics** is a list of items that contain key:value information useful |
661 |
for diagnosing the server behavior and may be used by the administrators of |
662 |
deployed Synnefo setups. |
663 |
|
664 |
**Example Details for server with id 42042, in JSON** |
665 |
|
666 |
.. code-block:: javascript |
667 |
|
668 |
{ |
669 |
"server": { |
670 |
"id": 42042, |
671 |
"name": "My Example Server", |
672 |
"status": "ACTIVE", |
673 |
"updated": "2013-04-18T10:09:57.824266+00:00", |
674 |
"hostId": "", |
675 |
"imageRef": "926a1bc5-2d85-49d4-aebe-0fc127ed89b9", |
676 |
"created": "2013-04-18T10:06:58.288273+00:00", |
677 |
"flavorRef": 22, |
678 |
"attachments": { |
679 |
"values": [{ |
680 |
"network_id": "1888", |
681 |
"mac_address": "aa:0c:f5:ad:16:41", |
682 |
"firewallProfile": "DISABLED", |
683 |
"ipv4": "83.212.112.56", |
684 |
"ipv6": "2001:648:2ffc:1119:a80c:f5ff:fead:1641", |
685 |
"id": "nic-42042-0" |
686 |
}] |
687 |
}, |
688 |
"suspended": false, |
689 |
"diagnostics": [{ |
690 |
"level": "DEBUG", |
691 |
"created": "2013-04-18T10:09:52.776920+00:00", |
692 |
"source": "image-info", |
693 |
"source_date": "2013-04-18T10:09:52.709791+00:00", |
694 |
"message": "Image customization finished successfully.", |
695 |
"details": null |
696 |
}], |
697 |
"progress": 100, |
698 |
"metadata": { |
699 |
"values": {"OS": "windows", "users": "Administrator"} |
700 |
} |
701 |
} |
702 |
} |
703 |
|
704 |
Rename Server |
705 |
............. |
706 |
|
707 |
======================== ====== ======== ========== |
708 |
URI Method Cyclades OS Compute |
709 |
======================== ====== ======== ========== |
710 |
``/servers/<server id>`` PUT ✔ ✔ |
711 |
======================== ====== ======== ========== |
712 |
|
713 |
* **server-id** is the identifier of the virtual server |
714 |
|
715 |
| |
716 |
|
717 |
============== ========================= ======== ========== |
718 |
Request Header Value Cyclades OS Compute |
719 |
============== ========================= ======== ========== |
720 |
X-Auth-Token User authentication token required required |
721 |
============== ========================= ======== ========== |
722 |
|
723 |
The request body is json formated. It consists of a ``server`` tag over the |
724 |
following attributes: |
725 |
|
726 |
=========== ==================== ======== ========== |
727 |
Name Description Cyclades OS Compute |
728 |
=========== ==================== ======== ========== |
729 |
name The server name ✔ ✔ |
730 |
accessIPv4 IP v4 address **✘** ✔ |
731 |
accessIPv6 IP v6 address **✘** ✔ |
732 |
=========== ==================== ======== ========== |
733 |
|
734 |
* In Cyclades, a virtual server may use multiple network connections, instead |
735 |
of limit them to one. |
736 |
|
737 |
| |
738 |
|
739 |
=========================== ===================== |
740 |
Return Code Description |
741 |
=========================== ===================== |
742 |
204 (OK) Request succeeded |
743 |
400 (Bad Request) Malformed request or malformed server id |
744 |
401 (Unauthorized) Missing or expired user token |
745 |
403 (Forbidden) User is not allowed to perform this operation |
746 |
404 (Not Found) Server not found |
747 |
415 (Bad Media Type) |
748 |
409 (Build In Progress) Server is not ready yet |
749 |
500 (Internal Server Error) The request cannot be completed because of an |
750 |
\ internal error |
751 |
503 (Service Unavailable) No available backends or service currently |
752 |
\ unavailable |
753 |
=========================== ===================== |
754 |
|
755 |
In case of a 204 return code, there will be no request results according to the |
756 |
Cyclades API, while the new server details are returned according to OS Compute |
757 |
API. |
758 |
|
759 |
Delete Server |
760 |
............. |
761 |
|
762 |
======================== ====== ======== ========== |
763 |
URI Method Cyclades OS Compute |
764 |
======================== ====== ======== ========== |
765 |
``/servers/<server id>`` DELETE ✔ ✔ |
766 |
======================== ====== ======== ========== |
767 |
|
768 |
* **server-id** is the identifier of the virtual server |
769 |
|
770 |
| |
771 |
|
772 |
============== ========================= ======== ========== |
773 |
Request Header Value Cyclades OS Compute |
774 |
============== ========================= ======== ========== |
775 |
X-Auth-Token User authentication token required required |
776 |
============== ========================= ======== ========== |
777 |
|
778 |
| |
779 |
|
780 |
=========================== ===================== |
781 |
Return Code Description |
782 |
=========================== ===================== |
783 |
204 (OK) Request succeeded |
784 |
400 (Bad Request) Malformed server id or machine already deleted |
785 |
401 (Unauthorized) Missing or expired user token |
786 |
404 (Not Found) Server not found |
787 |
409 (Build In Progress) Server is not ready yet |
788 |
500 (Internal Server Error) The request cannot be completed because of an |
789 |
\ internal error |
790 |
503 (Service Unavailable) Action not supported or service currently |
791 |
\ unavailable |
792 |
=========================== ===================== |
793 |
|
794 |
.. note:: When a server is deleted, all its connections are deleted too. |
795 |
Server Addresses |
796 |
---------------- |
797 |
|
798 |
List Addresses |
799 |
.............. |
800 |
|
801 |
List all network connections of a server |
802 |
|
803 |
============================ ====== ======== ========== |
804 |
URI Method Cyclades OS Compute |
805 |
============================ ====== ======== ========== |
806 |
``/servers/<server id>/ips`` GET ✔ ✔ |
807 |
============================ ====== ======== ========== |
808 |
|
809 |
* **server-id** is the identifier of the virtual server |
810 |
|
811 |
| |
812 |
|
813 |
============== ========================= ======== ========== |
814 |
Request Header Value Cyclades OS Compute |
815 |
============== ========================= ======== ========== |
816 |
X-Auth-Token User authentication token required required |
817 |
============== ========================= ======== ========== |
818 |
|
819 |
| |
820 |
|
821 |
================= =============== |
822 |
Request Parameter Value |
823 |
================= =============== |
824 |
json Respond in json |
825 |
xml Respond in xml |
826 |
================= =============== |
827 |
|
828 |
| |
829 |
|
830 |
=========================== ===================== |
831 |
Return Code Description |
832 |
=========================== ===================== |
833 |
200 (OK) Request succeeded |
834 |
400 (Bad Request) Malformed server id or machine already deleted |
835 |
401 (Unauthorized) Missing or expired user token |
836 |
404 (Not Found) Server not found |
837 |
409 (Build In Progress) Server is not ready yet |
838 |
500 (Internal Server Error) The request cannot be completed because of an |
839 |
\ internal error |
840 |
503 (Service Unavailable) Service currently unavailable |
841 |
=========================== ===================== |
842 |
|
843 |
If the return code is 200, the response body consists of a list of items under |
844 |
the ``addresses`` tag. Each item refers to a network interface connection (NIC). |
845 |
|
846 |
Each NIC connects the current server to a network. NICs are different to OS |
847 |
Compute's addresses. The formers are the server's |
848 |
`network interface connections <#nic-ref>`_ while the later describes a network. Cyclades API suggests this information can be acquired by the network_id, using |
849 |
the network part of the API. Thus, a Cyclades virtual server may be connected |
850 |
to the same network through more than one distinct network interfaces. The NIC |
851 |
mechanism allows more metadata to describe the network and its relation to the |
852 |
server. |
853 |
|
854 |
**An example of a response, in JSON** |
855 |
|
856 |
.. code-block:: javascript |
857 |
|
858 |
{ |
859 |
"addresses": { |
860 |
"values": [ |
861 |
{ |
862 |
"network_id": "1", |
863 |
"mac_address": "aa:00:03:7a:84:bb", |
864 |
"firewallProfile": "DISABLED", |
865 |
"ipv4": "192.168.0.27", |
866 |
"ipv6": "2001:646:2ffc:1222:a820:3fd:fe7a:84bb", |
867 |
"id": "nic-25455-0" |
868 |
}, { |
869 |
"network_id": "7", |
870 |
"mac_address": "aa:00:03:7a:84:cc", |
871 |
"firewallProfile": "DISABLED", |
872 |
"ipv4": "192.168.0.28", |
873 |
"ipv6": "2002:646:2fec:1222:a820:3fd:fe7a:84bc", |
874 |
"id": "nic-25455-1" |
875 |
}, |
876 |
] |
877 |
} |
878 |
} |
879 |
|
880 |
Get Server NIC by Network |
881 |
......................... |
882 |
|
883 |
Return the NIC that connects a server to a network |
884 |
|
885 |
========================================= ====== ======== ========== |
886 |
URI Method Cyclades OS Compute |
887 |
========================================= ====== ======== ========== |
888 |
``/servers/<server id>/ips/<network id>`` GET ✔ ✔ |
889 |
========================================= ====== ======== ========== |
890 |
|
891 |
* **server-id** is the identifier of the virtual server |
892 |
|
893 |
* **network-id** is the identifier of the virtual server |
894 |
|
895 |
| |
896 |
|
897 |
============== ========================= ======== ========== |
898 |
Request Header Value Cyclades OS Compute |
899 |
============== ========================= ======== ========== |
900 |
X-Auth-Token User authentication token required required |
901 |
============== ========================= ======== ========== |
902 |
|
903 |
| |
904 |
|
905 |
================= =============== |
906 |
Request Parameter Value |
907 |
================= =============== |
908 |
json Respond in json |
909 |
xml Respond in xml |
910 |
================= =============== |
911 |
|
912 |
| |
913 |
|
914 |
=========================== ===================== |
915 |
Return Code Description |
916 |
=========================== ===================== |
917 |
200 (OK) Request succeeded |
918 |
400 (Bad Request) Malformed server id or machine already deleted |
919 |
401 (Unauthorized) Missing or expired user token |
920 |
404 (Not Found) Server not found |
921 |
409 (Build In Progress) Server is not ready yet |
922 |
500 (Internal Server Error) The request cannot be completed because of an |
923 |
\ internal error |
924 |
503 (Service Unavailable) Service currently unavailable |
925 |
=========================== ===================== |
926 |
|
927 |
If the return code is 200, the response body consists of a NIC under the |
928 |
``network`` tag. |
929 |
|
930 |
This NIC (`network interface connections <#nic-ref>`_) connects the specified |
931 |
server to the specified network. NICs are only used in Cyclades API. The same |
932 |
operation in OS Compute API returns a list of IP addresses. |
933 |
|
934 |
**An example of a response, in JSON** |
935 |
|
936 |
.. code-block:: javascript |
937 |
|
938 |
{ |
939 |
"network": { |
940 |
"network_id": "7", |
941 |
"mac_address": "aa:00:03:7a:84:bb", |
942 |
"firewallProfile": "DISABLED", |
943 |
"ipv4": "192.168.0.27", |
944 |
"ipv6": "2001:646:2ffc:1222:a820:3fd:fe7a:84bb", |
945 |
"id": "nic-25455-0" |
946 |
} |
947 |
} |
948 |
|
949 |
Server Actions |
950 |
-------------- |
951 |
|
952 |
The request described in this section exists in both Synnefo API and OS Compute |
953 |
API as a multi-operation request. The individual operations implemented through |
954 |
this request are in many cases completely different between the two APIs. |
955 |
Although this document focuses on Synnefo operations, differences and |
956 |
similarities between the APIs are also briefed in this section. |
957 |
|
958 |
| |
959 |
|
960 |
============================= ======== ========== |
961 |
Operations Cyclades OS Compute |
962 |
============================= ======== ========== |
963 |
Start Server ✔ **✘** |
964 |
Shutdown Server ✔ **✘** |
965 |
Reboot Server ✔ ✔ |
966 |
Get Server Console ✔ **✘** |
967 |
Set Firewall Profile ✔ **✘** |
968 |
Change Administrator Password **✘** ✔ |
969 |
Rebuild Server **✘** ✔ |
970 |
Resize Server **✘** ✔ |
971 |
Confirm Resized Server **✘** ✔ |
972 |
Revert Resized Server **✘** ✔ |
973 |
Create Image **✘** ✔ |
974 |
============================= ======== ========== |
975 |
|
976 |
| |
977 |
|
978 |
====================================== ====== ======== ========== |
979 |
URI Method Cyclades OS Compute |
980 |
====================================== ====== ======== ========== |
981 |
``/servers/<server id>/action`` POST ✔ ✔ |
982 |
====================================== ====== ======== ========== |
983 |
|
984 |
| |
985 |
|
986 |
============== ========================= ======== ========== |
987 |
Request Header Value Cyclades OS Compute |
988 |
============== ========================= ======== ========== |
989 |
X-Auth-Token User authentication token required required |
990 |
============== ========================= ======== ========== |
991 |
|
992 |
| |
993 |
|
994 |
=========================== ===================== |
995 |
Return Code Description |
996 |
=========================== ===================== |
997 |
200 (OK) Request succeeded (for console operation) |
998 |
202 (OK) Request succeeded |
999 |
400 (Bad Request) Invalid request or unknown action |
1000 |
401 (Unauthorized) Missing or expired user token |
1001 |
403 (Forbidden) User is not allowed to perform this operation |
1002 |
500 (Internal Server Error) The request cannot be completed because of an |
1003 |
\ internal error |
1004 |
503 (Service Unavailable) The server is not currently available |
1005 |
=========================== ===================== |
1006 |
|
1007 |
Start server |
1008 |
................ |
1009 |
|
1010 |
This operation transitions a server from a STOPPED to an ACTIVE state. |
1011 |
|
1012 |
Request body must contain a ``start`` tag on an empty directory:: |
1013 |
|
1014 |
{ 'start': {}} |
1015 |
|
1016 |
|
1017 |
Reboot Server |
1018 |
............. |
1019 |
|
1020 |
This operation transitions a server from ``ACTIVE`` to ``REBOOT`` and then |
1021 |
``ACTIVE`` again. Synnefo and OS Compute APIs offer two reboot modes: soft and |
1022 |
hard. The only difference is that OS Compute distinguishes between the two |
1023 |
types of intermediate states (``REBOOT`` and ``HARD_REBOOT``) while rebooting, |
1024 |
but the expected behavior is the same in both APIs. |
1025 |
|
1026 |
Request body must contain a ``reboot`` tag over a ``type`` tag on the reboot |
1027 |
type:: |
1028 |
|
1029 |
{ 'reboot' : { 'type': <reboot type>}} |
1030 |
|
1031 |
* **reboot type** can be either ``SOFT`` or ``HARD``. |
1032 |
|
1033 |
** Reboot Action Request Body Example: JSON ** |
1034 |
|
1035 |
.. code-block:: javascript |
1036 |
|
1037 |
{ |
1038 |
'reboot': { |
1039 |
'type': 'hard' |
1040 |
} |
1041 |
} |
1042 |
|
1043 |
Shutdown server |
1044 |
............... |
1045 |
|
1046 |
This operation transitions a server from an ACTIVE to a STOPPED state. |
1047 |
|
1048 |
Request body must contain a ``shutdown`` tag on an empty directory:: |
1049 |
|
1050 |
{ 'shutdown': {}} |
1051 |
|
1052 |
Get Server Console |
1053 |
.................. |
1054 |
|
1055 |
The console operation arranges for an OOB console of the specified type. Only |
1056 |
consoles of type "vnc" are supported for now. Cyclades server uses a running |
1057 |
instance of vncauthproxy to setup proper VNC forwarding with a random password, |
1058 |
then returns the necessary VNC connection info to the caller. |
1059 |
|
1060 |
Request body must a contain a ``console`` tag over a ``type`` tag on a console |
1061 |
type:: |
1062 |
|
1063 |
console: {type: 'vnc' } |
1064 |
|
1065 |
If successful, it returns a **200** code and also a json formated body with the |
1066 |
following fields: |
1067 |
|
1068 |
================== ====================== |
1069 |
Response Parameter Description |
1070 |
================== ====================== |
1071 |
host The vncprocy host |
1072 |
port vncprocy port |
1073 |
password Temporary password |
1074 |
type Connection type (only VNC) |
1075 |
================== ====================== |
1076 |
|
1077 |
| |
1078 |
|
1079 |
**Example Action Console Response: JSON**: |
1080 |
|
1081 |
.. code-block:: javascript |
1082 |
|
1083 |
{ |
1084 |
"console": { |
1085 |
"type": "vnc", |
1086 |
"host": "vm42.example.org", |
1087 |
"port": 1234, |
1088 |
"password": "513NR4PN0T" |
1089 |
} |
1090 |
} |
1091 |
|
1092 |
**Example Action Console Response: XML**: |
1093 |
|
1094 |
.. code-block:: xml |
1095 |
|
1096 |
<?xml version="1.0" encoding="UTF-8"?> |
1097 |
<console xmlns="http://docs.openstack.org/compute/api/v1.1" |
1098 |
xmlns:atom="http://www.w3.org/2005/Atom" |
1099 |
type="vnc" |
1100 |
host="vm42.example.org" |
1101 |
port="1234" |
1102 |
password="513NR4PN0T"> |
1103 |
</console> |
1104 |
|
1105 |
Set Firewall Profile |
1106 |
.................... |
1107 |
|
1108 |
The firewallProfile function sets a firewall profile for the public interface |
1109 |
of a server. |
1110 |
|
1111 |
Request body must contain a ``firewallProfile`` tag over a ``profile`` tag on |
1112 |
the firewall type:: |
1113 |
|
1114 |
firewallProfile: { profile: <firewall profile> } |
1115 |
|
1116 |
* **firewall profile** can be ``ENABLED``, ``DISABLED`` or ``PROTECTED`` |
1117 |
|
1118 |
**Example Action firewallProfile: JSON**: |
1119 |
|
1120 |
.. code-block:: javascript |
1121 |
|
1122 |
{ |
1123 |
"firewallProfile": { |
1124 |
"profile": "ENABLED" |
1125 |
} |
1126 |
} |
1127 |
|
1128 |
|
1129 |
OS Compute API Specific |
1130 |
....................... |
1131 |
|
1132 |
* `Change Administrator Password <http://docs.openstack.org/api/openstack-compute/2/content/Change_Password-d1e3234.html>`_ |
1133 |
* `Rebuild Server <http://docs.openstack.org/api/openstack-compute/2/content/Rebuild_Server-d1e3538.html>`_ |
1134 |
* `Resize Server <http://docs.openstack.org/api/openstack-compute/2/content/Resize_Server-d1e3707.html>`_ |
1135 |
* `Confirm Resized Server <http://docs.openstack.org/api/openstack-compute/2/content/Confirm_Resized_Server-d1e3868.html>`_ |
1136 |
* `Revert Resized Server <http://docs.openstack.org/api/openstack-compute/2/content/Revert_Resized_Server-d1e4024.html>`_ |
1137 |
* `Create Image <http://docs.openstack.org/api/openstack-compute/2/content/Create_Image-d1e4655.html>`_ |
1138 |
|
1139 |
|
1140 |
Server Metadata |
1141 |
--------------- |
1142 |
|
1143 |
List metadata |
1144 |
............. |
1145 |
|
1146 |
.. note:: This operation is semantically equivalent in Cyclades and OS Compute. |
1147 |
|
1148 |
================================= ====== ======== ========== |
1149 |
URI Method Cyclades OS Compute |
1150 |
================================= ====== ======== ========== |
1151 |
``/servers/<server-id>/meta`` GET ✔ **✘** |
1152 |
``/servers/<server-id>/metadata`` GET **✘** ✔ |
1153 |
================================= ====== ======== ========== |
1154 |
|
1155 |
* **server-id** is the identifier of the virtual server |
1156 |
|
1157 |
| |
1158 |
|
1159 |
============== ========================= |
1160 |
Request Header Value |
1161 |
============== ========================= |
1162 |
X-Auth-Token User authentication token |
1163 |
============== ========================= |
1164 |
|
1165 |
| |
1166 |
|
1167 |
=========================== ===================== |
1168 |
Return Code Description |
1169 |
=========================== ===================== |
1170 |
200 (OK) Request succeeded |
1171 |
400 (Bad Request) Invalid server ID or Malformed request |
1172 |
401 (Unauthorized) Missing or expired user token |
1173 |
403 (Forbidden) Administratively suspended server |
1174 |
404 (Not Found) Server not found |
1175 |
500 (Internal Server Error) The request cannot be completed because of an |
1176 |
\ internal error |
1177 |
503 (Service Unavailable) The server is not currently available |
1178 |
=========================== ===================== |
1179 |
|
1180 |
In case of a 200 response code, the response should contain a JSON encoded list |
1181 |
of key:value pairs, under a 'values' tag which lies under a ``metadata`` tag, |
1182 |
for example:: |
1183 |
|
1184 |
{ |
1185 |
'metadata': { |
1186 |
'values': { |
1187 |
'OS': 'Linux', |
1188 |
'users': 'root' |
1189 |
} |
1190 |
} |
1191 |
} |
1192 |
|
1193 |
.. note:: In OS Compute API the ``values`` level is missing from the response |
1194 |
|
1195 |
Set / Update Server Metadata |
1196 |
............................ |
1197 |
|
1198 |
In Cyclades API, setting new metadata and updating the values of existing ones |
1199 |
is achieved with the same type of request (POST), while in OS Compute API there |
1200 |
are two separate request types (PUT and POST for |
1201 |
`setting new <http://docs.openstack.org/api/openstack-compute/2/content/Create_or_Replace_Metadata-d1e5358.html>`_ |
1202 |
and |
1203 |
`updating existing <http://docs.openstack.org/api/openstack-compute/2/content/Update_Metadata-d1e5208.html>`_ |
1204 |
metadata, respectively). |
1205 |
|
1206 |
In Cyclades API, metadata keys which are not referred by the operation will |
1207 |
remain intact, while metadata referred by the operation will be overwritten in |
1208 |
case of success. |
1209 |
|
1210 |
================================= ====== ======== ========== |
1211 |
URI Method Cyclades OS Compute |
1212 |
================================= ====== ======== ========== |
1213 |
``/servers/<server-id>/meta`` POST ✔ **✘** |
1214 |
``/servers/<server-id>/metadata`` PUT **✘** ✔ |
1215 |
``/servers/<server-id>/metadata`` POST **✘** ✔ |
1216 |
================================= ====== ======== ========== |
1217 |
|
1218 |
* **server-id** is the identifier of the virtual server |
1219 |
|
1220 |
| |
1221 |
|
1222 |
============== ========================= |
1223 |
Request Header Value |
1224 |
============== ========================= |
1225 |
X-Auth-Token User authentication token |
1226 |
============== ========================= |
1227 |
|
1228 |
| |
1229 |
|
1230 |
The request body should contain a JSON-formated set of key:value pairs, under |
1231 |
the ``metadata`` tag, e.g.:: |
1232 |
|
1233 |
{'metadata': {'role': 'webmail', 'users': 'root,maild'}} |
1234 |
|
1235 |
| |
1236 |
|
1237 |
=========================== ===================== |
1238 |
Return Code Description |
1239 |
=========================== ===================== |
1240 |
201 (OK) Request succeeded |
1241 |
400 (Bad Request) Invalid server ID or Malformed request |
1242 |
401 (Unauthorized) Missing or expired user token |
1243 |
403 (Forbidden) Administratively suspended server |
1244 |
404 (Not Found) Server not found |
1245 |
413 (OverLimit) Maximum number of metadata exceeded |
1246 |
500 (Internal Server Error) The request cannot be completed because of an |
1247 |
\ internal error |
1248 |
503 (Service Unavailable) The server is not currently available |
1249 |
=========================== ===================== |
1250 |
|
1251 |
| |
1252 |
|
1253 |
In case of a 201 code, the response body should present the new state of |
1254 |
servers metadata. E.g.:: |
1255 |
|
1256 |
{'metadata': {'OS': 'Linux', 'role': 'webmail', 'users': 'root,maild'}} |
1257 |
|
1258 |
Get Metadata Item |
1259 |
................. |
1260 |
|
1261 |
.. note:: This operation is semantically equivalent in Cyclades and OS Compute. |
1262 |
|
1263 |
======================================= ====== ======== ========== |
1264 |
URI Method Cyclades OS Compute |
1265 |
======================================= ====== ======== ========== |
1266 |
``/servers/<server-id>/meta/<key>`` GET ✔ **✘** |
1267 |
``/servers/<server-id>/metadata/<key>`` GET **✘** ✔ |
1268 |
======================================= ====== ======== ========== |
1269 |
|
1270 |
* **server-id** is the identifier of the virtual server |
1271 |
* **key** is the key of a matadatum key:value pair |
1272 |
|
1273 |
| |
1274 |
|
1275 |
============== ========================= |
1276 |
Request Header Value |
1277 |
============== ========================= |
1278 |
X-Auth-Token User authentication token |
1279 |
============== ========================= |
1280 |
|
1281 |
| |
1282 |
|
1283 |
=========================== ===================== |
1284 |
Return Code Description |
1285 |
=========================== ===================== |
1286 |
200 (OK) Request succeeded |
1287 |
400 (Bad Request) Invalid server ID or Malformed request |
1288 |
401 (Unauthorized) Missing or expired user token |
1289 |
403 (Forbidden) Administratively suspended server |
1290 |
404 (Not Found) Metadatum key not found |
1291 |
500 (Internal Server Error) The request cannot be completed because of an |
1292 |
\ internal error |
1293 |
503 (Service Unavailable) The server is not currently available |
1294 |
=========================== ===================== |
1295 |
|
1296 |
If the response code is 200, the response body contains the requested key:value |
1297 |
pair under a ``metadata`` tag. For example, if key was ``role``, the response |
1298 |
body would look similar to this:: |
1299 |
|
1300 |
{'metadata': {'role': 'webmail'}} |
1301 |
|
1302 |
.. note:: In OS Compute response, ``metadata`` is ``meta`` |
1303 |
|
1304 |
Set / Update Metadatum Item |
1305 |
........................... |
1306 |
|
1307 |
.. note:: This operation is semantically equivalent in Cyclades and OS Compute. |
1308 |
|
1309 |
======================================= ====== ======== ========== |
1310 |
URI Method Cyclades OS Compute |
1311 |
======================================= ====== ======== ========== |
1312 |
``/servers/<server-id>/meta/<key>`` PUT ✔ **✘** |
1313 |
``/servers/<server-id>/metadata/<key>`` PUT **✘** ✔ |
1314 |
======================================= ====== ======== ========== |
1315 |
|
1316 |
* **server-id** is the identifier of the virtual server |
1317 |
* **key** is the key of a matadatum key:value pair |
1318 |
|
1319 |
| |
1320 |
|
1321 |
============== ========================= |
1322 |
Request Header Value |
1323 |
============== ========================= |
1324 |
X-Auth-Token User authentication token |
1325 |
============== ========================= |
1326 |
|
1327 |
| |
1328 |
|
1329 |
Request body should contain a ``key``:``value`` pair under a ``meta`` tag. |
1330 |
The ``value`` is the (new) value to set. The ``key`` of the metadatum may or |
1331 |
may not exist prior to the operation. For example, request with ``role`` as a |
1332 |
``key`` may contain the following request body:: |
1333 |
|
1334 |
{'meta': {'role': 'gateway'}} |
1335 |
|
1336 |
| |
1337 |
|
1338 |
=========================== ===================== |
1339 |
Return Code Description |
1340 |
=========================== ===================== |
1341 |
201 (OK) Request succeeded |
1342 |
400 (Bad Request) Invalid server ID or Malformed request |
1343 |
401 (Unauthorized) Missing or expired user token |
1344 |
403 (Forbidden) Administratively suspended server |
1345 |
404 (Not Found) Metadatum key not found |
1346 |
413 (OverLimit) Maximum number of metadata exceeded |
1347 |
500 (Internal Server Error) The request cannot be completed because of an |
1348 |
\ internal error |
1349 |
503 (Service Unavailable) The server is not currently available |
1350 |
=========================== ===================== |
1351 |
|
1352 |
| |
1353 |
|
1354 |
If the response code is 201, the response body contains the ``key:pair`` |
1355 |
that has just been created or updated, under a ``meta`` tag, so that the body |
1356 |
of the response is identical to the body of the request. |
1357 |
|
1358 |
Delete Server Metadatum |
1359 |
....................... |
1360 |
|
1361 |
.. note:: This operation is semantically equivalent in Cyclades and OS Compute. |
1362 |
|
1363 |
======================================= ====== ======== ========== |
1364 |
URI Method Cyclades OS Compute |
1365 |
======================================= ====== ======== ========== |
1366 |
``/servers/<server-id>/meta/<key>`` DELETE ✔ **✘** |
1367 |
``/servers/<server-id>/metadata/<key>`` DELETE **✘** ✔ |
1368 |
======================================= ====== ======== ========== |
1369 |
|
1370 |
* **server-id** is the identifier of the virtual server |
1371 |
* **key** is the key of a matadatum key:value pair |
1372 |
|
1373 |
| |
1374 |
|
1375 |
============== ========================= |
1376 |
Request Header Value |
1377 |
============== ========================= |
1378 |
X-Auth-Token User authentication token |
1379 |
============== ========================= |
1380 |
|
1381 |
| |
1382 |
|
1383 |
=========================== ===================== |
1384 |
Return Code Description |
1385 |
=========================== ===================== |
1386 |
204 (OK) Request succeeded |
1387 |
400 (Bad Request) Invalid server ID |
1388 |
401 (Unauthorized) Missing or expired user token |
1389 |
403 (Forbidden) Administratively suspended server |
1390 |
404 (Not Found) Metadatum key not found |
1391 |
500 (Internal Server Error) The request cannot be completed because of an |
1392 |
\ internal error |
1393 |
503 (Service Unavailable) The server is not currently available |
1394 |
=========================== ===================== |
1395 |
|
1396 |
|
1397 |
Flavors |
1398 |
------- |
1399 |
|
1400 |
A flavor is an available hardware configuration for a server. Each flavor has a |
1401 |
unique combination of disk space and memory capacity. |
1402 |
|
1403 |
List Flavors |
1404 |
............ |
1405 |
|
1406 |
=================== ====== ======== ========== |
1407 |
URI Method Cyclades OS Compute |
1408 |
=================== ====== ======== ========== |
1409 |
``/flavors`` GET ✔ ✔ |
1410 |
``/flavors/detail`` GET ✔ **✘** |
1411 |
=================== ====== ======== ========== |
1412 |
|
1413 |
The detailed (``/flavors/detail``) listing in Cyclades is semantically similar |
1414 |
to OS Compute regular (``/flavor``) listing. The Cyclades regular listing is |
1415 |
Cyclades specific. |
1416 |
|
1417 |
| |
1418 |
|
1419 |
============== ========================= |
1420 |
Request Header Value |
1421 |
============== ========================= |
1422 |
X-Auth-Token User authentication token |
1423 |
============== ========================= |
1424 |
|
1425 |
| |
1426 |
|
1427 |
================= =============== |
1428 |
Request Parameter Value |
1429 |
================= =============== |
1430 |
json Respond in json |
1431 |
xml Respond in xml |
1432 |
================= =============== |
1433 |
|
1434 |
| |
1435 |
|
1436 |
=========================== ===================== |
1437 |
Return Code Description |
1438 |
=========================== ===================== |
1439 |
200 (OK) Request succeeded |
1440 |
400 (Bad Request) Malformed request |
1441 |
401 (Unauthorized) Missing or expired user token |
1442 |
403 (Forbidden) Forbidden to use this flavor |
1443 |
500 (Internal Server Error) The request cannot be completed because of an |
1444 |
\ internal error |
1445 |
503 (Service Unavailable) The server is not currently available |
1446 |
=========================== ===================== |
1447 |
|
1448 |
| |
1449 |
|
1450 |
If a 200 code is returned, the response body contains a list of flavors, under |
1451 |
a ``value`` tag, which lies under a ``flavors`` tag. Each item contains the |
1452 |
fields described in the `flavor section <#flavor-ref>`_. |
1453 |
|
1454 |
.. note:: In Compute OS API, the ``values`` layer is missing from the response. |
1455 |
|
1456 |
In Cyclades, if detail is not requested, only the ``id`` and ``name`` fields |
1457 |
are returned, e.g.: |
1458 |
|
1459 |
.. code-block:: javascript |
1460 |
|
1461 |
{ |
1462 |
"flavors": { |
1463 |
"values": [ |
1464 |
{ |
1465 |
"id": 1, |
1466 |
"name": "One code", |
1467 |
}, { |
1468 |
"id": 3, |
1469 |
"name": "Four core", |
1470 |
} |
1471 |
] |
1472 |
} |
1473 |
} |
1474 |
|
1475 |
Or in XML: |
1476 |
|
1477 |
.. code-block:: xml |
1478 |
|
1479 |
<?xml version="1.0" encoding="UTF-8"?> |
1480 |
<flavors xmlns="http://docs.openstack.org/compute/api/v1" |
1481 |
xmlns:atom="http://www.w3.org/2005/Atom"> |
1482 |
<flavor id="1" name="One core"/> |
1483 |
<flavor id="3" name="Four core"/> |
1484 |
</flavors> |
1485 |
|
1486 |
A detailed response will contain all the flavor fields, e.g.: |
1487 |
|
1488 |
.. code-block:: javascript |
1489 |
|
1490 |
{ |
1491 |
"flavors": { |
1492 |
"values": [ |
1493 |
{ |
1494 |
"id": 1, |
1495 |
"name": "One core", |
1496 |
"ram": 1024, |
1497 |
"SNF:disk_template": "drbd", |
1498 |
"disk": 20, |
1499 |
"cpu": 1 |
1500 |
}, { |
1501 |
"id": 3, |
1502 |
"name": "Four core", |
1503 |
"ram": 1024, |
1504 |
"SNF:disk_template": "drbd", |
1505 |
"disk": 40, |
1506 |
"cpu": 4 |
1507 |
} |
1508 |
] |
1509 |
} |
1510 |
} |
1511 |
|
1512 |
|
1513 |
Get Flavor Details |
1514 |
.................. |
1515 |
|
1516 |
======================= ====== ======== ========== |
1517 |
URI Method Cyclades OS Compute |
1518 |
======================= ====== ======== ========== |
1519 |
``/flavors/<flavor-id`` GET ✔ ✔ |
1520 |
======================= ====== ======== ========== |
1521 |
|
1522 |
* **flavor-id** is the identifier of the flavor |
1523 |
|
1524 |
| |
1525 |
|
1526 |
============== ========================= |
1527 |
Request Header Value |
1528 |
============== ========================= |
1529 |
X-Auth-Token User authentication token |
1530 |
============== ========================= |
1531 |
|
1532 |
| |
1533 |
|
1534 |
================= =============== |
1535 |
Request Parameter Value |
1536 |
================= =============== |
1537 |
json Respond in json |
1538 |
xml Respond in xml |
1539 |
================= =============== |
1540 |
|
1541 |
| |
1542 |
|
1543 |
=========================== ===================== |
1544 |
Return Code Description |
1545 |
=========================== ===================== |
1546 |
200 (OK) Request succeeded |
1547 |
400 (Bad Request) Malformed flavor ID |
1548 |
401 (Unauthorized) Missing or expired user token |
1549 |
403 (Forbidden) Forbidden to use this flavor |
1550 |
404 (Not Found) Flavor id not founmd |
1551 |
500 (Internal Server Error) The request cannot be completed because of an |
1552 |
\ internal error |
1553 |
503 (Service Unavailable) The server is not currently available |
1554 |
=========================== ===================== |
1555 |
|
1556 |
If the response code is 200, the response body should contain a flavor item, |
1557 |
consisting of the `flavor attributes <flavor-ref>`_ under a ``flavor`` tag. |
1558 |
|
1559 |
An example response in JSON: |
1560 |
|
1561 |
.. code-block:: javascript |
1562 |
|
1563 |
{ |
1564 |
"flavor": { |
1565 |
{ |
1566 |
"id": 1, |
1567 |
"name": "One core", |
1568 |
"ram": 1024, |
1569 |
"SNF:disk_template": "drbd", |
1570 |
"disk": 20, |
1571 |
"cpu": 1 |
1572 |
} |
1573 |
} |
1574 |
} |
1575 |
|
1576 |
or in XML: |
1577 |
|
1578 |
.. code-block:: xml |
1579 |
|
1580 |
<?xml version="1.0" encoding="UTF-8"?> |
1581 |
<flavor xmlns="http://docs.openstack.org/compute/api/v1" |
1582 |
xmlns:atom="http://www.w3.org/2005/Atom" |
1583 |
id="1" name="One core" ram="1024" disk="20" cpu="1" /> |
1584 |
|
1585 |
Images |
1586 |
------ |
1587 |
|
1588 |
|
1589 |
* ``progress`` is always returned. |
1590 |
* ``self`` and ``bookmark`` atom links are not returned. |
1591 |
* **List Images** returns just ``id`` and ``name`` if details are not requested. |
1592 |
* **List Images** can return 304 (even though not explicitly stated) when |
1593 |
``changes-since`` is given. |
1594 |
* **List Images** does not return deleted images when ``changes-since`` is given. |
1595 |
|
1596 |
An image is a collection of files you use to create or rebuild a server. |
1597 |
Synnefo deploymenrs usually provide pre-built OS images, but custom image |
1598 |
creation is also supported. |
1599 |
|
1600 |
|
1601 |
List Images |
1602 |
........... |
1603 |
|
1604 |
=================== ====== ======== ========== |
1605 |
URI Method Cyclades OS Compute |
1606 |
=================== ====== ======== ========== |
1607 |
``/servers`` GET ✔ ✔ |
1608 |
``/servers/detail`` GET ✔ ✔ |
1609 |
=================== ====== ======== ========== |
1610 |
|
1611 |
Both requests return a list of images. The first returns just ``id`` and |
1612 |
``name``, while the second returns full collections of image attributes. |
1613 |
|
1614 |
| |
1615 |
|
1616 |
================= ======================== ======== ========== |
1617 |
Request Parameter Value Cyclades OS Compute |
1618 |
================= ======================== ======== ========== |
1619 |
json Respond in json default **✘** |
1620 |
xml Respond in xml ✔ **✘** |
1621 |
server Server filter **✘** ✔ |
1622 |
name Image name filter **✘** ✔ |
1623 |
status Server status filter **✘** ✔ |
1624 |
changes-since Change timestamp filter ✔ ✔ |
1625 |
marker Last list last ID filter **✘** ✔ |
1626 |
limit Page size filter **✘** ✔ |
1627 |
type Request filter type **✘** ✔ |
1628 |
================= ======================== ======== ========== |
1629 |
|
1630 |
* **json** and **xml** parameters are mutually exclusive. If none supported, the response will be formated in json. |
1631 |
|
1632 |
* **changes-since** must be an ISO8601 date string. In Cyclades it refers to the image ``updated_at`` attribute and it should be a date in the window [- POLL_LIMIT ... now]. POLL_LIMIT default value is 3600 seconds except if it is set otherwise at server side. |
1633 |
|
1634 |
| |
1635 |
|
1636 |
============== ========================= ======== ========== |
1637 |
Request Header Value Cyclades OS Compute |
1638 |
============== ========================= ======== ========== |
1639 |
X-Auth-Token User authentication token required required |
1640 |
============== ========================= ======== ========== |
1641 |
|
1642 |
| |
1643 |
|
1644 |
=========================== ===================== |
1645 |
Return Code Description |
1646 |
=========================== ===================== |
1647 |
200 (OK) Request succeeded |
1648 |
304 (No images since date) Can be returned if ``changes-since`` is given |
1649 |
400 (Bad Request) Invalid or malformed ``changes-since`` parameter |
1650 |
401 (Unauthorized) Missing or expired user token |
1651 |
403 (Forbidden) User is not allowed to perform this operation |
1652 |
500 (Internal Server Error) The request cannot be completed because of an |
1653 |
\ internal error |
1654 |
503 (Service Unavailable) The server is not currently available |
1655 |
=========================== ===================== |
1656 |
|
1657 |
| |
1658 |
In case of a 200 code, the response body contains a list of |
1659 |
`image items <#image-ref>` under the ``images`` tag. |
1660 |
|
1661 |
For example, a JSON image response might like the following: |
1662 |
|
1663 |
.. code-block:: javascript |
1664 |
|
1665 |
{ |
1666 |
"images: { |
1667 |
"values": [ |
1668 |
{ |
1669 |
"status": "ACTIVE", |
1670 |
"updated": "2013-03-02T15:57:03+00:00", |
1671 |
"name": "edx_saas", |
1672 |
"created": "2013-03-02T12:21:00+00:00", |
1673 |
"progress": 100, |
1674 |
"id": "175716...526236", |
1675 |
"metadata": { |
1676 |
"values": { |
1677 |
"partition_table": "msdos", |
1678 |
"osfamily": "linux", |
1679 |
"users": "root saasbook", |
1680 |
"exclude_task_changepassword": "yes", |
1681 |
"os": "ubuntu", |
1682 |
"root_partition": "1", |
1683 |
"description": "Ubuntu 12.04 LTS" |
1684 |
} |
1685 |
} |
1686 |
}, { |
1687 |
"status": "ACTIVE", |
1688 |
"updated": "2013-03-02T15:57:03+00:00", |
1689 |
"name": "edx_saas", |
1690 |
"created": "2013-03-02T12:21:00+00:00", |
1691 |
"progress": 100, |
1692 |
"id": "1357163d...c526206", |
1693 |
"metadata": { |
1694 |
"values": { |
1695 |
"partition_table": "msdos", |
1696 |
"osfamily": "windows", |
1697 |
"users": "Administratior", |
1698 |
"exclude_task_changepassword": "yes", |
1699 |
"os": "WinME", |
1700 |
"root_partition": "1", |
1701 |
"description": "Rerto Windows" |
1702 |
} |
1703 |
} |
1704 |
} |
1705 |
] |
1706 |
} |
1707 |
} |
1708 |
|
1709 |
|
1710 |
The OS Compute API does not include any ``values`` layers in the response. More |
1711 |
details can be found |
1712 |
`here <http://docs.openstack.org/api/openstack-compute/2/content/List_Images-d1e4435.html>`_. |
1713 |
|
1714 |
|
1715 |
Get Image Details |
1716 |
................. |
1717 |
GET images/iid get image_details |
1718 |
|
1719 |
====================== ====== ======== ========== |
1720 |
URI Method Cyclades OS Compute |
1721 |
====================== ====== ======== ========== |
1722 |
``/images/<image-id>`` GET ✔ ✔ |
1723 |
====================== ====== ======== ========== |
1724 |
|
1725 |
* **image-id** is the identifier of the virtual image |
1726 |
|
1727 |
| |
1728 |
|
1729 |
============== ========================= ======== ========== |
1730 |
Request Header Value Cyclades OS Compute |
1731 |
============== ========================= ======== ========== |
1732 |
X-Auth-Token User authentication token required required |
1733 |
============== ========================= ======== ========== |
1734 |
|
1735 |
| |
1736 |
|
1737 |
=========================== ===================== |
1738 |
Return Code Description |
1739 |
=========================== ===================== |
1740 |
200 (OK) Request succeeded |
1741 |
400 (Bad Request) Malformed image id |
1742 |
401 (Unauthorized) Missing or expired user token |
1743 |
403 (Forbidden) Not allowed to use this image |
1744 |
404 (Not Found) Image not found |
1745 |
500 (Internal Server Error) The request cannot be completed because of an |
1746 |
\ internal error |
1747 |
503 (Service Unavailable) No available backends or service currently |
1748 |
\ unavailable |
1749 |
=========================== ===================== |
1750 |
|
1751 |
| |
1752 |
|
1753 |
In case of a 200 response code, the response body container a collection of |
1754 |
`image items <#image-ref>`_ under the ``values`` tag, lying under an ``images`` |
1755 |
tag. |
1756 |
|
1757 |
.. note:: In OS Compute API, the ``values`` layer is missing |
1758 |
|
1759 |
**Example Details for an image with id 6404619d-...-aef57eaff4af, in JSON** |
1760 |
|
1761 |
.. code-block:: javascript |
1762 |
|
1763 |
{ |
1764 |
"image": { |
1765 |
"id": "6404619d-...-aef57eaff4af", |
1766 |
"name": "FreeBSD", |
1767 |
"status": "ACTIVE", |
1768 |
"updated": "2013-04-24T12:06:02+00:00", |
1769 |
"created": "2013-04-24T11:52:16+00:00", |
1770 |
"progress": 100, |
1771 |
"metadata": { |
1772 |
"values": { |
1773 |
"kernel": "9.1 RELEASE", |
1774 |
"osfamily": "freebsd", |
1775 |
"users": "root", |
1776 |
"gui": "No GUI", |
1777 |
"sortorder": "9", |
1778 |
"os": "freebsd", |
1779 |
"root_partition": "2", |
1780 |
"description": "FreeBSD 9" |
1781 |
} |
1782 |
} |
1783 |
} |
1784 |
} |
1785 |
|
1786 |
|
1787 |
Delete Image |
1788 |
............ |
1789 |
|
1790 |
====================== ====== ======== ========= |
1791 |
URI Method Cyclades OS Compute |
1792 |
====================== ====== ======== ========= |
1793 |
``/images/<image id>`` DELETE ✔ ✔ |
1794 |
====================== ====== ======== ========== |
1795 |
|
1796 |
* **image-id** is the identifier of the image |
1797 |
|
1798 |
| |
1799 |
|
1800 |
============== ========================= ======== ========== |
1801 |
Request Header Value Cyclades OS Compute |
1802 |
============== ========================= ======== ========== |
1803 |
X-Auth-Token User authentication token required required |
1804 |
============== ========================= ======== ========== |
1805 |
|
1806 |
| |
1807 |
|
1808 |
=========================== ===================== |
1809 |
Return Code Description |
1810 |
=========================== ===================== |
1811 |
204 (OK) Request succeeded |
1812 |
400 (Bad Request) Invalid request or image id |
1813 |
401 (Unauthorized) Missing or expired user token |
1814 |
404 (Not Found) Image not found |
1815 |
500 (Internal Server Error) The request cannot be completed because of an |
1816 |
\ internal error |
1817 |
503 (Service Unavailable) Action not supported or service currently |
1818 |
\ unavailable |
1819 |
=========================== ===================== |
1820 |
|
1821 |
In case of a 204 code, image status will change from ``ACTIVE`` to ``DELETED`` |
1822 |
|
1823 |
Image Metadata |
1824 |
-------------- |
1825 |
|
1826 |
List metadata |
1827 |
............. |
1828 |
|
1829 |
.. note:: This operation is semantically equivalent in Cyclades and OS Compute. |
1830 |
|
1831 |
=============================== ====== ======== ========== |
1832 |
URI Method Cyclades OS Compute |
1833 |
=============================== ====== ======== ========== |
1834 |
``/images/<image-id>/meta`` GET ✔ **✘** |
1835 |
``/images/<image-id>/metadata`` GET **✘** ✔ |
1836 |
=============================== ====== ======== ========== |
1837 |
|
1838 |
* **image-id** is the identifier of the virtual image |
1839 |
|
1840 |
| |
1841 |
|
1842 |
============== ========================= ======== ========== |
1843 |
Request Header Value Cyclades OS Compute |
1844 |
============== ========================= ======== ========== |
1845 |
X-Auth-Token User authentication token required required |
1846 |
============== ========================= ======== ========== |
1847 |
|
1848 |
| |
1849 |
|
1850 |
=========================== ===================== |
1851 |
Return Code Description |
1852 |
=========================== ===================== |
1853 |
201 (OK) Request succeeded |
1854 |
400 (Bad Request) Invalid image ID or Malformed request |
1855 |
401 (Unauthorized) Missing or expired user token |
1856 |
403 (Forbidden) Administratively suspended server |
1857 |
404 (Not Found) Server not found |
1858 |
409 (Build In Progress) The image is not ready yet |
1859 |
500 (Internal Server Error) The request cannot be completed because of an |
1860 |
\ internal error |
1861 |
503 (Service Unavailable) The server is not currently available |
1862 |
=========================== ===================== |
1863 |
|
1864 |
In case of a 201 response code, the response should contain a JSON encoded list |
1865 |
of ``key``:``value`` pairs, under a 'values' tag which lies under a |
1866 |
``metadata`` tag, e.g.: |
1867 |
|
1868 |
.. code-block:: javascript |
1869 |
|
1870 |
{ |
1871 |
'metadata': { |
1872 |
'values': { |
1873 |
"partition_table": "msdos", |
1874 |
"kernel": "3.2.0", |
1875 |
"osfamily": "linux", |
1876 |
"users": "user", |
1877 |
"gui": "Unity 5", |
1878 |
"sortorder": "3", |
1879 |
"os": "ubuntu", |
1880 |
"root_partition": "1", |
1881 |
"description": "Ubuntu 12 LTS" |
1882 |
} |
1883 |
} |
1884 |
} |
1885 |
|
1886 |
.. note:: In OS Compute API the ``values`` level is missing from the response |
1887 |
|
1888 |
Set / Update Image Metadata |
1889 |
........................... |
1890 |
|
1891 |
In Cyclades API, setting new metadata and updating the values of existing ones |
1892 |
is achieved with the same type of request (POST), while in OS Compute API there |
1893 |
are two separate request types (PUT and POST for |
1894 |
`setting new <http://docs.openstack.org/api/openstack-compute/2/content/Create_or_Replace_Metadata-d1e5358.html>`_ |
1895 |
and |
1896 |
`updating existing <http://docs.openstack.org/api/openstack-compute/2/content/Update_Metadata-d1e5208.html>`_ |
1897 |
metadata, respectively). |
1898 |
|
1899 |
In Cyclades API, metadata keys which are not referred by the operation will |
1900 |
remain intact, while metadata referred by the operation will be overwritten in |
1901 |
case of success. |
1902 |
|
1903 |
=============================== ====== ======== ========== |
1904 |
URI Method Cyclades OS Compute |
1905 |
=============================== ====== ======== ========== |
1906 |
``/images/<image-id>/meta`` POST ✔ **✘** |
1907 |
``/images/<image-id>/metadata`` PUT **✘** ✔ |
1908 |
``/images/<image-id>/metadata`` POST **✘** ✔ |
1909 |
=============================== ====== ======== ========== |
1910 |
|
1911 |
* **image-id** is the identifier of the virtual image |
1912 |
|
1913 |
| |
1914 |
|
1915 |
============== ========================= ======== ========== |
1916 |
Request Header Value Cyclades OS Compute |
1917 |
============== ========================= ======== ========== |
1918 |
X-Auth-Token User authentication token required required |
1919 |
============== ========================= ======== ========== |
1920 |
|
1921 |
| |
1922 |
|
1923 |
The request body should contain a JSON-formated set of ``key``:``value`` pairs, |
1924 |
under the ``metadata`` tag, e.g.:: |
1925 |
|
1926 |
{'metadata': {'XtraSoftware': 'XampleSoft', 'os': 'Xubuntu'}} |
1927 |
|
1928 |
| |
1929 |
|
1930 |
=========================== ===================== |
1931 |
Return Code Description |
1932 |
=========================== ===================== |
1933 |
201 (OK) Request succeeded |
1934 |
400 (Bad Request) Malformed request or image id |
1935 |
401 (Unauthorized) Missing or expired user token |
1936 |
403 (Forbidden) Not allowed to modify this image |
1937 |
404 (Not Found) Image or metadatum key not found |
1938 |
413 (OverLimit) Maximum number of metadata exceeded |
1939 |
500 (Internal Server Error) The request cannot be completed because of an |
1940 |
\ internal error |
1941 |
503 (Service Unavailable) The server is not currently available |
1942 |
=========================== ===================== |
1943 |
|
1944 |
| |
1945 |
|
1946 |
In case of a 201 code, the response body should present the new state of |
1947 |
servers metadata. E.g.:: |
1948 |
|
1949 |
{ |
1950 |
'metadata': { |
1951 |
"partition_table": "msdos", |
1952 |
"kernel": "3.2.0", |
1953 |
"osfamily": "linux", |
1954 |
"users": "user", |
1955 |
"gui": "Unity 5", |
1956 |
"sortorder": "3", |
1957 |
"os": "Xubuntu", |
1958 |
"root_partition": "1", |
1959 |
"description": "Ubuntu 12 LTS", |
1960 |
"XtraSoftware": "XampleSoft" |
1961 |
} |
1962 |
} |
1963 |
|
1964 |
Get Metadata Item |
1965 |
................. |
1966 |
|
1967 |
.. note:: This operation is semantically equivalent in Cyclades and OS Compute. |
1968 |
|
1969 |
===================================== ====== ======== ========== |
1970 |
URI Method Cyclades OS Compute |
1971 |
===================================== ====== ======== ========== |
1972 |
``/image/<image-id>/meta/<key>`` GET ✔ **✘** |
1973 |
``/images/<image-id>/metadata/<key>`` GET **✘** ✔ |
1974 |
===================================== ====== ======== ========== |
1975 |
|
1976 |
* **image-id** is the identifier of the virtual image |
1977 |
* **key** is the key of a matadatum ``key``:``value`` pair |
1978 |
|
1979 |
| |
1980 |
|
1981 |
============== ========================= ======== ========== |
1982 |
Request Header Value Cyclades OS Compute |
1983 |
============== ========================= ======== ========== |
1984 |
X-Auth-Token User authentication token required required |
1985 |
============== ========================= ======== ========== |
1986 |
|
1987 |
| |
1988 |
|
1989 |
=========================== ===================== |
1990 |
Return Code Description |
1991 |
=========================== ===================== |
1992 |
200 (OK) Request succeeded |
1993 |
400 (Bad Request) Malformed request or image id |
1994 |
401 (Unauthorized) Missing or expired user token |
1995 |
403 (Forbidden) Not allowed to access this information |
1996 |
404 (Not Found) Metadatum key not found |
1997 |
500 (Internal Server Error) The request cannot be completed because of an |
1998 |
\ internal error |
1999 |
503 (Service Unavailable) The server is not currently available |
2000 |
=========================== ===================== |
2001 |
|
2002 |
If the response code is 200, the response body contains the requested |
2003 |
``key``:``value`` pair under a ``metadata`` tag. For example, if key was |
2004 |
``os``, the response body would look similar to this:: |
2005 |
|
2006 |
{'metadata': {'os': 'Xubuntu'}} |
2007 |
|
2008 |
.. note:: In OS Compute response, ``metadata`` is ``meta`` |
2009 |
|
2010 |
Set / Update Metadatum Item |
2011 |
........................... |
2012 |
|
2013 |
.. note:: This operation is semantically equivalent in Cyclades and OS Compute. |
2014 |
|
2015 |
===================================== ====== ======== ========== |
2016 |
URI Method Cyclades OS Compute |
2017 |
===================================== ====== ======== ========== |
2018 |
``/images/<image-id>/meta/<key>`` PUT ✔ **✘** |
2019 |
``/images/<image-id>/metadata/<key>`` PUT **✘** ✔ |
2020 |
===================================== ====== ======== ========== |
2021 |
|
2022 |
* **image-id** is the identifier of the image |
2023 |
* **key** is the key of a matadatum ``key``:``value`` pair |
2024 |
|
2025 |
| |
2026 |
|
2027 |
============== ========================= ======== ========== |
2028 |
Request Header Value Cyclades OS Compute |
2029 |
============== ========================= ======== ========== |
2030 |
X-Auth-Token User authentication token required required |
2031 |
============== ========================= ======== ========== |
2032 |
|
2033 |
| |
2034 |
|
2035 |
Request body should contain a ``key``:``value`` pair under a ``meta`` tag. The |
2036 |
``value`` is the (new) value to set. The ``key`` of the metadatum may or may |
2037 |
not exist prior to the operation. For example, request with ``os`` as a |
2038 |
``key`` may contain the following request body:: |
2039 |
|
2040 |
{'meta': {'os': 'Kubuntu'}} |
2041 |
|
2042 |
| |
2043 |
|
2044 |
=========================== ===================== |
2045 |
Return Code Description |
2046 |
=========================== ===================== |
2047 |
201 (OK) Request succeeded |
2048 |
400 (Bad Request) Malformed request or image id |
2049 |
401 (Unauthorized) Missing or expired user token |
2050 |
403 (Forbidden) Not allowed to modify this image |
2051 |
404 (Not Found) Metadatum key not found |
2052 |
413 (OverLimit) Maximum number of metadata exceeded |
2053 |
500 (Internal Server Error) The request cannot be completed because of an |
2054 |
\ internal error |
2055 |
503 (Service Unavailable) The server is not currently available |
2056 |
=========================== ===================== |
2057 |
|
2058 |
| |
2059 |
|
2060 |
If the response code is 201, the response body contains the ``key:pair`` |
2061 |
that has just been created or updated, under a ``meta`` tag, so that the body |
2062 |
of the response is identical to the body of the request. |
2063 |
|
2064 |
Delete Image Metadata |
2065 |
..................... |
2066 |
|
2067 |
.. note:: This operation is semantically equivalent in Cyclades and OS Compute. |
2068 |
|
2069 |
===================================== ====== ======== ========== |
2070 |
URI Method Cyclades OS Compute |
2071 |
===================================== ====== ======== ========== |
2072 |
``/images/<image-id>/meta/<key>`` DELETE ✔ **✘** |
2073 |
``/images/<image-id>/metadata/<key>`` DELETE **✘** ✔ |
2074 |
===================================== ====== ======== ========== |
2075 |
|
2076 |
* **image-id** is the identifier of the image |
2077 |
* **key** is the key of a matadatum ``key``:``value`` pair |
2078 |
|
2079 |
| |
2080 |
|
2081 |
============== ========================= |
2082 |
Request Header Value |
2083 |
============== ========================= |
2084 |
X-Auth-Token User authentication token |
2085 |
============== ========================= |
2086 |
|
2087 |
| |
2088 |
|
2089 |
=========================== ===================== |
2090 |
Return Code Description |
2091 |
=========================== ===================== |
2092 |
204 (OK) Request succeeded |
2093 |
400 (Bad Request) Malformed image ID |
2094 |
401 (Unauthorized) Missing or expired user token |
2095 |
403 (Forbidden) Not allowed to modify this image |
2096 |
404 (Not Found) Metadatum key not found |
2097 |
500 (Internal Server Error) The request cannot be completed because of an |
2098 |
\ internal error |
2099 |
503 (Service Unavailable) The server is not currently available |
2100 |
=========================== ===================== |
2101 |
|
2102 |
|
2103 |
Networks |
2104 |
-------- |
2105 |
|
2106 |
============= ======== ========== |
2107 |
BASE URI Cyclades OS Compute |
2108 |
============= ======== ========== |
2109 |
``/networks`` ✔ **✘** |
2110 |
============= ======== ========== |
2111 |
|
2112 |
The Network part of Cyclades API is not supported by the OS Compute API, |
2113 |
although it shares some similaritied with the |
2114 |
`OS Quantum API <http://docs.openstack.org/api/openstack-network/1.0/content/API_Operations.html>`_. |
2115 |
There are key differences in the design of the two systems, which exceed the |
2116 |
scope of this document, although they affect the respective APIs. |
2117 |
|
2118 |
A Server can connect to one or more networks identified by a numeric id. |
2119 |
Networks are accessible only by the users who created them. When a network is |
2120 |
deleted, all connections to it are deleted. |
2121 |
|
2122 |
There is a special **public** network with the id *public* that can be accessed |
2123 |
at */networks/public*. All servers are connected to **public** by default and |
2124 |
this network can not be deleted or modified in any way. |
2125 |
|
2126 |
List Networks |
2127 |
............. |
2128 |
|
2129 |
This operation lists the networks associated with a users account |
2130 |
|
2131 |
==================== ====== |
2132 |
URI Method |
2133 |
==================== ====== |
2134 |
``/networks`` GET |
2135 |
``/networks/detail`` GET |
2136 |
==================== ====== |
2137 |
|
2138 |
| |
2139 |
|
2140 |
============== ========================= |
2141 |
Request Header Value |
2142 |
============== ========================= |
2143 |
X-Auth-Token User authentication token |
2144 |
============== ========================= |
2145 |
|
2146 |
| |
2147 |
|
2148 |
=========================== ===================== |
2149 |
Return Code Description |
2150 |
=========================== ===================== |
2151 |
204 (OK) Request succeeded |
2152 |
304 (Not Modified) |
2153 |
400 (Bad Request) Malformed network id |
2154 |
401 (Unauthorized) Missing or expired user token |
2155 |
404 (Not Found) Network not found |
2156 |
409 (Build In Progress) Server is not ready yet |
2157 |
500 (Internal Server Error) The request cannot be completed because of an |
2158 |
\ internal error |
2159 |
503 (Service Unavailable) Action not supported or service currently |
2160 |
\ unavailable |
2161 |
=========================== ===================== |
2162 |
|
2163 |
The ``detail`` operation lists the `full network attributes <#network-ref>`_, |
2164 |
while the regular operation returns only the ``network id`` and the |
2165 |
``network name``. |
2166 |
|
2167 |
**Example Networks List Response: JSON (regular)**: |
2168 |
|
2169 |
.. code-block:: javascript |
2170 |
|
2171 |
{ |
2172 |
"networks": { |
2173 |
"values": [ |
2174 |
{"id": "1". "name": "public"}, |
2175 |
{"id": "2". "name": "my private network"} |
2176 |
] |
2177 |
} |
2178 |
} |
2179 |
|
2180 |
**Example Networks List Response: JSON (detail)**: |
2181 |
|
2182 |
.. code-block:: javascript |
2183 |
|
2184 |
{ |
2185 |
"networks": { |
2186 |
"values": [ |
2187 |
{ |
2188 |
"id": "1", |
2189 |
"name": "public", |
2190 |
"created": "2011-04-20T15:31:08.199640+00:00", |
2191 |
"updated": "2011-05-06T12:47:05.582679+00:00", |
2192 |
"attachments": {"values": ["nic-42-0", "nic-73-0"]} |
2193 |
}, { |
2194 |
"id": 2, |
2195 |
"name": "my private network", |
2196 |
"created": "2011-04-20T14:32:08.199640+00:00", |
2197 |
"updated": "2011-05-06T11:40:05.582679+00:00", |
2198 |
"attachments": {"values": ["nic-42-2", "nic-7-3"]} |
2199 |
} |
2200 |
] |
2201 |
} |
2202 |
} |
2203 |
|
2204 |
|
2205 |
Create Network |
2206 |
.............. |
2207 |
|
2208 |
This operation creates a new network |
2209 |
|
2210 |
==================== ====== |
2211 |
URI Method |
2212 |
==================== ====== |
2213 |
``/networks`` POST |
2214 |
==================== ====== |
2215 |
|
2216 |
| |
2217 |
|
2218 |
============== ========================= |
2219 |
Request Header Value |
2220 |
============== ========================= |
2221 |
X-Auth-Token User authentication token |
2222 |
============== ========================= |
2223 |
|
2224 |
| |
2225 |
|
2226 |
The request body is json-formated and contains a collection of attributes under |
2227 |
the ``network`` tag, which are presented bellow: |
2228 |
|
2229 |
================== ======================= ======== ======= |
2230 |
Request Attributes Description Required Default |
2231 |
================== ======================= ======== ======= |
2232 |
name Network name ✔ |
2233 |
type Network type ✔ |
2234 |
dhcp If use DHCP **✘** True |
2235 |
cidr IPv4 CIDR **✘** 192.168.1.0/2 |
2236 |
cidr6 IPv6 CDIR **✘** null |
2237 |
gateway IPv4 gateway address **✘** null |
2238 |
gateway6 IPv6 gateway address **✘** null |
2239 |
public If a public network **✘** False |
2240 |
================== ======================= ======== ======= |
2241 |
|
2242 |
* **name** is a string |
2243 |
|
2244 |
* **type** can be CUSTOM, IP_LESS_ROUTED, MAC_FILTERED, PHYSICAL_VLAN |
2245 |
|
2246 |
* **dhcp** and **public** are flags |
2247 |
|
2248 |
* **cidr**, and **gateway** are IPv4 addresses |
2249 |
|
2250 |
* **cidr6**, and **gateway6** are IPv6 addresses |
2251 |
|
2252 |
* **public** should better not be used. If True, a 403 is returned. |
2253 |
|
2254 |
**Example Create Network Request Body: JSON**: |
2255 |
|
2256 |
.. code-block:: javascript |
2257 |
|
2258 |
{ |
2259 |
"network": {"name": "private_net", "type": "MAC_FILTERED"} |
2260 |
} |
2261 |
|
2262 |
| |
2263 |
|
2264 |
=========================== ===================== |
2265 |
Return Code Description |
2266 |
=========================== ===================== |
2267 |
202 (OK) Request succeeded |
2268 |
400 (Bad Request) Malformed network id or request |
2269 |
401 (Unauthorized) Missing or expired user token |
2270 |
403 (Forbidden) Public network is forbidden |
2271 |
404 (Not Found) Network not found |
2272 |
413 (Over Limit) Reached networks limit |
2273 |
415 (Bad Media Type) Bad network type |
2274 |
500 (Internal Server Error) The request cannot be completed because of an |
2275 |
\ internal error |
2276 |
503 (Service Unavailable) Failed to allocated network resources |
2277 |
=========================== ===================== |
2278 |
|
2279 |
In case of a 202 code, the operation asynchronously provisions a new private |
2280 |
network and the response body consists of a collection of |
2281 |
`network attributes <#network-red>`_. |
2282 |
|
2283 |
**Example Create Network Response: JSON**: |
2284 |
|
2285 |
.. code-block:: javascript |
2286 |
|
2287 |
{ |
2288 |
"network": { |
2289 |
"status": "PENDING", |
2290 |
"updated": "2013-04-25T13:31:17.165237+00:00", |
2291 |
"name": "my private network", |
2292 |
"created": "2013-04-25T13:31:17.165088+00:00", |
2293 |
"cidr6": null, |
2294 |
"id": "6567", |
2295 |
"gateway6": null, |
2296 |
"public": false, |
2297 |
"dhcp": false, |
2298 |
"cidr": "192.168.1.0/24", |
2299 |
"type": "MAC_FILTERED", |
2300 |
"gateway": null, |
2301 |
"attachments": {"values": []} |
2302 |
} |
2303 |
} |
2304 |
|
2305 |
|
2306 |
Get Network Details |
2307 |
................... |
2308 |
|
2309 |
========================== ====== |
2310 |
URI Method |
2311 |
========================== ====== |
2312 |
``/networks/<network-id>`` GET |
2313 |
========================== ====== |
2314 |
|
2315 |
* **network-id** is the identifier of the network |
2316 |
|
2317 |
| |
2318 |
|
2319 |
============== ========================= |
2320 |
Request Header Value |
2321 |
============== ========================= |
2322 |
X-Auth-Token User authentication token |
2323 |
============== ========================= |
2324 |
|
2325 |
| |
2326 |
|
2327 |
=========================== ===================== |
2328 |
Return Code Description |
2329 |
=========================== ===================== |
2330 |
200 (OK) Request succeeded |
2331 |
400 (Bad Request) Malformed request or network id |
2332 |
401 (Unauthorized) Missing or expired user token |
2333 |
404 (Not Found) Network not found |
2334 |
500 (Internal Server Error) The request cannot be completed because of an |
2335 |
\ internal error |
2336 |
503 (Service Unavailable) The service is not currently available |
2337 |
=========================== ===================== |
2338 |
|
2339 |
| |
2340 |
|
2341 |
In case of a 200 code, the response body consists of a collection of |
2342 |
`network attributes <#network-ref>`_. |
2343 |
|
2344 |
**Example Get Network Details Response: JSON**: |
2345 |
|
2346 |
.. code-block:: javascript |
2347 |
|
2348 |
{ |
2349 |
"network": { |
2350 |
"status": "PENDING", |
2351 |
"updated": "2013-04-25T13:31:17.165237+00:00", |
2352 |
"name": "my private network", |
2353 |
"created": "2013-04-25T13:31:17.165088+00:00", |
2354 |
"cidr6": null, |
2355 |
"id": "6567", |
2356 |
"gateway6": null, |
2357 |
"public": false, |
2358 |
"dhcp": false, |
2359 |
"cidr": "192.168.1.0/24", |
2360 |
"type": "MAC_FILTERED", |
2361 |
"gateway": null, |
2362 |
"attachments": {"values": []} |
2363 |
} |
2364 |
} |
2365 |
|
2366 |
Rename Network |
2367 |
.............. |
2368 |
|
2369 |
========================== ====== |
2370 |
URI Method |
2371 |
========================== ====== |
2372 |
``/networks/<network-id>`` PUT |
2373 |
========================== ====== |
2374 |
|
2375 |
* **network-id** is the identifier of the network |
2376 |
|
2377 |
| |
2378 |
|
2379 |
============== ========================= |
2380 |
Request Header Value |
2381 |
============== ========================= |
2382 |
X-Auth-Token User authentication token |
2383 |
============== ========================= |
2384 |
|
2385 |
| |
2386 |
|
2387 |
The request body is json-formated and contains a ``network`` tab over the |
2388 |
following attribute: |
2389 |
|
2390 |
================== ================ |
2391 |
Request Parameters Description |
2392 |
================== ================ |
2393 |
name New network name |
2394 |
================== ================ |
2395 |
|
2396 |
**Example Update Network Name Request: JSON**: |
2397 |
|
2398 |
.. code-block:: javascript |
2399 |
|
2400 |
{"network": {"name": "new_name"}} |
2401 |
|
2402 |
| |
2403 |
|
2404 |
=========================== ===================== |
2405 |
Return Code Description |
2406 |
=========================== ===================== |
2407 |
204 (OK) Request succeeded |
2408 |
400 (Bad Request) Malformed request or network deleted |
2409 |
401 (Unauthorized) Missing or expired user token |
2410 |
403 (Forbidden) Administratively suspended server |
2411 |
404 (Not Found) Network not found |
2412 |
413 (Over Limit) Network Limit Exceeded |
2413 |
415 (Bad Media Type) Bad network type |
2414 |
500 (Internal Server Error) The request cannot be completed because of an |
2415 |
\ internal error |
2416 |
503 (Service Unavailable) The service is not currently available |
2417 |
=========================== ===================== |
2418 |
|
2419 |
In case of a 200 response code, the ``name`` of the network is changed to the |
2420 |
new value. |
2421 |
|
2422 |
Delete Network |
2423 |
.............. |
2424 |
|
2425 |
========================== ====== |
2426 |
URI Method |
2427 |
========================== ====== |
2428 |
``/networks/<network-id>`` DELETE |
2429 |
========================== ====== |
2430 |
|
2431 |
* **network-id** is the identifier of the network |
2432 |
|
2433 |
| |
2434 |
|
2435 |
============== ========================= |
2436 |
Request Header Value |
2437 |
============== ========================= |
2438 |
X-Auth-Token User authentication token |
2439 |
============== ========================= |
2440 |
|
2441 |
| |
2442 |
|
2443 |
=========================== ===================== |
2444 |
Return Code Description |
2445 |
=========================== ===================== |
2446 |
204 (OK) Request succeeded |
2447 |
400 (Bad Request) Malformed request or network already deleted |
2448 |
401 (Unauthorized) Missing or expired user token |
2449 |
403 (Forbidden) Administratively suspended server |
2450 |
404 (Not Found) Network not found |
2451 |
500 (Internal Server Error) The request cannot be completed because of an |
2452 |
\ internal error |
2453 |
503 (Service Unavailable) The service is not currently available |
2454 |
=========================== ===================== |
2455 |
|
2456 |
Add / Remove Server |
2457 |
................... |
2458 |
|
2459 |
================================= ====== |
2460 |
URI Method |
2461 |
================================= ====== |
2462 |
``/networks/<network-id>/action`` POST |
2463 |
================================= ====== |
2464 |
|
2465 |
* **network-id** is the identifier of the network |
2466 |
|
2467 |
| |
2468 |
|
2469 |
============== ========================= |
2470 |
Request Header Value |
2471 |
============== ========================= |
2472 |
X-Auth-Token User authentication token |
2473 |
============== ========================= |
2474 |
|
2475 |
| |
2476 |
|
2477 |
The json-formated request body should be an ``add`` **or** ``remove`` tag over |
2478 |
the following attribute: |
2479 |
|
2480 |
================== ================================= |
2481 |
Request Paramenter Description |
2482 |
================== ================================= |
2483 |
serverRef Server id to (dis)connect from/to |
2484 |
================== ================================= |
2485 |
|
2486 |
**Example Action Add: JSON**: |
2487 |
|
2488 |
.. code-block:: javascript |
2489 |
|
2490 |
{"add" : {"serverRef" : 42}} |
2491 |
|
2492 |
**Example Action Remove: JSON**: |
2493 |
|
2494 |
.. code-block:: javascript |
2495 |
|
2496 |
{"remove" : {"serverRef" : 42}} |
2497 |
|
2498 |
| |
2499 |
|
2500 |
=========================== ===================== |
2501 |
Return Code Description |
2502 |
=========================== ===================== |
2503 |
204 (OK) Request succeeded |
2504 |
400 (Bad Request) Malformed request or network already deleted |
2505 |
401 (Unauthorized) Missing or expired user token |
2506 |
403 (Forbidden) Not allowed to modify this network (e.g. public) |
2507 |
404 (Not Found) Network not found |
2508 |
500 (Internal Server Error) The request cannot be completed because of an |
2509 |
\ internal error |
2510 |
503 (Service Unavailable) The service is not currently available |
2511 |
=========================== ===================== |
2512 |
|
2513 |
In case of 204 code, the server is connected to (``add``) or disconnected from |
2514 |
(``remove``) the network. |
2515 |
|
2516 |
Index of Attributes |
2517 |
------------------- |
2518 |
|
2519 |
.. _server-ref: |
2520 |
|
2521 |
Server Attributes |
2522 |
................. |
2523 |
|
2524 |
================ ========================== ======== ========== |
2525 |
Server attribute Description Cyclades OS Compute |
2526 |
================ ========================== ======== ========== |
2527 |
id Server ID ✔ ✔ |
2528 |
name Server Name ✔ ✔ |
2529 |
status Server Status ✔ ✔ |
2530 |
updated Date of last modification ✔ ✔ |
2531 |
created Date of creation ✔ ✔ |
2532 |
hostId Physical host empty ✔ |
2533 |
imageRef Image ID ✔ **✘** |
2534 |
image A full image descreption **✘** ✔ |
2535 |
flavorRef Flavor ID ✔ **✘** |
2536 |
flavor A full flavor description **✘** ✔ |
2537 |
adminPass Superuser Password ✔ ✔ |
2538 |
suspended If server is suspended ✔ ✔ |
2539 |
progress Build progress ✔ ✔ |
2540 |
metadata Custom server metadata ✔ ✔ |
2541 |
user_id Server owner **✘** ✔ |
2542 |
tenant_id Server tenant **✘** ✔ |
2543 |
accessIPv4 Server IPV4 net address **✘** ✔ |
2544 |
accessIPv6 Server IPV4 net address **✘** ✔ |
2545 |
addresses Nets connected on server **✘** ✔ |
2546 |
links Server links **✘** ✔ |
2547 |
================ ========================== ======== ========== |
2548 |
|
2549 |
* **status** values are described `here <#status-ref>`_ |
2550 |
|
2551 |
* **updated** and **created** are date-formated |
2552 |
|
2553 |
* **hostId** is always empty in Cyclades and is returned for compatibility reasons |
2554 |
|
2555 |
* **imageRef** and **flavorRef** always refer to existing Image and Flavor specifications. Cyclades improved the OpenStack approach by using references to Image and Flavor attributes, instead of listing their full properties |
2556 |
|
2557 |
* **adminPass** in Cyclades it is generated automatically during creation. For safety, it is not stored anywhere in the system and it cannot be recovered with a query request |
2558 |
|
2559 |
* **suspended** is True only of the server is suspended by the cloud administrations or policy |
2560 |
|
2561 |
* **progress** is a number between 0 and 100 and reflects the server building status |
2562 |
|
2563 |
* **metadata** are custom key:value pairs refering to the VM. In Cyclades, the ``OS`` and ``users`` metadata are automatically retrieved from the servers image during creation |
2564 |
|
2565 |
.. _status-ref: |
2566 |
|
2567 |
Server Status |
2568 |
............. |
2569 |
|
2570 |
============= ==================== ======== ========== |
2571 |
Status Description Cyclades OS Compute |
2572 |
============= ==================== ======== ========== |
2573 |
BUILD Building ✔ ✔ |
2574 |
ACTIVE Up and running ✔ ✔ |
2575 |
STOPPED Shut down ✔ **✘** |
2576 |
REBOOT Rebooting ✔ ✔ |
2577 |
DELETED Removed ✔ ✔ |
2578 |
UNKNOWN Unexpected error ✔ ✔ |
2579 |
ERROR In error ✔ ✔ |
2580 |
HARD_REBOOT Hard rebooting **✘** ✔ |
2581 |
PASSWORD Resetting password **✘** ✔ |
2582 |
REBUILD Rebuilding server **✘** ✔ |
2583 |
RESCUE In rescue mode **✘** ✔ |
2584 |
RESIZE Resizing **✘** ✔ |
2585 |
REVERT_RESIZE Failed to resize **✘** ✔ |
2586 |
SHUTOFF Shut down by user **✘** ✔ |
2587 |
SUSPENDED Suspended **✘** ✔ |
2588 |
VERIFY_RESIZE Waiting confirmation **✘** ✔ |
2589 |
============= ==================== ======== ========== |
2590 |
|
2591 |
.. _network-ref |
2592 |
|
2593 |
Network |
2594 |
....... |
2595 |
|
2596 |
.. note:: Networks are features in Cyclades API but not in OS Compute API |
2597 |
|
2598 |
================== =========== |
2599 |
Network Attributes Description |
2600 |
================== =========== |
2601 |
id Network identifier |
2602 |
name Network name |
2603 |
created Date of creation |
2604 |
updates Date of last update |
2605 |
cidr IPv4 CIDR Address |
2606 |
cidr6 IPv6 CIDR Address |
2607 |
dhcp IPv4 DHCP Address |
2608 |
dhcp6 IPv6 DHCP Address |
2609 |
gateway IPv4 Gateway Address |
2610 |
gateway6 IPv6 Gateway Address |
2611 |
public If the network is public |
2612 |
status Network status |
2613 |
attachments Network Interface Connections (NICs) |
2614 |
================== =========== |
2615 |
|
2616 |
* **id** and **name** are int and string respectively |
2617 |
|
2618 |
* **created** and **updated** are ISO8061 date strings |
2619 |
|
2620 |
* **public** is a boolean flag |
2621 |
|
2622 |
* **status** can be PENDING, ACTIVE or DELETED |
2623 |
|
2624 |
* **attachments** refers to the NICs connecting servers on that network. |
2625 |
|
2626 |
.. _nic-ref: |
2627 |
|
2628 |
Network Interface Connection (NIC) |
2629 |
.................................. |
2630 |
|
2631 |
A Network Interface Connection (NIC) represents a servers connection to a network. |
2632 |
|
2633 |
A NIC is identified by a server and an (obviously unique) mac address. A server can have multiple NICs, though. In practice, a NIC id is used of reference and identification. |
2634 |
|
2635 |
Each NIC is used to connect a specific server to a network. The network is aware of that connection for as long as it holds. If a NIC is disconnected from a network, it is destroyed. |
2636 |
|
2637 |
A NIC specification contains the following information: |
2638 |
|
2639 |
================= ====================== ======== ========== |
2640 |
Server Attributes Description Cyclades OS Compute |
2641 |
================= ====================== ======== ========== |
2642 |
id The NIC id ✔ **✘** |
2643 |
mac_address NIC's mac address ✔ **✘** |
2644 |
network_id Network of connection ✔ **✘** |
2645 |
firewallProfile The firewall profile ✔ **✘** |
2646 |
ipv4 IP v4 address ✔ **✘** |
2647 |
ipv6 IP v6 address ✔ **✘** |
2648 |
================= ====================== ======== ========== |
2649 |
|
2650 |
* **id** is the unique identified of the NIC. It consists of the server id and an ordinal number nic-<server-id>-<ordinal number> , e.g. for a server with id 42:: |
2651 |
nic-42-0, nic-42-1, ... |
2652 |
|
2653 |
* **mac_address** is the unique mac address of the interface |
2654 |
|
2655 |
* **network_id** is the id of the network this nic connects to. |
2656 |
|
2657 |
* **firewallProfile** , if set, refers to the mode of the firewall. Valid firewall profile values:: |
2658 |
|
2659 |
ENABLED, DISABLED, PROTECTED |
2660 |
|
2661 |
* **ipv4** and **ipv6** are the IP addresses (versions 4 and 6 respectively) of the specific network connection for that machine. |
2662 |
|
2663 |
.. _flavor-ref: |
2664 |
|
2665 |
Flavor |
2666 |
...... |
2667 |
|
2668 |
A flavor is a hardware configuration for a server. It contains the following |
2669 |
information: |
2670 |
|
2671 |
================= ==================== ======== ========== |
2672 |
Flavor Attributes Description Cyclades OS Compute |
2673 |
================= ==================== ======== ========== |
2674 |
id The flavor id ✔ ✔ |
2675 |
name The flavor name ✔ ✔ |
2676 |
ram Server RAM size ✔ ✔ |
2677 |
SNF:disk_template Storage mechanism ✔ **✘** |
2678 |
disk Server disk size ✔ ✔ |
2679 |
cpu # of Virtual CPUs ✔ **✘** |
2680 |
vcpus # of Virtual CPUs **✘** ✔ |
2681 |
links rel Atom link rel field **✘** ✔ |
2682 |
links href Atom link href field **✘** ✔ |
2683 |
================= ==================== ======== ========== |
2684 |
|
2685 |
* **id** is the flavor unique id (a possitive integer) |
2686 |
|
2687 |
* **name** is the flavor name (a string) |
2688 |
|
2689 |
* **ram** is the server RAM size in MB |
2690 |
|
2691 |
* **SNF:disk_template** is a reference to the underlying storage mechanism used |
2692 |
by the Cyclades server. It is Cyclades specific. |
2693 |
|
2694 |
* **disk** the servers disk size in GB |
2695 |
|
2696 |
* **cpu** and **vcpus** are semantically equivalent terms in Cyclades and OS Compute APIs respectively and they refer to the number of virtual CPUs assigned |
2697 |
to a server |
2698 |
|
2699 |
* **link ref** and **link href** refer to the Atom link attributes that are |
2700 |
`used in OS Compute API <http://docs.openstack.org/api/openstack-compute/2/content/List_Flavors-d1e4188.html>`_. |
2701 |
|
2702 |
.. _image-ref: |
2703 |
|
2704 |
Image |
2705 |
..... |
2706 |
|
2707 |
An image is a collection of files you use to create or rebuild a server. |
2708 |
|
2709 |
An image item may have the fields presented bellow: |
2710 |
|
2711 |
================= ====================== ======== ========== |
2712 |
Server Attributes Description Cyclades OS Compute |
2713 |
================= ====================== ======== ========== |
2714 |
id Image ID ✔ ✔ |
2715 |
name Image name ✔ ✔ |
2716 |
updated Last update date ✔ ✔ |
2717 |
created Image creation date ✔ ✔ |
2718 |
progress Ready status progress ✔ **✘** |
2719 |
status Image status **✘** ✔ |
2720 |
tenant_id Image creator **✘** ✔ |
2721 |
user_id Image users **✘** ✔ |
2722 |
metadata Custom metadata ✔ ✔ |
2723 |
links Atom links **✘** ✔ |
2724 |
minDisk Minimum required disk **✘** ✔ |
2725 |
minRam Minimum required RAM **✘** ✔ |
2726 |
================= ====================== ======== ========== |
2727 |
|
2728 |
* **id** is the image id and **name** is the image name. They are both strings. |
2729 |
|
2730 |
* **updated** and **created** are both ISO8601 date strings |
2731 |
|
2732 |
* **progress** varies between 0 and 100 and denotes the status of the image |
2733 |
|
2734 |
* **metadata** is a collection of ``key``:``values`` pairs of custom metadata, |
2735 |
under the tag ``values`` which lies under the tag ``metadata``. |
2736 |
|
2737 |
.. note:: in OS Compute, the ``values`` layer is missing |