compute-api-guide.rst 89.1 KB
Newer Older
1
.. _compute-api-guide:
2

3
4
5
API Guide
*********

6
`Cyclades <cyclades.html>`_ is the Compute Service of `Synnefo
7
8
9
<http://www.synnefo.org>`_. The Cyclades/Compute API complies with
`OpenStack Compute <http://docs.openstack.org/api/openstack-compute/2/content>`_
with custom extensions when needed.
10

11
This document's goals are:
12

13
14
* Define the Cyclades/Compute REST API
* Clarify the differences between Cyclades and OpenStack/Compute
15

16
Users and developers who wish to access Cyclades through its REST API are
17
18
advised to use the
`kamaki <http://www.synnefo.org/docs/kamaki/latest/index.html>`_ command-line
19
client and associated python library, instead of making direct calls.
20
21
22
23

Overview
========

24
25
26
27
* OpenStack does not define if requests for invalid URLs should return 404 or a
* Fault. We return a BadRequest Fault.
* OpenStack does not define if requests with a wrong HTTP method should return
* 405 or a Fault. We return a BadRequest Fault.
28
29
30
31
32
33
34

General API Information
=======================

Authentication
--------------

35
36
37
All requests use the same authentication method: an ``X-Auth-Token`` header is
passed to the servive, which is used to authenticate the user and retrieve user
related information. No other user details are passed through HTTP.
38
39
40
41

Efficient Polling with the Changes-Since Parameter
--------------------------------------------------

42
* Effectively limit support of the changes-since parameter in **List Servers**
43
44
  and **List Images**.

45
* Assume that garbage collection of deleted servers will only affect servers
46
47
48
  deleted ``POLL_TIME`` seconds (default: 3600) in the past or earlier. Else
  loose the information of a server getting deleted.

49
* Images do not support a deleted state, so deletions cannot be tracked.
50

51
52
Limitations
-----------
53

54
* Version MIME type and vesionless requests are not currently supported.
55

56
57
* Cyclades only supports JSON Requests and JSON/XML Responses. XML Requests are
  currently not supported.
58

59
* Optional content compression support is currently not supported.
60

61
62
* To prevent abuse, HTTP sessions have a timeout of 20 seconds before being
  closed.
63

64
* Full URI references and ``self`` and ``bookmark`` links are not supported.
65

66
* Pagination is currently not supported.
67

68
69
70
71
72
* Cached responses are currently not supported.

* Limits are currently not supported.

* Extensions are currently not supported.
73
74
75
76
77


API Operations
==============

78
79
80
81
82
83
84
85
86
87
88
89
90
.. rubric:: Servers

================================================== ========================================= ====== ======== ==========
Description                                        URI                                       Method Cyclades OS/Compute
================================================== ========================================= ====== ======== ==========
`List <#list-servers>`_                            ``/servers``                              GET    ✔        ✔
\                                                  ``/servers/detail``                       GET    ✔        ✔
`Create <#create-server>`_                         ``/servers``                              POST   ✔        ✔
`Get Stats <#get-server-stats>`_                   ``/servers/<server-id>/stats``            GET    ✔        **✘**
`Get Diagnostics <#get-server-diagnostics>`_       ``/servers/<server-id>/diagnostics``      GET    ✔        **✘**
`Get Details <#get-server-details>`_               ``/servers/<server id>``                  GET    ✔        ✔
`Rename <#rename-server>`_                         ``/servers/<server id>``                  PUT    ✔        ✔
`Delete <#delete-server>`_                         ``/servers/<server id>``                  DELETE ✔        ✔
91
92
`List Connections <#list-server-connections>`_     ``/servers/<server id>/ips``              GET    ✔        ✔
`Get Connection <#connection-with-network>`_       ``/servers/<server id>/ips/<network id>`` GET    ✔        ✔
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
`List Metadata <#list-server-metadata>`_           ``/servers/<server-id>/metadata``         GET    ✔        ✔
`Update Metadata <#set-update-server-metadata>`_   ``/servers/<server-id>/metadata``         PUT    **✘**    ✔
\                                                  ``/servers/<server-id>/metadata``         POST   ✔        ✔
`Get Meta Item <#get-server-metadata-item>`_       ``/servers/<server-id>/metadata/<key>``   GET    ✔        ✔
`Update Meta Item <#update-server-metadata-item>`_ ``/servers/<server-id>/metadata/<key>``   PUT    ✔        ✔
`Delete Meta Item <#delete-server-metadata>`_      ``/servers/<server-id>/metadata/<key>``   DELETE ✔        ✔
`Actions <#server-actions>`_                       ``servers/<server id>/action``            POST   ✔        ✔
================================================== ========================================= ====== ======== ==========

.. rubric:: Flavors

==================================== ======================== ====== ======== ==========
Description                          URI                      Method Cyclades OS/Compute
==================================== ======================== ====== ======== ==========
`List <#list-flavors>`_              ``/flavors``             GET    ✔        ✔
\                                    ``/flavors/detail``      GET    ✔        **✘**
`Get details <#get-flavor-details>`_ ``/flavors/<flavor-id>`` GET    ✔        ✔
==================================== ======================== ====== ======== ==========

.. rubric:: Images

=========================================== ===================================== ====== ======== ==========
Description                                 URI                                   Method Cyclades OS/Compute
=========================================== ===================================== ====== ======== ==========
`List <#list-images>`_                      ``/images``                           GET    ✔        ✔
\                                           ``/images/detail``                    GET    ✔        ✔
`Get details <#get-image-details>`_         ``/images/<image-id>``                GET    ✔        ✔
`Delete <#delete-image>`_                   ``/images/<image id>``                DELETE ✔        ✔
`List Metadata <#list-image-metadata>`_     ``/images/<image-id>/metadata``       GET    ✔        ✔
`Update Metadata <#update-image-metadata>`_ ``/images/<image-id>/metadata``       POST   ✔        ✔
\                                           ``/images/<image-id>/metadata``       PUT    **✘**    ✔
`Get Meta Item <#get-image-metadata>`_      ``/image/<image-id>/metadata/<key>``  GET    ✔        ✔
`Update Metadata <#update-image-metadata>`_ ``/images/<image-id>/metadata/<key>`` PUT    ✔        ✔
`Delete Metadata <#delete-image-metadata>`_ ``/images/<image-id>/metadata/<key>`` DELETE ✔        ✔
=========================================== ===================================== ====== ======== ==========
128

129
List Servers
130
------------
131

132
133
134
135
List all virtual servers owned by the user.

.. rubric:: Request

136
=================== ====== ======== ==========
137
URI                 Method Cyclades OS/Compute
138
139
=================== ====== ======== ==========
``/servers``        GET    ✔        ✔
Stavros Sachtouris's avatar
Stavros Sachtouris committed
140
``/servers/detail`` GET    ✔        ✔
141
142
=================== ====== ======== ==========

143
144
145
* Both requests return a list of servers. The first returns just ``id``,
  ``name`` and ``links``, while the second returns the full collections of
  server attributes.
146

147
148
|
==============  ========================= ======== ==========
149
Request Header  Value                     Cyclades OS/Compute
150
151
152
153
154
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

|
155
================= =================================== ======== ==========
156
Request Parameter Value                               Cyclades OS/Compute
157
================= =================================== ======== ==========
158
159
json              Respond in json                     default  **✘**
xml               Respond in xml                      ✔        **✘**
160
161
162
163
164
165
166
167
168
changes-since     Servers delete since that timestamp ✔        ✔
image             Image reference                     **✘**    ✔
flavor            VM flavor reference                 **✘**    ✔
server            Server flavor reference             **✘**    ✔
status            Server status                       **✘**    ✔
marker            Last list last ID                   **✘**    ✔
limit             Page size                           **✘**    ✔
================= =================================== ======== ==========

169
170
* **json** and **xml** parameters are mutually exclusive. If none supported,
the response will be formated in json.
171

172
173
* **status** refers to the `server status <#status-ref>`_

174
175
* **changes-since** must be an ISO8601 date string

176
.. rubric:: Response
177
178
179
180
181
182
183
184

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
304 (No servers since date) Can be returned if ``changes-since`` is given
400 (Bad Request)           Invalid or malformed ``changes-since`` parameter
401 (Unauthorized)          Missing or expired user token
185
403 (Forbidden)             User is not allowed to perform this operation
186
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
187
\                           internal error
188
189
190
503 (Service Unavailable)   The server is not currently available
=========================== =====================

191
192
193
|

Response body contents::
194

195
196
197
198
199
200
  servers: [
    {
      <server attribute>: <value>,
      ...
    }, ...
  ]
201

202
The server attributes are listed `here <#server-ref>`_
203
204

*Example List Servers: JSON (regular)*
205
206

.. code-block:: javascript
207

208
209
  GET https://example.org/compute/v2.0/servers

210

211
212
  {
    "servers": [
213
214
      {
        "links": [
215
216
217
218
219
220
221
          {
            "href": "https://example.org/compute/v2.0/servers/42", 
            "rel": "self"
          }, {
            "href": "https://example.org/compute/v2.0/servers/42", 
            "rel": "bookmark"
          }
222
223
224
225
226
        ],
        "id": "42",
        "name": "My Server",
      }, {
        "links": [
227
228
229
230
231
232
233
          {
            "href": "https://example.org/compute/v2.0/servers/43", 
            "rel": "self"
          }, {
            "href": "https://example.org/compute/v2.0/servers/43", 
            "rel": "bookmark"
          }
234
        ],
235
        "id": "84",
236
237
238
        "name": "My Server",
      }
    ]
239
  }
240
241
242

*Example List Servers: JSON (detail)*

243
244
245
  GET https://example.org/compute/v2.0/servers/detail


246
247
.. code-block:: javascript

248
249
  {
    "servers": [
250
      {
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
        "addresses": [
          "2718": [
            {
              "version": 6,
              "addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21ab",
              "OS-EXT-IPS:type": "fixed"
            }
          ],
          "2719": [
            {
              "version": 4,
              "addr": "192.168.1.2",
              "OS-EXT-IPS:type": "floating"
            }
          ]
        ],
267
268
        "attachments": [
            {
269
270
271
              "id": "18",
              "network_id": "2718",
              "mac_address": "aa:01:02:6c:34:ab",
272
              "firewallProfile": "DISABLED",
273
274
275
276
277
278
279
280
281
282
283
              "ipv4": "",
              "ipv6": "2001:443:2dfc:1232:a810:3cf:fe9b:21ab"
              "OS-EXT-IPS:type": "fixed"
            }, {
              "id": "19",
              "network_id": "2719",
              "mac_address": "aa:00:0c:6d:34:bb",
              "firewallProfile": "PROTECTED",
              "ipv4": "192.168.1.2",
              "ipv6": ""
              "OS-EXT-IPS:type": "floating"
284
285
            }
        ],
286
        "links": [
287
288
289
290
291
292
293
294
295
296
297
          {
            "href": "https://example.org/compute/v2.0/servers/42", 
            "rel": "self"
          }, {
            "href": "https://example.org/compute/v2.0/servers/42", 
            "rel": "bookmark"
          }
        ],
        "image": {
          "id": "im4g3-1d",
          "links": [
298
            {
299
300
301
302
303
304
305
306
              "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
              "rel": "self"
            }, {
              "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
              "rel": "bookmark"
            }, {
              "href": "https://example.org/image/v1.0/images/im4g3-1d", 
              "rel": "alternate"
307
            }
308
309
310
          ]
        },
        "suspended": false,
311
        "created': '2011-04-19T10:18:52.085737+00:00',
312
        "flavor": {
313
314
315
316
317
318
319
320
321
322
          "id": 1",
          "links": [
            {
              "href": "https://example.org/compute/v2.0/flavors/1", 
              "rel": "self"
            }, {
              "href": "https://example.org/compute/v2.0/flavors/1", 
              "rel": "bookmark"
            }
          ]
323
        },
324
        "id": "42",
325
326
327
328
329
330
        "security_groups": [{"name": "default"}],
        "user_id": "s0m5-u5e7-1d",
        "accessIPv4": "",
        "accessIPv6": "",
        "progress": 100,
        "config_drive": "",
331
        "status": "ACTIVE",
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
        "updated": "2011-05-29T14:07:07.037602+00:00",
        "hostId": "",
        "SNF:fqdn": "snf-42.vm.example.org",
        "key_name": null,
        "name": "My Server",
        "created": "2014-02-12T08:31:37.834542+00:00",
        "tenant_id": "s0m5-u5e7-1d",
        "SNF:port_forwarding": {},
        "SNF:task_state": "",
        "diagnostics": [
            {
                "level": "DEBUG",
                "created": "2014-02-12T08:31:37.834542+00:00",
                "source": "image-info",
                "source_date": "2014-02-12T08:32:35.929507+00:00",
                "message": "Image customization finished successfully.",
                "details": null
            }
        ],
        "metadata": {
            "os": "debian",
            "users": "root"
        }
355
      }, {
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
      {
        "addresses": [
          "2718": [
            {
              "version": 6,
              "addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd",
              "OS-EXT-IPS:type": "fixed"
            }
          ],
          "4178": [
            {
              "version": 4,
              "addr": "192.168.1.3",
              "OS-EXT-IPS:type": "floating"
            }
          ]
        ],
373
374
        "attachments": [
            {
375
376
377
              "id": "36",
              "network_id": "2718",
              "mac_address": "aa:01:02:6c:34:cd",
378
              "firewallProfile": "DISABLED",
379
380
381
              "ipv4": "",
              "ipv6": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd"
              "OS-EXT-IPS:type": "fixed"
382
            }, {
383
384
385
386
387
388
389
              "id": "38",
              "network_id": "4178",
              "mac_address": "aa:00:0c:6d:34:cc",
              "firewallProfile": "PROTECTED",
              "ipv4": "192.168.1.3",
              "ipv6": ""
              "OS-EXT-IPS:type": "floating"
390
391
            }
        ],
392
        "links": [
393
394
395
396
397
398
399
400
401
402
403
          {
            "href": "https://example.org/compute/v2.0/servers/84", 
            "rel": "self"
          }, {
            "href": "https://example.org/compute/v2.0/servers/84", 
            "rel": "bookmark"
          }
        ],
        "image": {
          "id": "im4g3-1d",
          "links": [
404
            {
405
406
407
408
409
410
411
412
              "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
              "rel": "self"
            }, {
              "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
              "rel": "bookmark"
            }, {
              "href": "https://example.org/image/v1.0/images/im4g3-1d", 
              "rel": "alternate"
413
            }
414
          ]
415
        },
416
417
418
419
420
421
422
423
424
425
426
427
428
        "suspended": false,
        "created': '2011-04-21T10:18:52.085737+00:00',
        "flavor": {
          "id": 3",
          "links": [
            {
              "href": "https://example.org/compute/v2.0/flavors/3", 
              "rel": "self"
            }, {
              "href": "https://example.org/compute/v2.0/flavors/3", 
              "rel": "bookmark"
            }
          ]
429
        },
430
431
432
433
434
435
436
        "id": "84",
        "security_groups": [{"name": "default"}],
        "user_id": "s0m5-u5e7-1d",
        "accessIPv4": "",
        "accessIPv6": "",
        "progress": 100,
        "config_drive": "",
437
        "status": "ACTIVE",
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
        "updated": "2011-05-30T14:07:07.037602+00:00",
        "hostId": "",
        "SNF:fqdn": "snf-84.vm.example.org",
        "key_name": null,
        "name": "My Other Server",
        "created": "2014-02-21T08:31:37.834542+00:00",
        "tenant_id": "s0m5-u5e7-1d",
        "SNF:port_forwarding": {},
        "SNF:task_state": "",
        "diagnostics": [
          {
            "level": "DEBUG",
            "created": "2014-02-21T08:31:37.834542+00:00",
            "source": "image-info",
            "source_date": "2014-02-21T08:32:35.929507+00:00",
            "message": "Image customization finished successfully.",
            "details": null
          }
        ],
        "metadata": {
          "os": "debian",
          "users": "root"
        }
461
462
      }
    ]
463
  }
464
465


466
Create Server
467
-------------
468

469
470
471
472
Create a new virtual server

.. rubric:: Request

473
============ ====== ======== ==========
474
URI          Method Cyclades OS/Compute
475
476
477
============ ====== ======== ==========
``/servers`` POST   ✔        ✔
============ ====== ======== ==========
478
479

|
480
481
482
483
==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS/Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
484
485
Content-Type    Type or request body      required required
Content-Length  Length of request body    required required
486
487
488
==============  ========================= ======== ==========

|
489
================= ===============
490
Request Parameter Value
491
492
================= ===============
json              Respond in json
493
xml               Respond in xml
494
495
================= ===============

496
Request body contents::
497

498
499
500
501
502
503
  server: {
      <server attribute>: <value>,
      ...
      personality: [
        ...
      ],
504
505
506
      networks: [
        ...
      ]
507
508
      ...
  }
509

510
511
512
513
514
515
516
517
518
=========== ====================== ======== ==========
Attributes  Description            Cyclades OS/Compute
=========== ====================== ======== ==========
name        The server name        ✔        ✔
imageRef    Image id               ✔        ✔
flavorRef   Resources flavor       ✔        ✔
personality Personality contents   ✔        ✔
metadata    Custom metadata        ✔        ✔
networks    Connection information ✔        ✔
519
.. project  .. Project UUID        .. ✔     .. **✘**
520
=========== ====================== ======== ==========
521
522
523

* **name** can be any string

524
* **imageRed** and **flavorRed** should refer to existing images and hardware
525
  flavors accessible by the user
526

527
* **metadata** are ``key``:``value`` pairs of custom server-specific metadata.
528
529
  There are no semantic limitations, although the ``OS`` and ``USERS`` values
  should rather be defined
530

531
532
* **personality** (optional) is a list of
  `personality injections <#personality-ref>`_
533

534
535
* **networks** (optional) is a list of
  `network connections <#network-on-vm-ref>`_.
536

537
538
.. rubric:: Response

539
540
541
542
543
544
545
546
=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Malformed request data
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             User is not allowed to perform this operation
404 (Not Found)             Image or Flavor not found
547
413 (Over Limit)            Exceeded some resource limit
548
415 (Bad Media Type)        
549
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
550
\                           internal error
551
503 (Service Unavailable)   No available backends or service currently
Stavros Sachtouris's avatar
Stavros Sachtouris committed
552
\                           unavailable
553
554
555
556
=========================== =====================

|

557
558
559
560
561
562
563
564
Response body contents::

  server: {
    <server attribute>: <value>,
    ...
  }

Server attributes are `listed here <#server-ref>`_.
565

566
567
568
.. note:: The ``adminPass`` attribute is generated in the response. This is the
    only case where this attribute appears in a response.

569
*Example Create Server Response: JSON*
570
571

.. code-block:: javascript
572

573
574
575
  POST https://example.org/compute/v2.0/servers


576
577
  {
    "server": {
578
579
      "name": "My Example Server",
      "id": 5678,
580
581
      "status": "BUILD",
      "created": "2013-04-10T13:52:17.085402+00:00",
582
      "updated": "2013-04-10T13:52:17.085402+00:00",
583
      "adminPass": "fKCqlZe2at",
584
      "progress": 0
585
      "metadata": {
586
587
588
589
        "OS": "debian",
        "USERS": "root"
      },
      ...
590
591
    }
  }
592

593
.. _personality-ref:
594

595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
Personality: injecting files while creating a virtual server
............................................................

The term "personality" refers to a mechanism for injecting data as files into
the file system of a virtual server while the server is being created. This
mechanism has many application e.g., the injection of ``ssh keys`` for secure
password-less access, automation in user profile configuration, etc.

A personality injection contains the following attributes:

====================== =================== ======== ==========
Personality Attributes Description         Cyclades OS/Compute
====================== =================== ======== ==========
path                   File path on server ✔        ✔
contents               Data to inject      ✔        ✔
group                  User group          ✔        **✘**
mode                   File access mode    ✔        **✘**
owner                  File owner          ✔        **✘**
====================== =================== ======== ==========

* **path** is the path (including name) for the file on the remote server. If
  the file does not exist, it will be created
* **contents** is the data to be injected, must not exceed 10240 *bytes* and
  must be base64-encoded
* **mode** is the access mode of the created remote file and must be a number
  (usually octal or decimal)

*Example Create Server Request: JSON*

.. code-block:: javascript

  POST https://example.org/compute/v2.0/servers
  {
    "server": {
      "name": "My Password-less Server",
      "personality": [
        {
          "path": "/home/someuser/.ssh/authorized_keys",
          "contents": "Some users public key",
          "group": "users",
          "mode": 0600,
          "owner": "someuser"
        }, {
          "path": "/home/someuser/.bashrc",
          "contents": "bash configuration",
          "group": "users",
          "mode": 0777,
          "owner": "someuser"
        }
      ],
      ...
    }
  }

.. _network-on-vm-ref:

Network connections on virtual server creation
..............................................

A network connection is established by creating a port that connects a virtual
device with a network. There are five cases:

* The ``network`` attribute is not provided. In that case, the service will
  apply its default policy (e.g., automatic public network and IP assignment)
* The ``network`` attribute is an empty list. In that case, the virtual server
  will not have any network connections
* Provide an existing network ID. In that case, the virtual server will be
  connected to that network.
* Provide an existing network ID and an IP (which is already associated to that
  network). In that case, the virtual server will be connected to that network
  with this specific IP attached.
* Provide an existing port ID to establish a connection through it.

========================================= ======== ==========
Network attributes on server construction Cyclades OS/Compute
========================================= ======== ==========
uuid                                      ✔        ✔
fixed_ip                                  ✔        ✔
port                                      ✔        ✔
========================================= ======== ==========

E.g., the following example connects a public network with an IP (2719) and a
private network (9876) on the virtual server under construction:

* Example Connect server on various networks*

.. code-block:: python

  POST https://example.org/compute/v2.0/servers
  {
    "server": {
      "networks": [
        {"uuid": 9876},
        {"uuid": 2719, "fixed_ip": "192.168.1.2"},
      ],
      ...
    }
  }
693
694


695
Get Server Stats
696
----------------
697

698
699
700
.. note:: This operation is not part of OS/Compute v2.

This operation returns URLs of graphs showing CPU and Network statistics.
701

702
.. rubric:: Request
703

704
============================== ====== ======== ==========
705
URI                            Method Cyclades OS/Compute
706
707
708
============================== ====== ======== ==========
``/servers/<server-id>/stats`` GET    ✔        **✘**
============================== ====== ======== ==========
709

710
|
711
==============  ========================= ======== ==========
712
Request Header  Value                     Cyclades OS/Compute
713
714
715
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========
716
717
718
719
720
721
722
723
724

|
================= ===============
Request Parameter Value          
================= ===============
json              Respond in json
xml               Respond in xml 
================= ===============

725
726
* **json** and **xml** parameters are mutually exclusive. If none supported,
the response will be formated in json.
727

728
.. rubric:: Response
729
730
731
732
733
734
735
736
737

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Server deleted
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
738
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
739
\                           internal error
740
741
742
743
503 (Service Unavailable)   The server is not currently available
=========================== =====================

|
744

745
746
747
748
749
Response body contents::

  stats: {<parameter>: <value> }

============= ======================
750
Parameter     Description
751
752
753
754
755
756
757
758
759
760
============= ======================
serverRef     Server ID
refresh       Refresh frequency
cpuBar        Latest CPU load graph URL
cpuTimeSeries CPU load / time graph URL
netBar        Latest Network load graph URL
netTimeSeries Network load / time graph URL
============= ======================

* **refresh** is the recommended sampling rate
761

762
*Example Get Server Stats Response: JSON*
763
764

.. code-block:: javascript
765
  GET https://example.org/compute/v2.0/servers/5678/stats
766
  {
767
    "stats": {
768
      "serverRef": 5678,
769
770
771
772
773
774
      "refresh": 60,
      "cpuBar": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-bar.png",
      "cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-ts.png",
      "netBar": "http://stats.okeanos.grnet.gr/b9a...048c/net-bar.png",
      "netTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/net-ts.png"
    }
775
776
  }

777
Get Server Diagnostics
778
----------------------
779

780
.. note:: This operation is not part of OS/Compute v2.
781

782
783
784
This operation returns diagnostic information (logs) for a server.

.. rubric:: Request
785
786

==================================== ====== ======== ==========
787
URI                                  Method Cyclades OS/Compute
788
789
790
791
792
==================================== ====== ======== ==========
``/servers/<server-id>/diagnostics`` GET    ✔        **✘**
==================================== ====== ======== ==========

|
793
794
795
796
797
==============  ========================= ======== ==========
Request Header  Value                     Cyclades OS/Compute
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========
798

799
.. rubric:: Response
800
801
802
803
804
805
806
807
808
809

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Server deleted
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
810
\                           internal error
811
812
813
503 (Service Unavailable)   The server is not currently available
=========================== =====================

814
815
816
817
818
819
820
821
822
823
824
|

Response body contents::

  [
    {
      <diagnostic attribute}: <value>,
      ...
    },
    ...
  ]
825
826
827
828
829
830
831

==================== ===========
Diagnostic attribute Description
==================== ===========
level                Debug level
created              Log entry timestamp
source               Log source proccess
832
source_date          Log source date
833
834
835
836
message              Log description
details              Detailed log description
==================== ===========

837
*Example Get Server Diagnostics Response: JSON*
838
839
840

.. code-block:: javascript

841
  GET https://example.org/compute/v2.0/servers/5678/diagnostics
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
  [
    {
      "level": "DEBUG",
      "created": "2013-04-09T15:25:53.965144+00:00",
      "source": "image-helper-task-start",
      "source_date": "2013-04-09T15:25:53.954695+00:00",
      "message": "FixPartitionTable",
      "details": null
    }, {
      "level": "DEBUG",
      "created": "2013-04-09T15:25:46.413718+00:00",
      "source": "image-info",
      "source_date": "2013-04-09T15:25:46.404477+00:00",
      "message": "Starting customization VM...",
      "details": null
    }
  ]

860
Get Server Details
861
------------------
862

863
864
865
866
This operation returns detailed information for a virtual server

.. rubric:: Request

867
======================== ====== ======== ==========
868
URI                      Method Cyclades OS/Compute
869
870
871
872
873
874
875
======================== ====== ======== ==========
``/servers/<server id>`` GET    ✔        ✔
======================== ====== ======== ==========

|

==============  ========================= ======== ==========
876
Request Header  Value                     Cyclades OS/Compute
877
878
879
880
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

881
.. rubric:: Response
882
883
884
885
886
887
888
889
890

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Malformed server id
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
891
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
892
\                           internal error
893
503 (Service Unavailable)   No available backends or service currently
Stavros Sachtouris's avatar
Stavros Sachtouris committed
894
\                           unavailable
895
896
897
898
=========================== =====================

|

899
900
901
902
903
904
Response body contents::

  server: {
    <server attribute>: <value>,
    ...
  }
905

906
907
908
Server attributes are explained `here <#server-ref>`_

*Example get server Details*
909
910
911

.. code-block:: javascript

912
913
914
  GET https://example.org/compute/v2.0/servers/84


915
916
  {
    "server": {
917
918
919
920
921
922
923
      "addresses": [
        "2718": [
          {
            "version": 6,
            "addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd",
            "OS-EXT-IPS:type": "fixed"
          }
924
        ],
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
        "4178": [
          {
            "version": 4,
            "addr": "192.168.1.3",
            "OS-EXT-IPS:type": "floating"
          }
        ]
      ],
      "attachments": [
          {
            "id": "36",
            "network_id": "2718",
            "mac_address": "aa:01:02:6c:34:cd",
            "firewallProfile": "DISABLED",
            "ipv4": "",
            "ipv6": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd"
            "OS-EXT-IPS:type": "fixed"
          }, {
            "id": "38",
            "network_id": "4178",
            "mac_address": "aa:00:0c:6d:34:cc",
            "firewallProfile": "PROTECTED",
            "ipv4": "192.168.1.3",
            "ipv6": ""
            "OS-EXT-IPS:type": "floating"
          }
      ],
      "links": [
        {
          "href": "https://example.org/compute/v2.0/servers/84", 
          "rel": "self"
        }, {
          "href": "https://example.org/compute/v2.0/servers/84", 
          "rel": "bookmark"
        }
      ],
      "image": {
        "id": "im4g3-1d",
963
        "links": [
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
          {
            "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
            "rel": "self"
          }, {
            "href": "https://example.org/compute/v2.0/images/im4g3-1d", 
            "rel": "bookmark"
          }, {
            "href": "https://example.org/image/v1.0/images/im4g3-1d", 
            "rel": "alternate"
          }
        ]
      },
      "suspended": false,
      "created': '2011-04-21T10:18:52.085737+00:00',
      "flavor": {
        "id": 3",
        "links": [
          {
            "href": "https://example.org/compute/v2.0/flavors/3", 
            "rel": "self"
          }, {
            "href": "https://example.org/compute/v2.0/flavors/3", 
            "rel": "bookmark"
          }
        ]
      },
      "id": "84",
      "security_groups": [{"name": "default"}],
      "user_id": "s0m5-u5e7-1d",
      "accessIPv4": "",
      "accessIPv6": "",
      "progress": 100,
      "config_drive": "",
      "status": "ACTIVE",
      "updated": "2011-05-30T14:07:07.037602+00:00",
      "hostId": "",
      "SNF:fqdn": "snf-84.vm.example.org",
      "key_name": null,
      "name": "My Other Server",
      "created": "2014-02-21T08:31:37.834542+00:00",
      "tenant_id": "s0m5-u5e7-1d",
      "SNF:port_forwarding": {},
      "SNF:task_state": "",
      "diagnostics": [
        {
          "level": "DEBUG",
          "created": "2014-02-21T08:31:37.834542+00:00",
          "source": "image-info",
          "source_date": "2014-02-21T08:32:35.929507+00:00",
          "message": "Image customization finished successfully.",
          "details": null
        }
      ],
      "metadata": {
        "os": "debian",
        "users": "root"
1020
1021
1022
      }
    }
  }
1023

1024
Rename Server
1025
-------------
1026

1027
1028
In Synnefo/Cyclades, only the ``name`` attribute of a virtual server can be
modified with this call.
1029
1030
1031

.. rubric:: Response

1032
======================== ====== ======== ==========
1033
URI                      Method Cyclades OS/Compute
1034
1035
1036
1037
1038
1039
======================== ====== ======== ==========
``/servers/<server id>`` PUT    ✔        ✔
======================== ====== ======== ==========

|
==============  ========================= ======== ==========
1040
Request Header  Value                     Cyclades OS/Compute
1041
1042
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
1043
1044
Content-Type    Type or request body      required required
Content-Length  Length of request body    required required
1045
1046
==============  ========================= ======== ==========

1047
1048
1049
1050
1051
1052
Request body contents::

  server: {
    <server attribute>: <value>,
    ...
  }
1053
1054

=========== ==================== ======== ==========
1055
Attribute   Description          Cyclades OS/Compute
1056
1057
1058
1059
1060
1061
=========== ==================== ======== ==========
name        The server name      ✔        ✔
accessIPv4  IP v4 address        **✘**    ✔
accessIPv6  IP v6 address        **✘**    ✔
=========== ==================== ======== ==========

1062
1063
1064
* **accessIPv4** and **accessIPv6** are ignored. Cyclades features a different
  `mechanism for managing network connections <network-api-guide.html>`_ on
  servers
1065

1066
1067
1068
1069
*Example Rename Server Request: JSON*

.. code-block:: javascript

1070
  {"server": {"name": "New name"}}
1071

1072
.. rubric:: Response
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083

=========================== =====================
Return Code                 Description
=========================== =====================
204 (OK)                    Request succeeded
400 (Bad Request)           Malformed request or malformed server id
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             User is not allowed to perform this operation
404 (Not Found)             Server not found
415 (Bad Media Type)
409 (Build In Progress)     Server is not ready yet
1084
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
1085
\                           internal error
1086
503 (Service Unavailable)   No available backends or service currently
Stavros Sachtouris's avatar
Stavros Sachtouris committed
1087
\                           unavailable
1088
1089
=========================== =====================

1090
1091
1092
.. note:: In case of a 204 return code, there will be no request results
  according to the Cyclades API. Compute OS API suggests that response should
  include the new server details.
1093

1094
Delete Server
1095
-------------
1096

1097
1098
Delete a virtual server. When a server is deleted, all its attachments (ports)
are deleted as well.
1099
1100
1101

.. rubric:: Request

1102
======================== ====== ======== ==========
1103
URI                      Method Cyclades OS/Compute
1104
1105
1106
1107
======================== ====== ======== ==========
``/servers/<server id>`` DELETE ✔        ✔
======================== ====== ======== ==========

1108
* **server-id** is the identifier of the virtual server.
1109
1110
1111

|
==============  ========================= ======== ==========
1112
Request Header  Value                     Cyclades OS/Compute
1113
1114
1115
1116
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

1117
.. rubric:: Response
1118
1119
1120
1121
1122
1123
1124
1125
1126

=========================== =====================
Return Code                 Description
=========================== =====================
204 (OK)                    Request succeeded
400 (Bad Request)           Malformed server id or machine already deleted
401 (Unauthorized)          Missing or expired user token
404 (Not Found)             Server not found
409 (Build In Progress)     Server is not ready yet
1127
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
1128
\                           internal error
1129
503 (Service Unavailable)   Action not supported or service currently
Stavros Sachtouris's avatar
Stavros Sachtouris committed
1130
\                           unavailable
1131
1132
=========================== =====================

1133
1134
List Server Connections
-----------------------
1135

1136
1137
List a server's network connections. In Cyclades, connections are ports between
a network and the server.
1138
1139

.. rubric:: Request
1140
1141

============================ ====== ======== ==========
1142
URI                          Method Cyclades OS/Compute
1143
1144
1145
1146
1147
1148
============================ ====== ======== ==========
``/servers/<server id>/ips`` GET    ✔        ✔
============================ ====== ======== ==========

|
==============  ========================= ======== ==========
1149
Request Header  Value                     Cyclades OS/Compute
1150
1151
1152
1153
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

1154
.. rubric:: Response
1155
1156
1157
1158
1159
1160
1161
1162
1163

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Malformed server id or machine already deleted
401 (Unauthorized)          Missing or expired user token
404 (Not Found)             Server not found
409 (Build In Progress)     Server is not ready yet
1164
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
1165
\                           internal error
1166
1167
1168
503 (Service Unavailable)   Service currently unavailable
=========================== =====================

1169
1170
Response body contents::

1171
  addresses: [
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
    <network id>: [
      {
        version: <4 or 6>,
        addr: <IP address, if any>
        OS-EXT-TYPE:type: <floating or fixed>
      },
      ...
    ],
    ...
  ],
  attachments: [
1183
    {
1184
      <attachment attribute>: ...,
1185
1186
1187
      ...
    },
    ...
1188
  ]
1189

1190
Attachment attributes are explained `here <#attachments-ref>`_
1191

1192
*Example List Addresses: JSON*
1193
1194
1195

.. code-block:: javascript

1196
1197
  GET https://example.org/compute/v2.0/servers/84/ips/

1198
  {
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
      "addresses": [
        "2718": [
          {
            "version": 6,
            "addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd",
            "OS-EXT-IPS:type": "fixed"
          }
        ],
        "4178": [
          {
            "version": 4,
            "addr": "192.168.1.3",
            "OS-EXT-IPS:type": "floating"
          }
        ]
      ],
      "attachments": [
          {
            "id": "36",
            "network_id": "2718",
            "mac_address": "aa:01:02:6c:34:cd",
            "firewallProfile": "DISABLED",
            "ipv4": "",
            "ipv6": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd"
            "OS-EXT-IPS:type": "fixed"
          }, {
            "id": "38",
            "network_id": "4178",
            "mac_address": "aa:00:0c:6d:34:cc",
            "firewallProfile": "PROTECTED",
            "ipv4": "192.168.1.3",
            "ipv6": ""
            "OS-EXT-IPS:type": "floating"
          }
      ]
1234
1235
  }

1236
1237
Connection with network
-----------------------
1238

1239
Get information on a network connected on a server
1240

1241
.. rubric:: Request
1242
1243

========================================= ====== ======== ==========
1244
URI                                       Method Cyclades OS/Compute
1245
1246
1247
1248
1249
1250
========================================= ====== ======== ==========
``/servers/<server id>/ips/<network id>`` GET    ✔        ✔
========================================= ====== ======== ==========

|
==============  ========================= ======== ==========
1251
Request Header  Value                     Cyclades OS/Compute
1252
1253
1254
1255
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========

1256
.. rubric:: Response
1257
1258
1259
1260
1261
1262
1263
1264
1265

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Malformed server id or machine already deleted
401 (Unauthorized)          Missing or expired user token
404 (Not Found)             Server not found
409 (Build In Progress)     Server is not ready yet
1266
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
1267
\                           internal error
1268
1269
1270
503 (Service Unavailable)   Service currently unavailable
=========================== =====================

1271
1272
1273
1274
1275
|

Response body contents::

  network: {
1276
1277
1278
1279
1280
1281
    <network id>: [
      {
        version: <4 or 6>,
        addr: <IP address, if any>
        OS-EXT-TYPE:type: <floating or fixed>
      },
1282
  }
1283

1284
**Example**
1285
1286
1287

.. code-block:: javascript

1288
  GET https://example.org/compute/v2.0/servers/84/ips/2718
1289

1290

1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
  "network": {
    "2718": [
      {
        "version": 6,
        "addr": "2001:443:2dfc:1232:a810:3cf:fe9b:21cd",
        "OS-EXT-IPS:type": "fixed"
      }
    ]
  }

1301
List Server Metadata
1302
--------------------
1303

1304
1305
1306
1307
.. note:: This operation is semantically equivalent in Cyclades and OS/Compute
  besides the different URI.

.. rubric:: Request
1308
1309

================================= ====== ======== ==========
1310
URI                               Method Cyclades OS/Compute
1311
================================= ====== ======== ==========
1312
``/servers/<server-id>/metadata`` GET    ✔        ✔
1313
1314
1315
================================= ====== ======== ==========

|
1316
==============  ========================= ======== ==========
1317
Request Header  Value                     Cyclades OS/Compute
1318
1319
1320
==============  ========================= ======== ==========
X-Auth-Token    User authentication token required required
==============  ========================= ======== ==========
1321

1322
.. rubric:: Response
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332

=========================== =====================
Return Code                 Description
=========================== =====================
200 (OK)                    Request succeeded
400 (Bad Request)           Invalid server ID or Malformed request
401 (Unauthorized)          Missing or expired user token
403 (Forbidden)             Administratively suspended server
404 (Not Found)             Server not found
500 (Internal Server Error) The request cannot be completed because of an
Stavros Sachtouris's avatar
Stavros Sachtouris committed
1333
\                           internal error
1334
1335
1336
503 (Service Unavailable)   The server is not currently available
=========================== =====================

1337
1338
Response body contents::

1339
1340
  metadata: {
    <key>: <value>,
1341
1342
1343
      ...
  }

1344
1345
* Key is in uppercase by convention

1346
*Example List Server Metadata: JSON*
1347
1348

.. code-block:: javascript
1349

1350
  {
1351
    ""metadata": {
1352
      "OS": "Linux",
1353
      "USERS": "root"
1354
1355
1356
1357
    }
  }

Set / Update Server Metadata
1358
----------------------------
1359
1360

In Cyclades API, setting new metadata and updating the values of existing ones
1361
1362
is achieved with the same type of request (``POST``), while in OS/Compute API
there are two separate request types (``PUT`` and ``POST`` for
1363
1364
1365
1366
1367
`setting new <http://docs.openstack.org/api/openstack-compute/2/content/Create_or_Replace_Metadata-d1e5358.html>`_
and
`updating existing <http://docs.openstack.org/api/openstack-compute/2/content/Update_Metadata-d1e5208.html>`_
metadata, respectively).

1368
In Cyclades API, metadata keys which are not referred by the operation will
1369
1370
1371
remain intact, while metadata referred by the operation will be overwritten.

.. rubric:: Request
1372
1373

================================= ====== ======== ==========
1374
URI                               Method Cyclades OS/Compute
1375
1376
================================= ====== ======== ==========
``/servers/<server-id>/metadata`` PUT    **✘**    ✔
1377
``/servers/<server-id>/metadata`` POST   ✔       ✔
1378
1379
1380
================================= ====== ======== ==========

|
1381
==============  ========================= ======== ==========
1382
Request Header  Value                     Cyclades OS/Compute
1383
1384
<