Revision 20394434
b/docs/api-guide.rst | ||
---|---|---|
36 | 36 |
.. toctree:: |
37 | 37 |
:maxdepth: 2 |
38 | 38 |
|
39 |
Identity API (Keystone) <astakos-api-guide>
|
|
39 |
Identity API (Keystone) <identity-api-guide>
|
|
40 | 40 |
|
41 | 41 |
|
42 | 42 |
Resource and Quota Service API (Astakos) |
... | ... | |
72 | 72 |
.. toctree:: |
73 | 73 |
:maxdepth: 2 |
74 | 74 |
|
75 |
Compute API (Compute) <cyclades-api-guide> |
|
75 |
Compute API (Compute) <compute-api-guide> |
|
76 |
|
|
76 | 77 |
|
77 | 78 |
|
78 | 79 |
Network Service API (Cyclades) |
... | ... | |
100 | 101 |
.. toctree:: |
101 | 102 |
:maxdepth: 2 |
102 | 103 |
|
103 |
Image API (Glance) <plankton-api-guide>
|
|
104 |
Image API (Glance) <image-api-guide>
|
|
104 | 105 |
|
105 | 106 |
|
106 | 107 |
Storage Service API (Pithos) |
... | ... | |
114 | 115 |
.. toctree:: |
115 | 116 |
:maxdepth: 2 |
116 | 117 |
|
117 |
Storage API (Object Storage) <pithos-api-guide>
|
|
118 |
Storage API (Object Storage) <object-api-guide>
|
|
118 | 119 |
|
119 | 120 |
|
120 | 121 |
Implementing new clients |
/dev/null | ||
---|---|---|
1 |
Astakos API |
|
2 |
=========== |
|
3 |
|
|
4 |
This is Astakos API guide. |
|
5 |
|
|
6 |
Overview |
|
7 |
-------- |
|
8 |
|
|
9 |
|
|
10 |
Astakos service co-ordinates the access to resources (and the subsequent |
|
11 |
permission model) and acts as the single point of registry and entry to the |
|
12 |
GRNET cloud services. |
|
13 |
|
|
14 |
This document's goals is to describe the APIs to the outer world. |
|
15 |
Make sure you have read the :ref:`astakos` general architecture first. |
|
16 |
|
|
17 |
Document Revisions |
|
18 |
^^^^^^^^^^^^^^^^^^ |
|
19 |
|
|
20 |
========================= ================================ |
|
21 |
Revision Description |
|
22 |
========================= ================================ |
|
23 |
0.15 (December 02, 2013) Extent token api with validate token call |
|
24 |
0.15 (October 29, 2013) Remove GET /authenticate in favor of POST /tokens |
|
25 |
0.14 (June 03, 2013) Remove endpoint listing |
|
26 |
0.14 (May 28, 2013) Extend token api with authenticate call |
|
27 |
0.14 (May 23, 2013) Extend api to list endpoints |
|
28 |
0.14 (May 14, 2013) Do not serve user quotas in :ref:`authenticate-api-label` |
|
29 |
0.14 (May 02, 2013) Change URIs (keep also the old ones until the next version) |
|
30 |
0.13 (January 21, 2013) Extend api to export user presentation & quota information. |
|
31 |
0.6 (June 06, 2012) Split service and user API. |
|
32 |
0.1 (Feb 10, 2012) Initial release. |
|
33 |
========================= ================================ |
|
34 |
|
|
35 |
Get Services |
|
36 |
^^^^^^^^^^^^ |
|
37 |
|
|
38 |
Returns a json formatted list containing information about the supported cloud services. |
|
39 |
|
|
40 |
============================= ========= ================== |
|
41 |
Uri Method Description |
|
42 |
============================= ========= ================== |
|
43 |
``/ui/get_services`` GET Get cloud services |
|
44 |
============================= ========= ================== |
|
45 |
|
|
46 |
Example reply: |
|
47 |
|
|
48 |
:: |
|
49 |
|
|
50 |
[{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"}, |
|
51 |
{"url": "/okeanos.html", "name": "~okeanos", "id": "2"}, |
|
52 |
{"url": "/ui/", "name": "pithos", "id": "3"}] |
|
53 |
|
|
54 |
|
|
55 |
Get Menu |
|
56 |
^^^^^^^^ |
|
57 |
|
|
58 |
Returns a json formatted list containing the cloud bar links. |
|
59 |
|
|
60 |
========================= ========= ================== |
|
61 |
Uri Method Description |
|
62 |
========================= ========= ================== |
|
63 |
``/ui/get_menu`` GET Get cloud bar menu |
|
64 |
========================= ========= ================== |
|
65 |
|
|
66 |
Example reply if request user is not authenticated: |
|
67 |
|
|
68 |
:: |
|
69 |
|
|
70 |
[{"url": "/ui/", "name": "Sign in"}] |
|
71 |
|
|
72 |
Example reply if request user is authenticated: |
|
73 |
|
|
74 |
:: |
|
75 |
|
|
76 |
[{"url": "/ui/", "name": "user@example.com"}, |
|
77 |
{"url": "/ui/landing", "name": "Dashboard"}, |
|
78 |
{"url": "/ui/logout", "name": "Sign out"}] |
|
79 |
|
|
80 |
|
|
81 |
User API Operations |
|
82 |
-------------------- |
|
83 |
|
|
84 |
The operations described in this chapter allow users to send feedback and |
|
85 |
get user uuid/displayname mappings. |
|
86 |
|
|
87 |
All the operations require a valid user token. |
|
88 |
|
|
89 |
Send feedback |
|
90 |
^^^^^^^^^^^^^ |
|
91 |
|
|
92 |
Post user feedback. |
|
93 |
|
|
94 |
========================== ========= ================== |
|
95 |
Uri Method Description |
|
96 |
========================== ========= ================== |
|
97 |
``/account/v1.0/feedback`` POST Send feedback |
|
98 |
========================== ========= ================== |
|
99 |
|
|
100 |
| |
|
101 |
|
|
102 |
==================== ============================ |
|
103 |
Request Header Name Value |
|
104 |
==================== ============================ |
|
105 |
X-Auth-Token User authentication token |
|
106 |
==================== ============================ |
|
107 |
|
|
108 |
| |
|
109 |
|
|
110 |
====================== ========================= |
|
111 |
Request Parameter Name Value |
|
112 |
====================== ========================= |
|
113 |
feedback_msg Feedback message |
|
114 |
feedback_data Additional information about service client status |
|
115 |
====================== ========================= |
|
116 |
|
|
117 |
| |
|
118 |
|
|
119 |
=========================== ===================== |
|
120 |
Return Code Description |
|
121 |
=========================== ===================== |
|
122 |
200 (OK) The request succeeded |
|
123 |
502 (Bad Gateway) Send feedback failure |
|
124 |
400 (Bad Request) Method not allowed or invalid message data |
|
125 |
401 (Unauthorized) Missing or expired user token |
|
126 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
127 |
=========================== ===================== |
|
128 |
|
|
129 |
.. warning:: The service is also available under ``/feedback``. |
|
130 |
It will be removed in the next version. |
|
131 |
|
|
132 |
Get User catalogs |
|
133 |
^^^^^^^^^^^^^^^^^ |
|
134 |
|
|
135 |
Return a json formatted dictionary containing information about a specific user |
|
136 |
|
|
137 |
=============================== ========= ================== |
|
138 |
Uri Method Description |
|
139 |
=============================== ========= ================== |
|
140 |
``/account/v1.0/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite |
|
141 |
=============================== ========= ================== |
|
142 |
|
|
143 |
| |
|
144 |
|
|
145 |
==================== ============================ |
|
146 |
Request Header Name Value |
|
147 |
==================== ============================ |
|
148 |
X-Auth-Token User authentication token |
|
149 |
==================== ============================ |
|
150 |
|
|
151 |
| |
|
152 |
|
|
153 |
The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. |
|
154 |
|
|
155 |
Example request content: |
|
156 |
|
|
157 |
:: |
|
158 |
|
|
159 |
{"displaynames": ["user1@example.com", "user2@example.com"], |
|
160 |
"uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} |
|
161 |
|
|
162 |
Example reply: |
|
163 |
|
|
164 |
:: |
|
165 |
|
|
166 |
{"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
|
167 |
"user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, |
|
168 |
'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", |
|
169 |
"ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} |
|
170 |
|
|
171 |
|
|
172 |
| |
|
173 |
|
|
174 |
=========================== ===================== |
|
175 |
Return Code Description |
|
176 |
=========================== ===================== |
|
177 |
200 (OK) The request succeeded |
|
178 |
400 (Bad Request) Method not allowed or request body is not json formatted |
|
179 |
401 (Unauthorized) Missing or expired or invalid user token |
|
180 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
181 |
=========================== ===================== |
|
182 |
|
|
183 |
.. warning:: The service is also available under ``/user_catalogs``. |
|
184 |
It will be removed in the next version. |
|
185 |
|
|
186 |
Service API Operations |
|
187 |
---------------------- |
|
188 |
|
|
189 |
The operations described in this chapter allow services to get user uuid/displayname mappings. |
|
190 |
|
|
191 |
All the operations require a valid service token. |
|
192 |
|
|
193 |
Get User catalogs |
|
194 |
^^^^^^^^^^^^^^^^^ |
|
195 |
|
|
196 |
Return a json formatted dictionary containing information about a specific user |
|
197 |
|
|
198 |
======================================= ========= ================== |
|
199 |
Uri Method Description |
|
200 |
======================================= ========= ================== |
|
201 |
``/account/v1.0/service/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite |
|
202 |
======================================= ========= ================== |
|
203 |
|
|
204 |
| |
|
205 |
|
|
206 |
==================== ============================ |
|
207 |
Request Header Name Value |
|
208 |
==================== ============================ |
|
209 |
X-Auth-Token Service authentication token |
|
210 |
==================== ============================ |
|
211 |
|
|
212 |
| |
|
213 |
|
|
214 |
The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. |
|
215 |
If instead of list null is passed then the response contains the information for all the system users (For discretion purposes |
|
216 |
this behavior is **not** exposed in the respective call of the User API). |
|
217 |
|
|
218 |
Example request content: |
|
219 |
|
|
220 |
:: |
|
221 |
|
|
222 |
{"displaynames": ["user1@example.com", "user2@example.com"], |
|
223 |
"uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} |
|
224 |
|
|
225 |
Example reply: |
|
226 |
|
|
227 |
:: |
|
228 |
|
|
229 |
{"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", |
|
230 |
"user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, |
|
231 |
'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", |
|
232 |
"ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} |
|
233 |
|
|
234 |
|
|
235 |
| |
|
236 |
|
|
237 |
=========================== ===================== |
|
238 |
Return Code Description |
|
239 |
=========================== ===================== |
|
240 |
200 (OK) The request succeeded |
|
241 |
400 (Bad Request) Method not allowed or request body is not json formatted |
|
242 |
401 (Unauthorized) Missing or expired or invalid service token |
|
243 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
244 |
=========================== ===================== |
|
245 |
|
|
246 |
.. warning:: The service is also available under ``/service/api/user_catalogs``. |
|
247 |
It will be removed in the next version. |
|
248 |
|
|
249 |
Tokens API Operations |
|
250 |
---------------------- |
|
251 |
|
|
252 |
Authenticate |
|
253 |
^^^^^^^^^^^^ |
|
254 |
|
|
255 |
This call takes the user token or the user uuid/token pair, authenticates |
|
256 |
the user and returns information about the token, its holder as well as |
|
257 |
a list of services the user can access. |
|
258 |
If no request body is provided (the request content length is missing or |
|
259 |
equals to 0), the call operates in public mode, attempts no authentication |
|
260 |
and returns only the service catalog. |
|
261 |
|
|
262 |
========================================= ========= ================== |
|
263 |
Uri Method Description |
|
264 |
========================================= ========= ================== |
|
265 |
``/identity/v2.0/tokens/`` POST Checks whether the provided token is valid and conforms with the provided uuid (if present) and returns back information about the user |
|
266 |
========================================= ========= ================== |
|
267 |
|
|
268 |
The input should be json formatted. |
|
269 |
|
|
270 |
Example request: |
|
271 |
|
|
272 |
:: |
|
273 |
|
|
274 |
{ |
|
275 |
"auth":{ |
|
276 |
"token":{ |
|
277 |
"id":"CDEe2k0T/HdiJWBMMbHyOA" |
|
278 |
}, |
|
279 |
"tenantName":"c18088be-16b1-4263-8180-043c54e22903" |
|
280 |
} |
|
281 |
} |
|
282 |
|
|
283 |
or |
|
284 |
|
|
285 |
:: |
|
286 |
|
|
287 |
{ |
|
288 |
"auth":{ |
|
289 |
"passwordCredentials":{ |
|
290 |
"username":"c18088be-16b1-4263-8180-043c54e22903", |
|
291 |
"password":"CDEe2k0T/HdiJWBMMbHyOA" |
|
292 |
}, |
|
293 |
"tenantName":"c18088be-16b1-4263-8180-043c54e22903" |
|
294 |
} |
|
295 |
} |
|
296 |
|
|
297 |
|
|
298 |
The tenantName in the above requests is optional. |
|
299 |
|
|
300 |
The response is json formatted unless it is requested otherwise via format |
|
301 |
request parameter or Accept header. |
|
302 |
|
|
303 |
Example json response: |
|
304 |
|
|
305 |
:: |
|
306 |
|
|
307 |
{"access": { |
|
308 |
"token": { |
|
309 |
"expires": "2013-06-19T15:23:59.975572+00:00", |
|
310 |
"id": "CDEe2k0T/HdiJWBMMbHyOA==", |
|
311 |
"tenant": { |
|
312 |
"id": "c18088be-16b1-4263-8180-043c54e22903", |
|
313 |
"name": "Firstname Lastname" |
|
314 |
} |
|
315 |
}, |
|
316 |
"serviceCatalog": [ |
|
317 |
{"endpoints_links": [], |
|
318 |
"endpoints": [{ |
|
319 |
"SNF:uiURL": "https://accounts.example.synnefo.org/ui", |
|
320 |
"versionId": "v1.0", |
|
321 |
"publicURL": "https://accounts.example.synnefo.org/account/v1.0"}], |
|
322 |
"type": "account", |
|
323 |
"name": "astakos_account"}, |
|
324 |
{"endpoints_links": [], |
|
325 |
"endpoints": [{ |
|
326 |
"SNF:uiURL": "https://accounts.example.synnefo.org/ui", |
|
327 |
"versionId": "v2.0", |
|
328 |
"publicURL": "https://accounts.example.synnefo.org/account/v2.0"}], |
|
329 |
"type": "identity", |
|
330 |
"name": "astakos_identity"}, |
|
331 |
{"endpoints_links": [], |
|
332 |
"endpoints": [{ |
|
333 |
"SNF:uiURL": "https://cyclades.example.synnefo.org/ui", |
|
334 |
"versionId": "v2.0", |
|
335 |
"publicURL": "https://cyclades.example.synnefo.org/cyclades/compute/v2.0"}], |
|
336 |
"type": "compute", |
|
337 |
"name": "cyclades_compute"}, |
|
338 |
{"endpoints_links": [], |
|
339 |
"endpoints": [{ |
|
340 |
"SNF:uiURL": "https://cyclades.example.synnefo.org/ui", |
|
341 |
"versionId": "v1.0", |
|
342 |
"publicURL": "https://cyclades.example.synnefo.org/cyclades/vmapi/v1.0"}], |
|
343 |
"type": "cyclades_vmapi", |
|
344 |
"name": "cyclades_vmapi"}, |
|
345 |
{"endpoints_links": [], |
|
346 |
"endpoints": [{ |
|
347 |
"SNF:uiURL": "https://cyclades.example.synnefo.org/ui", |
|
348 |
"versionId": "v1.0", |
|
349 |
"publicURL": "https://cyclades.example.synnefo.org/cyclades/image/v1.0"}], |
|
350 |
"type": "image", |
|
351 |
"name": "cyclades_plankton"}, |
|
352 |
{"endpoints_links": [], |
|
353 |
"endpoints": [{ |
|
354 |
"SNF:uiURL": "https://object-store.example.synnefo.org/ui", |
|
355 |
"versionId": "v2.0", |
|
356 |
"publicURL": "https://object-store.example.synnefo.org/pithos/public/v2.0"}], |
|
357 |
"type": "public", |
|
358 |
"name": "pithos_public"}, |
|
359 |
{"endpoints_links": [], |
|
360 |
"endpoints": [{ |
|
361 |
"SNF:uiURL": "https://object-store.example.synnefo.org/ui", |
|
362 |
"versionId": "v1", |
|
363 |
"publicURL": "https://object-store.example.synnefo.org/pithos/object-store/v1"}], |
|
364 |
"type": "object-store", |
|
365 |
"name": "pithos_object-store"}, |
|
366 |
{"endpoints_links": [], |
|
367 |
"endpoints": [{ |
|
368 |
"SNF:uiURL": "https://accounts.example.synnefo.org/ui", |
|
369 |
"versionId": "", |
|
370 |
"SNF:webloginURL": "http://localhost:8080/astakos/weblogin" |
|
371 |
"publicURL": "https://accounts.example.synnefo.org/astakos/weblogin"}], |
|
372 |
"type": "astakos_weblogin", |
|
373 |
"name": "astakos_weblogin"}], |
|
374 |
"user": { |
|
375 |
"roles_links": [], |
|
376 |
"id": "c18088be-16b1-4263-8180-043c54e22903", |
|
377 |
"roles": [{"id": 1, "name": "default"}], |
|
378 |
"name": "Firstname Lastname"}}} |
|
379 |
|
|
380 |
Example xml response: |
|
381 |
|
|
382 |
:: |
|
383 |
|
|
384 |
<?xml version="1.0" encoding="UTF-8"?> |
|
385 |
|
|
386 |
<access xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
|
387 |
xmlns="http://docs.openstack.org/identity/api/v2.0"> |
|
388 |
<token id="CDEe2k0T/HdiJWBMMbHyOA==" expires="2013-06-19T15:23:59.975572+00:00"> |
|
389 |
<tenant id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname" /> |
|
390 |
</token> |
|
391 |
<user id="c18088be-16b1-4263-8180-043c54e22903" name="Firstname Lastname"> |
|
392 |
<roles> |
|
393 |
<role id="1" name="default"/> |
|
394 |
</roles> |
|
395 |
</user> |
|
396 |
<serviceCatalog> |
|
397 |
<service type="account" name="astakos_account"> |
|
398 |
<endpoint SNF:uiURL="https://accounts.example.synnefo.org/ui" versionId="v1.0" publicURL="https://accounts.example.synnefo.org/account/v1.0" /> |
|
399 |
</service> |
|
400 |
<service type="identity" name="astakos_identity"> |
|
401 |
<endpoint SNF:uiURL="https://accounts.example.synnefo.org/ui" versionId="v2.0" publicURL="https://accounts.example.synnefo.org/account/v2.0" /> |
|
402 |
</service> |
|
403 |
<service type="compute" name="cyclades_compute"> |
|
404 |
<endpoint SNF:uiURL="https://cyclades.example.synnefo.org/ui" versionId="v2.0" publicURL="https://cyclades.example.synnefo.org/cyclades/compute/v2.0" /> |
|
405 |
</service> |
|
406 |
<service type="cyclades_vmapi" name="cyclades_vmapi"> |
|
407 |
<endpoint SNF:uiURL="https://cyclades.example.synnefo.org/ui" versionId="v1.0" publicURL="https://cyclades.example.synnefo.org/cyclades/vmapi/v1.0" /> |
|
408 |
</service> |
|
409 |
<service type="image" name="cyclades_plankton"> |
|
410 |
<endpoint SNF:uiURL="https://cyclades.example.synnefo.org/ui" versionId="v1.0" publicURL="https://cyclades.example.synnefo.org/cyclades/image/v1.0" /> |
|
411 |
</service> |
|
412 |
<service type="public" name="pithos_public"> |
|
413 |
<endpoint SNF:uiURL="https://object-store.example.synnefo.org/ui" versionId="v2.0" publicURL="https://object-store.example.synnefo.org/pithos/public/v2.0" /> |
|
414 |
</service> |
|
415 |
<service type="object-store" name="pithos_object-store"> |
|
416 |
<endpoint SNF:uiURL="https://object-store.example.synnefo.org/ui" versionId="v1" publicURL="https://object-store.example.synnefo.org/pithos/object-store/v1" /> </service> |
|
417 |
<service type="astakos_weblogin" name="astakos_weblogin"> |
|
418 |
<endpoint SNF:uiURL="htftps://accounts.example.synnefo.org/ui" versionId="" "SNF:webloginURL": "http://localhost:8080/astakos/weblogin" publicURL="https://accounts.example.synnefo.org/astakos/weblogin" /> |
|
419 |
</serviceCatalog> |
|
420 |
</access> |
|
421 |
|
|
422 |
| |
|
423 |
|
|
424 |
=========================== ===================== |
|
425 |
Return Code Description |
|
426 |
=========================== ===================== |
|
427 |
200 (OK) The request succeeded |
|
428 |
400 (Bad Request) Method not allowed or invalid request format or missing expected input or not consistent tenantName |
|
429 |
401 (Unauthorized) Invalid token or invalid creadentials or tenantName does not comply with the provided token |
|
430 |
500 (Internal Server Error) The request cannot be completed because of an internal error |
|
431 |
=========================== ===================== |
|
432 |
|
|
433 |
Validate token |
|
434 |
^^^^^^^^^^^^^^ |
|
435 |
|
|
436 |
This calls validates an access token and confirms that it belongs to a |
|
437 |
specified scope. |
|
438 |
|
|
439 |
========================================= ========= ================== |
|
440 |
Uri Method Description |
|
441 |
========================================= ========= ================== |
|
442 |
``/identity/v2.0/tokens/<token_id>`` GET Validates an access token and confirms that it belongs to a specified scope. |
|
443 |
========================================= ========= ================== |
|
444 |
|
|
445 |
| |
|
446 |
|
|
447 |
====================== ========================= |
|
448 |
Request Parameter Name Value |
|
449 |
====================== ========================= |
|
450 |
belongsTo Validates that a access token has the specified scope. |
|
451 |
The belongsTo parameter is optional. |
|
452 |
====================== ========================= |
|
453 |
|
|
454 |
|
|
455 |
Example response |
|
456 |
|
|
457 |
:: |
|
458 |
|
|
459 |
{"access": { |
|
460 |
"token": { |
|
461 |
"expires": "2013-12-02T15:57:34.300266+00:00", |
|
462 |
"id": "2YotnFZFEjr1zCsicMWpAA", |
|
463 |
"tenant": { |
|
464 |
"id": "c18088be-16b1-4263-8180-043c54e22903", |
|
465 |
"name": "Firstname Lastname" |
|
466 |
} |
|
467 |
}, |
|
468 |
"user": { |
|
469 |
"roles_links": [], |
|
470 |
"id": "c18088be-16b1-4263-8180-043c54e22903", |
|
471 |
"roles": [{"id": 1, "name": "default"}], |
|
472 |
"name": "Firstname Lastname"}}} |
|
473 |
| |
|
474 |
|
|
475 |
=========================== ===================== |
|
476 |
Return Code Description |
|
477 |
=========================== ===================== |
|
478 |
404 Unknown or expired access token or the access token does not belong to the specified scope |
|
479 |
=========================== ===================== |
b/docs/compute-api-guide.rst | ||
---|---|---|
1 |
.. _compute-api-guide: |
|
2 |
|
|
3 |
API Guide |
|
4 |
********* |
|
5 |
|
|
6 |
`Cyclades <cyclades.html>`_ is the Compute Service of `Synnefo |
|
7 |
<http://www.synnefo.org>`_. The Cyclades API tries to be as close to the |
|
8 |
`OpenStack Compute API v2 |
|
9 |
<http://docs.openstack.org/api/openstack-compute/2/content>`_ as possible. |
|
10 |
|
|
11 |
This document's goals are: |
|
12 |
|
|
13 |
* Define the Cyclades/Compute REST API |
|
14 |
* Clarify the differences between Cyclades and OpenStack/Compute |
|
15 |
|
|
16 |
Users and developers who wish to access Cyclades through its REST API are |
|
17 |
advised to use the `kamaki <http://www.synnefo.org/docs/kamaki/latest/index.html>`_ command-line |
|
18 |
client and associated python library, instead of making direct calls. |
|
19 |
|
|
20 |
Overview |
|
21 |
======== |
|
22 |
|
|
23 |
* OpenStack does not define if requests for invalid URLs should return 404 or a |
|
24 |
* Fault. We return a BadRequest Fault. |
|
25 |
* OpenStack does not define if requests with a wrong HTTP method should return |
|
26 |
* 405 or a Fault. We return a BadRequest Fault. |
|
27 |
|
|
28 |
General API Information |
|
29 |
======================= |
|
30 |
|
|
31 |
Authentication |
|
32 |
-------------- |
|
33 |
|
|
34 |
All requests use the same authentication method: an ``X-Auth-Token`` header is |
|
35 |
passed to the servive, which is used to authenticate the user and retrieve user |
|
36 |
related information. No other user details are passed through HTTP. |
|
37 |
|
|
38 |
Efficient Polling with the Changes-Since Parameter |
|
39 |
-------------------------------------------------- |
|
40 |
|
|
41 |
* Effectively limit support of the changes-since parameter in **List Servers** |
|
42 |
and **List Images**. |
|
43 |
|
|
44 |
* Assume that garbage collection of deleted servers will only affect servers |
|
45 |
deleted ``POLL_TIME`` seconds (default: 3600) in the past or earlier. Else |
|
46 |
loose the information of a server getting deleted. |
|
47 |
|
|
48 |
* Images do not support a deleted state, so deletions cannot be tracked. |
|
49 |
|
|
50 |
Limitations |
|
51 |
----------- |
|
52 |
|
|
53 |
* Version MIME type and vesionless requests are not currently supported. |
|
54 |
|
|
55 |
* Cyclades only supports JSON Requests and JSON/XML Responses. XML Requests are |
|
56 |
currently not supported. |
|
57 |
|
|
58 |
* Optional content compression support is currently not supported. |
|
59 |
|
|
60 |
* To prevent abuse, HTTP sessions have a timeout of 20 seconds before being |
|
61 |
closed. |
|
62 |
|
|
63 |
* Full URI references and ``self`` and ``bookmark`` links are not supported. |
|
64 |
|
|
65 |
* Pagination is currently not supported. |
|
66 |
|
|
67 |
* Cached responses are currently not supported. |
|
68 |
|
|
69 |
* Limits are currently not supported. |
|
70 |
|
|
71 |
* Extensions are currently not supported. |
|
72 |
|
|
73 |
|
|
74 |
API Operations |
|
75 |
============== |
|
76 |
|
|
77 |
Servers |
|
78 |
------- |
|
79 |
|
|
80 |
=================================================== ========================================= ====== ======== ========== |
|
81 |
Description URI Method Cyclades OS/Compute |
|
82 |
=================================================== ========================================= ====== ======== ========== |
|
83 |
`List <#list-servers>`_ ``/servers`` GET ✔ ✔ |
|
84 |
\ ``/servers/detail`` GET ✔ ✔ |
|
85 |
`Create <#create-server>`_ ``/servers`` POST ✔ ✔ |
|
86 |
`Get Stats <#get-server-stats>`_ ``/servers/<server-id>/stats`` GET ✔ **✘** |
|
87 |
`Get Diagnostics <#get-server-diagnostics>`_ ``/servers/<server-id>/diagnostics`` GET ✔ **✘** |
|
88 |
`Get Details <#get-server-details>`_ ``/servers/<server id>`` GET ✔ ✔ |
|
89 |
`Rename <#rename-server>`_ ``/servers/<server id>`` PUT ✔ ✔ |
|
90 |
`Delete <#delete-server>`_ ``/servers/<server id>`` DELETE ✔ ✔ |
|
91 |
`List Addresses <#list-server-addresses>`_ ``/servers/<server id>/ips`` GET ✔ ✔ |
|
92 |
`Get NICs by Net <#get-server-nics-by-network>`_ ``/servers/<server id>/ips/<network id>`` GET ✔ ✔ |
|
93 |
`List Metadata <#list-server-metadata>`_ ``/servers/<server-id>/metadata`` GET ✔ ✔ |
|
94 |
`Update Metadata <#set-update-server-metadata>`_ ``/servers/<server-id>/metadata`` PUT **✘** ✔ |
|
95 |
\ ``/servers/<server-id>/metadata`` POST ✔ ✔ |
|
96 |
`Get Meta Item <#get-server-metadata-item>`_ ``/servers/<server-id>/metadata/<key>`` GET ✔ ✔ |
|
97 |
`Update Meta Item <#update-server-metadatum-item>`_ ``/servers/<server-id>/metadata/<key>`` PUT ✔ ✔ |
|
98 |
`Delete Meta Item <#delete-server-metadatum>`_ ``/servers/<server-id>/metadata/<key>`` DELETE ✔ ✔ |
|
99 |
=================================================== ========================================= ====== ======== ========== |
|
100 |
|
|
101 |
List Servers |
|
102 |
............ |
|
103 |
|
|
104 |
List all virtual servers owned by the user. |
|
105 |
|
|
106 |
.. rubric:: Request |
|
107 |
|
|
108 |
=================== ====== ======== ========== |
|
109 |
URI Method Cyclades OS/Compute |
|
110 |
=================== ====== ======== ========== |
|
111 |
``/servers`` GET ✔ ✔ |
|
112 |
``/servers/detail`` GET ✔ ✔ |
|
113 |
=================== ====== ======== ========== |
|
114 |
|
|
115 |
* Both requests return a list of servers. The first returns just ``id``, |
|
116 |
``name`` and ``links``, while the second returns the full collections of |
|
117 |
server attributes. |
|
118 |
|
|
119 |
| |
|
120 |
|
|
121 |
============== ========================= ======== ========== |
|
122 |
Request Header Value Cyclades OS/Compute |
|
123 |
============== ========================= ======== ========== |
|
124 |
X-Auth-Token User authentication token required required |
|
125 |
============== ========================= ======== ========== |
|
126 |
|
|
127 |
| |
|
128 |
|
|
129 |
================= =================================== ======== ========== |
|
130 |
Request Parameter Value Cyclades OS/Compute |
|
131 |
================= =================================== ======== ========== |
|
132 |
json Respond in json default **✘** |
|
133 |
xml Respond in xml ✔ **✘** |
|
134 |
changes-since Servers delete since that timestamp ✔ ✔ |
|
135 |
image Image reference **✘** ✔ |
|
136 |
flavor VM flavor reference **✘** ✔ |
|
137 |
server Server flavor reference **✘** ✔ |
|
138 |
status Server status **✘** ✔ |
|
139 |
marker Last list last ID **✘** ✔ |
|
140 |
limit Page size **✘** ✔ |
|
141 |
================= =================================== ======== ========== |
|
142 |
|
|
143 |
* **json** and **xml** parameters are mutually exclusive. If none supported, |
|
144 |
the response will be formated in json. |
|
145 |
|
|
146 |
* **status** refers to the `server status <#status-ref>`_ |
|
147 |
|
|
148 |
* **changes-since** must be an ISO8601 date string |
|
149 |
|
|
150 |
.. note:: Request body should be empty |
|
151 |
|
|
152 |
.. rubric:: Response |
|
153 |
|
|
154 |
=========================== ===================== |
|
155 |
Return Code Description |
|
156 |
=========================== ===================== |
|
157 |
200 (OK) Request succeeded |
|
158 |
304 (No servers since date) Can be returned if ``changes-since`` is given |
|
159 |
400 (Bad Request) Invalid or malformed ``changes-since`` parameter |
|
160 |
401 (Unauthorized) Missing or expired user token |
|
161 |
403 (Forbidden) User is not allowed to perform this operation |
|
162 |
500 (Internal Server Error) The request cannot be completed because of an |
|
163 |
\ internal error |
|
164 |
503 (Service Unavailable) The server is not currently available |
|
165 |
=========================== ===================== |
|
166 |
|
|
167 |
| |
|
168 |
|
|
169 |
Response body contents:: |
|
170 |
|
|
171 |
servers: [ |
|
172 |
{ |
|
173 |
<server attribute>: <value>, |
|
174 |
... |
|
175 |
}, ... |
|
176 |
] |
|
177 |
|
|
178 |
================= ====================== ======== ========== |
|
179 |
Server Attributes Description Cyclades OS/Compute |
|
180 |
================= ====================== ======== ========== |
|
181 |
id The server id ✔ ✔ |
|
182 |
name The server name ✔ ✔ |
|
183 |
links Reference links ✔ ✔ |
|
184 |
hostId Server playground empty ✔ |
|
185 |
created Creation date ✔ ✔ |
|
186 |
updated Creation date ✔ ✔ |
|
187 |
flavor The flavor id ✔ ✔ |
|
188 |
image The image id ✔ ✔ |
|
189 |
progress Build progress ✔ ✔ |
|
190 |
status Server status ✔ ✔ |
|
191 |
attachments Network interfaces ✔ **✘** |
|
192 |
addresses Network interfaces **✘** ✔ |
|
193 |
metadata Server custom metadata ✔ ✔ |
|
194 |
================= ====================== ======== ========== |
|
195 |
|
|
196 |
* **hostId** is not used in Cyclades, but is returned as an empty string for |
|
197 |
compatibility |
|
198 |
|
|
199 |
* **progress** is changing while the server is building up and has values |
|
200 |
between 0 and 100. When it reaches 100 the server is built. |
|
201 |
|
|
202 |
* **status** refers to `the status <#status-ref>`_ of the server |
|
203 |
|
|
204 |
* **metadata** are custom key:value pairs used to specify various attributes of |
|
205 |
the VM (e.g. OS, super user, etc.) |
|
206 |
|
|
207 |
* **attachments** in Cyclades are lists of network interfaces (nics). |
|
208 |
**Attachments** are different to OS/Compute's **addresses**. The former is a |
|
209 |
list of the server's `network interface connections <#nic-ref>`_ while the |
|
210 |
later is just a list of networks. Thus, a Cyclades virtual server may be |
|
211 |
connected to the same network through more than one distinct network |
|
212 |
interfaces (e.g. server 43 is connected to network 101 with nic-43-1 and |
|
213 |
nic-43-2 in the example bellow). |
|
214 |
|
|
215 |
* **Network Interfaces (NICs)** contain information about a server's connection |
|
216 |
to a network. Each NIC is identified by an id of the form |
|
217 |
nic-<server-id>-<ordinal-number>. More details can be found `here |
|
218 |
<#nic-ref>`_. |
|
219 |
|
|
220 |
|
|
221 |
*Example List Servers: JSON (regular)* |
|
222 |
|
|
223 |
.. code-block:: javascript |
|
224 |
|
|
225 |
[ |
|
226 |
{ |
|
227 |
"links": [ |
|
228 |
{ |
|
229 |
"href": "https://example.org/compute/v2.0/servers/42", |
|
230 |
"rel": "self" |
|
231 |
}, |
|
232 |
{ |
|
233 |
"href": "https://example.org/compute/v2.0/servers/42", |
|
234 |
"rel": "bookmark" |
|
235 |
} |
|
236 |
], |
|
237 |
"id": "42", |
|
238 |
"name": "My Server", |
|
239 |
}, { |
|
240 |
"links": [ |
|
241 |
{ |
|
242 |
"href": "https://example.org/compute/v2.0/servers/43", |
|
243 |
"rel": "self" |
|
244 |
}, |
|
245 |
{ |
|
246 |
"href": "https://example.org/compute/v2.0/servers/43", |
|
247 |
"rel": "bookmark" |
|
248 |
} |
|
249 |
], |
|
250 |
"id": "43", |
|
251 |
"name": "My Server", |
|
252 |
} |
|
253 |
] |
|
254 |
|
|
255 |
*Example List Servers: JSON (detail)* |
|
256 |
|
|
257 |
.. code-block:: javascript |
|
258 |
|
|
259 |
[ |
|
260 |
{ |
|
261 |
"attachments": [ |
|
262 |
{ |
|
263 |
"id": "nic-42-0", |
|
264 |
"network_id": "101", |
|
265 |
"mac_address": "aa:00:00:49:2e:7e", |
|
266 |
"firewallProfile": "DISABLED", |
|
267 |
"ipv4": "192.168.4.5", |
|
268 |
"ipv6": "2001:648:2ffc:1222:a800:ff:fef5:3f5b" |
|
269 |
} |
|
270 |
], |
|
271 |
"links": [ |
|
272 |
{ |
|
273 |
"href": "https://example.org/compute/v2.0/servers/42", |
|
274 |
"rel": "self" |
|
275 |
}, |
|
276 |
{ |
|
277 |
"href": "https://example.org/compute/v2.0/servers/42", |
|
278 |
"rel": "bookmark" |
|
279 |
} |
|
280 |
], |
|
281 |
"created': '2011-04-19T10:18:52.085737+00:00', |
|
282 |
"flavor": { |
|
283 |
"id": 1", |
|
284 |
"links": [ |
|
285 |
{ |
|
286 |
"href": "https://example.org/compute/v2.0/flavors/1", |
|
287 |
"rel": "self" |
|
288 |
}, |
|
289 |
{ |
|
290 |
"href": "https://example.org/compute/v2.0/flavors/1", |
|
291 |
"rel": "bookmark" |
|
292 |
} |
|
293 |
] |
|
294 |
|
|
295 |
}, |
|
296 |
"hostId": "", |
|
297 |
"id": "42", |
|
298 |
"image": { |
|
299 |
"id": "im4g3-1d", |
|
300 |
"links": [ |
|
301 |
{ |
|
302 |
"href": "https://example.org/compute/v2.0/images/im4g3-1d", |
|
303 |
"rel": "self" |
|
304 |
}, |
|
305 |
{ |
|
306 |
"href": "https://example.org/compute/v2.0/images/im4g3-1d", |
|
307 |
"rel": "bookmark" |
|
308 |
}, |
|
309 |
{ |
|
310 |
"href": "https://example.org/image/v1.0/images/im4g3-1d", |
|
311 |
"rel": "alternate" |
|
312 |
} |
|
313 |
] |
|
314 |
}, |
|
315 |
"metadata": {{"foo": "bar"}, |
|
316 |
"name": "My Server", |
|
317 |
"status": "ACTIVE", |
|
318 |
"updated": "2011-05-29T14:07:07.037602+00:00" |
|
319 |
}, { |
|
320 |
"attachments": [ |
|
321 |
{ |
|
322 |
"id": "nic-43-0", |
|
323 |
"mac_address": "aa:00:00:91:2f:df", |
|
324 |
"network_id": "1", |
|
325 |
"ipv4": "192.168.32.2" |
|
326 |
}, { |
|
327 |
"id": "nic-43-1", |
|
328 |
"network_id": "101", |
|
329 |
"mac_address": "aa:00:00:49:2g:7f", |
|
330 |
"firewallProfile": "DISABLED", |
|
331 |
"ipv4": "192.168.32.6", |
|
332 |
"ipv6": "2001:648:2ffc:1222:a800:ff:fef5:3f5c' |
|
333 |
}, { |
|
334 |
"id": "nic-43-2", |
|
335 |
"network_id": "101", |
|
336 |
"mac_address": "aa:00:00:51:2h:7f", |
|
337 |
"firewallProfile": "DISABLED", |
|
338 |
"ipv4": "192.168.32.7", |
|
339 |
"ipv6": "2001:638:2eec:1222:a800:ff:fef5:3f5c" |
|
340 |
} |
|
341 |
], |
|
342 |
"links": [ |
|
343 |
{ |
|
344 |
"href": "https://example.org/compute/v2.0/servers/43", |
|
345 |
"rel": "self" |
|
346 |
}, |
|
347 |
{ |
|
348 |
"href": "https://example.org/compute/v2.0/servers/43", |
|
349 |
"rel": "bookmark" |
|
350 |
} |
|
351 |
], |
|
352 |
"created": "2011-05-02T20:51:08.527759+00:00", |
|
353 |
"flavor": { |
|
354 |
"id": 1", |
|
355 |
"links": [ |
|
356 |
{ |
|
357 |
"href": "https://example.org/compute/v2.0/flavors/1", |
|
358 |
"rel": "self" |
|
359 |
}, |
|
360 |
{ |
|
361 |
"href": "https://example.org/compute/v2.0/flavors/1", |
|
362 |
"rel": "bookmark" |
|
363 |
} |
|
364 |
] |
|
365 |
|
|
366 |
}, |
|
367 |
"hostId": "", |
|
368 |
"id": "43", |
|
369 |
"image": { |
|
370 |
"id": "im4g3-1d", |
|
371 |
"links": [ |
|
372 |
{ |
|
373 |
"href": "https://example.org/compute/v2.0/images/im4g3-1d", |
|
374 |
"rel": "self" |
|
375 |
}, |
|
376 |
{ |
|
377 |
"href": "https://example.org/compute/v2.0/images/im4g3-1d", |
|
378 |
"rel": "bookmark" |
|
379 |
}, |
|
380 |
{ |
|
381 |
"href": "https://example.org/image/v1.0/images/im4g3-1d", |
|
382 |
"rel": "alternate" |
|
383 |
} |
|
384 |
] |
|
385 |
}, |
|
386 |
"name": "Other Server", |
|
387 |
"description": "A sample server to showcase server requests", |
|
388 |
"progress": "0", |
|
389 |
"status": "ACTIVE", |
|
390 |
"updated": "2011-05-29T14:59:11.267087+00:00" |
|
391 |
} |
|
392 |
] |
|
393 |
|
|
394 |
|
|
395 |
Create Server |
|
396 |
............. |
|
397 |
|
|
398 |
Create a new virtual server |
|
399 |
|
|
400 |
.. rubric:: Request |
|
401 |
|
|
402 |
============ ====== ======== ========== |
|
403 |
URI Method Cyclades OS/Compute |
|
404 |
============ ====== ======== ========== |
|
405 |
``/servers`` POST ✔ ✔ |
|
406 |
============ ====== ======== ========== |
|
407 |
|
|
408 |
| |
|
409 |
|
|
410 |
============== ========================= ======== ========== |
|
411 |
Request Header Value Cyclades OS/Compute |
|
412 |
============== ========================= ======== ========== |
|
413 |
X-Auth-Token User authentication token required required |
|
414 |
Content-Type Type or request body required required |
|
415 |
Content-Length Length of request body required required |
|
416 |
============== ========================= ======== ========== |
|
417 |
|
|
418 |
*Example Request Headers*:: |
|
419 |
|
|
420 |
X-Auth-Token: z31uRXUn1LZy45p1r7V== |
|
421 |
Content-Type: application/json |
|
422 |
Content-Length: 735 |
|
423 |
|
|
424 |
| |
|
425 |
|
|
426 |
================= =============== |
|
427 |
Request Parameter Value |
|
428 |
================= =============== |
|
429 |
json Respond in json |
|
430 |
xml Respond in xml |
|
431 |
================= =============== |
|
432 |
|
|
433 |
Request body contents:: |
|
434 |
|
|
435 |
server: { |
|
436 |
<server attribute>: <value>, |
|
437 |
... |
|
438 |
personality: [ |
|
439 |
{ |
|
440 |
<personality attribute>: <value>, |
|
441 |
... |
|
442 |
}, |
|
443 |
... |
|
444 |
], |
|
445 |
... |
|
446 |
} |
|
447 |
|
|
448 |
=========== ==================== ======== ========== |
|
449 |
Attributes Description Cyclades OS/Compute |
|
450 |
=========== ==================== ======== ========== |
|
451 |
name The server name ✔ ✔ |
|
452 |
imageRef Image id ✔ ✔ |
|
453 |
flavorRef Resources flavor ✔ ✔ |
|
454 |
personality Personality contents ✔ ✔ |
|
455 |
metadata Custom metadata ✔ ✔ |
|
456 |
=========== ==================== ======== ========== |
|
457 |
|
|
458 |
* **name** can be any string |
|
459 |
|
|
460 |
* **imageRed** and **flavorRed** should refer to existing images and hardware |
|
461 |
flavors accessible by the user |
|
462 |
|
|
463 |
* **metadata** are ``key``:``value`` pairs of custom server-specific metadata. |
|
464 |
There are no semantic limitations. |
|
465 |
|
|
466 |
* **personality** (optional) is a list of personality injections. A personality |
|
467 |
injection is a way to add a file into a virtual server while creating it. |
|
468 |
Each change modifies/creates a file on the virtual server. The injected data |
|
469 |
(``contents``) should not exceed 10240 *bytes* in size and must be base64 |
|
470 |
encoded. The file mode should be a number, not a string. A personality |
|
471 |
injection contains the following attributes: |
|
472 |
|
|
473 |
====================== =================== ======== ========== |
|
474 |
Personality Attributes Description Cyclades OS/Compute |
|
475 |
====================== =================== ======== ========== |
|
476 |
path File path on server ✔ ✔ |
|
477 |
contents Data to inject ✔ ✔ |
|
478 |
group User group ✔ **✘** |
|
479 |
mode File access mode ✔ **✘** |
|
480 |
owner File owner ✔ **✘** |
|
481 |
====================== =================== ======== ========== |
|
482 |
|
|
483 |
*Example Create Server Request: JSON* |
|
484 |
|
|
485 |
.. code-block:: javascript |
|
486 |
|
|
487 |
{ |
|
488 |
"server": { |
|
489 |
"name": "My Server Name: Example Name", |
|
490 |
"imageRef": "da7a211f-...-f901ce81a3e6", |
|
491 |
"flavorRef": 289, |
|
492 |
"personality": [ |
|
493 |
{ |
|
494 |
"path": "/Users/myusername/personlities/example1.file", |
|
495 |
"contents": "some data to inject", |
|
496 |
"group": "remotely-set user group", |
|
497 |
"mode": 0600, |
|
498 |
"owner": "ausername" |
|
499 |
}, { |
|
500 |
"path": "/Users/myusername/personlities/example2.file", |
|
501 |
"contents": "some more data to inject", |
|
502 |
"group": "", |
|
503 |
"mode": 0777, |
|
504 |
"owner": "anotherusername" |
|
505 |
} |
|
506 |
], |
|
507 |
"metadata": { |
|
508 |
"EloquentDescription": "Example server with personality", |
|
509 |
"ShortDescription": "Trying VMs" |
|
510 |
} |
|
511 |
} |
|
512 |
} |
|
513 |
|
|
514 |
.. rubric:: Response |
|
515 |
|
|
516 |
=========================== ===================== |
|
517 |
Return Code Description |
|
518 |
=========================== ===================== |
|
519 |
200 (OK) Request succeeded |
|
520 |
400 (Bad Request) Malformed request data |
|
521 |
401 (Unauthorized) Missing or expired user token |
|
522 |
403 (Forbidden) User is not allowed to perform this operation |
|
523 |
404 (Not Found) Image or Flavor not found |
|
524 |
413 (Over Limit) Exceeded some resource limit (#VMs, personality |
|
525 |
size, etc.) |
|
526 |
415 (Bad Media Type) |
|
527 |
500 (Internal Server Error) The request cannot be completed because of an |
|
528 |
\ internal error |
|
529 |
503 (Service Unavailable) No available backends or service currently |
|
530 |
\ unavailable |
|
531 |
=========================== ===================== |
|
532 |
|
|
533 |
| |
|
534 |
|
|
535 |
Response body contents:: |
|
536 |
|
|
537 |
server: { |
|
538 |
<server attribute>: <value>, |
|
539 |
... |
|
540 |
} |
|
541 |
|
|
542 |
Server attributes are `listed here <#server-ref>`_. |
|
543 |
|
|
544 |
*Example Create Server Response: JSON* |
|
545 |
|
|
546 |
.. code-block:: javascript |
|
547 |
|
|
548 |
{ |
|
549 |
"server": { |
|
550 |
"addresses": |
|
551 |
"id": 28130, |
|
552 |
"links": [ |
|
553 |
{ |
|
554 |
"href": "https://example.org/compute/v2.0/servers/42", |
|
555 |
"rel": "self" |
|
556 |
}, |
|
557 |
{ |
|
558 |
"href": "https://example.org/compute/v2.0/servers/42", |
|
559 |
"rel": "bookmark" |
|
560 |
} |
|
561 |
], |
|
562 |
|
|
563 |
"image": { |
|
564 |
"id": im4g3-1d |
|
565 |
"links": [ |
|
566 |
{ |
|
567 |
"href": "https://example.org/compute/v2.0/images/im4g3-1d" |
|
568 |
"rel": "self" |
|
569 |
}, { |
|
570 |
"href": "https://example.org/compute/v2.0/images/im4g3-1d" |
|
571 |
"rel": "bookmark" |
|
572 |
}, { |
|
573 |
"href": "https://example.org/image/v1.0/images/im4g3-1d" |
|
574 |
"rel": "alternate" |
|
575 |
} |
|
576 |
] |
|
577 |
}, |
|
578 |
"flavor": { |
|
579 |
"id": 289 |
|
580 |
"links": [ |
|
581 |
{ |
|
582 |
"href": "https://example.org/compute/v2.0/flavors/289" |
|
583 |
"rel": "self" |
|
584 |
}, { |
|
585 |
"href": "https://example.org/compute/v2.0/flavors/289" |
|
586 |
"rel": "bookmark" |
|
587 |
} |
|
588 |
] |
|
589 |
}, |
|
590 |
"status": "BUILD", |
|
591 |
"updated": "2013-04-10T13:52:18.140686+00:00", |
|
592 |
"hostId": "", |
|
593 |
"name": "My Server Name: Example Name", |
|
594 |
"created": "2013-04-10T13:52:17.085402+00:00", |
|
595 |
"adminPass": "fKCqlZe2at", |
|
596 |
"suspended": false, |
|
597 |
"progress": 0 |
|
598 |
"metadata": { |
|
599 |
"EloquentDescription": "Example server with personality", |
|
600 |
"ShortDescription": "Trying VMs" |
|
601 |
} |
|
602 |
} |
|
603 |
} |
|
604 |
|
|
605 |
*Example Create Server Response: XML* |
|
606 |
|
|
607 |
.. code-block:: xml |
|
608 |
|
|
609 |
<?xml version="1.0" encoding="UTF-8"?> |
|
610 |
<server xmlns="http://docs.openstack.org/compute/api/v1.1"\ |
|
611 |
xmlns:atom="http://www.w3.org/2005/Atom" |
|
612 |
id="1" |
|
613 |
status="BUILD" |
|
614 |
hostId="", |
|
615 |
name="My Server Name: Example Name" |
|
616 |
created="2013-04-10T13:52:17.085402+00:00" |
|
617 |
adminPass="fKCqlZe2at" |
|
618 |
suspended="false" |
|
619 |
progress="0" |
|
620 |
... |
|
621 |
/> |
|
622 |
|
|
623 |
Get Server Stats |
|
624 |
................ |
|
625 |
|
|
626 |
.. note:: This operation is not part of OS/Compute v2. |
|
627 |
|
|
628 |
This operation returns URLs of graphs showing CPU and Network statistics. |
|
629 |
|
|
630 |
.. rubric:: Request |
|
631 |
|
|
632 |
============================== ====== ======== ========== |
|
633 |
URI Method Cyclades OS/Compute |
|
634 |
============================== ====== ======== ========== |
|
635 |
``/servers/<server-id>/stats`` GET ✔ **✘** |
|
636 |
============================== ====== ======== ========== |
|
637 |
|
|
638 |
* **server-id** is the identifier of the virtual server |
|
639 |
|
|
640 |
| |
|
641 |
|
|
642 |
============== ========================= ======== ========== |
|
643 |
Request Header Value Cyclades OS/Compute |
|
644 |
============== ========================= ======== ========== |
|
645 |
X-Auth-Token User authentication token required required |
|
646 |
============== ========================= ======== ========== |
|
647 |
|
|
648 |
| |
|
649 |
|
|
650 |
================= =============== |
|
651 |
Request Parameter Value |
|
652 |
================= =============== |
|
653 |
json Respond in json |
|
654 |
xml Respond in xml |
|
655 |
================= =============== |
|
656 |
|
|
657 |
* **json** and **xml** parameters are mutually exclusive. If none supported, |
|
658 |
the response will be formated in json. |
|
659 |
|
|
660 |
.. note:: Request body should be empty |
|
661 |
|
|
662 |
.. rubric:: Response |
|
663 |
|
|
664 |
=========================== ===================== |
|
665 |
Return Code Description |
|
666 |
=========================== ===================== |
|
667 |
200 (OK) Request succeeded |
|
668 |
400 (Bad Request) Invalid server ID or Server deleted |
|
669 |
401 (Unauthorized) Missing or expired user token |
|
670 |
403 (Forbidden) Administratively suspended server |
|
671 |
404 (Not Found) Server not found |
|
672 |
500 (Internal Server Error) The request cannot be completed because of an |
|
673 |
\ internal error |
|
674 |
503 (Service Unavailable) The server is not currently available |
|
675 |
=========================== ===================== |
|
676 |
|
|
677 |
| |
|
678 |
|
|
679 |
Response body contents:: |
|
680 |
|
|
681 |
stats: {<parameter>: <value> } |
|
682 |
|
|
683 |
============= ====================== |
|
684 |
Parameter Description |
|
685 |
============= ====================== |
|
686 |
serverRef Server ID |
|
687 |
refresh Refresh frequency |
|
688 |
cpuBar Latest CPU load graph URL |
|
689 |
cpuTimeSeries CPU load / time graph URL |
|
690 |
netBar Latest Network load graph URL |
|
691 |
netTimeSeries Network load / time graph URL |
|
692 |
============= ====================== |
|
693 |
|
|
694 |
* **refresh** is the recommended sampling rate |
|
695 |
|
|
696 |
*Example Get Server Stats Response: JSON* |
|
697 |
|
|
698 |
.. code-block:: javascript |
|
699 |
|
|
700 |
{ |
|
701 |
"stats": { |
|
702 |
"serverRef": 1, |
|
703 |
"refresh": 60, |
|
704 |
"cpuBar": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-bar.png", |
|
705 |
"cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-ts.png", |
|
706 |
"netBar": "http://stats.okeanos.grnet.gr/b9a...048c/net-bar.png", |
|
707 |
"netTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/net-ts.png" |
|
708 |
} |
|
709 |
} |
|
710 |
|
|
711 |
*Example Get Network Details Response: XML* |
|
712 |
|
|
713 |
.. code-block:: xml |
|
714 |
|
|
715 |
<?xml version="1.0" encoding="UTF-8"?> |
|
716 |
<stats xmlns="http://docs.openstack.org/compute/api/v1.1"\ |
|
717 |
xmlns:atom="http://www.w3.org/2005/Atom" |
|
718 |
serverRef="1" |
|
719 |
refresh="60" |
|
720 |
cpuBar="https://www.example.com/stats/snf-42/cpu-bar/", |
|
721 |
netTimeSeries="https://example.com/stats/snf-42/net-ts/", |
|
722 |
netBar="https://example.com/stats/snf-42/net-bar/", |
|
723 |
cpuTimeSeries="https://www.example.com/stats/snf-42/cpu-ts/" |
|
724 |
</stats> |
|
725 |
|
|
726 |
Get Server Diagnostics |
|
727 |
...................... |
|
728 |
|
|
729 |
.. note:: This operation is not part of OS/Compute v2. |
|
730 |
|
|
731 |
This operation returns diagnostic information (logs) for a server. |
|
732 |
|
|
733 |
.. rubric:: Request |
|
734 |
|
|
735 |
==================================== ====== ======== ========== |
|
736 |
URI Method Cyclades OS/Compute |
|
737 |
==================================== ====== ======== ========== |
|
738 |
``/servers/<server-id>/diagnostics`` GET ✔ **✘** |
|
739 |
==================================== ====== ======== ========== |
|
740 |
|
|
741 |
* **server-id** is the identifier of the virtual server |
|
742 |
|
|
743 |
| |
|
744 |
|
|
745 |
============== ========================= ======== ========== |
|
746 |
Request Header Value Cyclades OS/Compute |
|
747 |
============== ========================= ======== ========== |
|
748 |
X-Auth-Token User authentication token required required |
|
749 |
============== ========================= ======== ========== |
|
750 |
|
|
751 |
.. note:: Request parameters should be empty |
|
752 |
|
|
753 |
.. note:: Request body should be empty |
|
754 |
|
|
755 |
.. rubric:: Response |
|
756 |
|
|
757 |
=========================== ===================== |
|
758 |
Return Code Description |
|
759 |
=========================== ===================== |
|
760 |
200 (OK) Request succeeded |
|
761 |
400 (Bad Request) Invalid server ID or Server deleted |
|
762 |
401 (Unauthorized) Missing or expired user token |
|
763 |
403 (Forbidden) Administratively suspended server |
|
764 |
404 (Not Found) Server not found |
|
765 |
500 (Internal Server Error) The request cannot be completed because of an |
|
766 |
\ internal error |
|
767 |
503 (Service Unavailable) The server is not currently available |
|
768 |
=========================== ===================== |
|
769 |
|
|
770 |
| |
|
771 |
|
|
772 |
Response body contents:: |
|
773 |
|
|
774 |
[ |
|
775 |
{ |
|
776 |
<diagnostic attribute}: <value>, |
|
777 |
... |
|
778 |
}, { |
|
779 |
<diagnostic attribute}: <value>, |
|
780 |
... |
|
781 |
}, |
|
782 |
... |
|
783 |
] |
|
784 |
|
|
785 |
==================== =========== |
|
786 |
Diagnostic attribute Description |
|
787 |
==================== =========== |
|
788 |
level Debug level |
|
789 |
created Log entry timestamp |
|
790 |
source Log source proccess |
|
791 |
source_date Log source date |
|
792 |
message Log description |
|
793 |
details Detailed log description |
|
794 |
==================== =========== |
|
795 |
|
|
796 |
*Example Get Server Diagnostics Response: JSON* |
|
797 |
|
|
798 |
.. code-block:: javascript |
|
799 |
|
|
800 |
[ |
|
801 |
{ |
|
802 |
"level": "DEBUG", |
|
803 |
"created": "2013-04-09T15:25:53.965144+00:00", |
|
804 |
"source": "image-helper-task-start", |
|
805 |
"source_date": "2013-04-09T15:25:53.954695+00:00", |
|
806 |
"message": "FixPartitionTable", |
|
807 |
"details": null |
|
808 |
}, { |
|
809 |
"level": "DEBUG", |
|
810 |
"created": "2013-04-09T15:25:46.413718+00:00", |
|
811 |
"source": "image-info", |
|
812 |
"source_date": "2013-04-09T15:25:46.404477+00:00", |
|
813 |
"message": "Starting customization VM...", |
|
814 |
"details": null |
|
815 |
}, { |
|
816 |
"level": "DEBUG", |
|
817 |
"created": "2013-04-09T15:25:46.207038+00:00", |
|
818 |
"source": "image-info", |
|
819 |
"source_date": "2013-04-09T15:25:46.197183+00:00", |
|
820 |
"message": "Image copy finished.", |
|
821 |
"details": "All operations finished as they should. No errors reported." |
|
822 |
} |
|
823 |
] |
|
824 |
|
|
825 |
Get Server Details |
|
826 |
.................. |
|
827 |
|
|
828 |
This operation returns detailed information for a virtual server |
|
829 |
|
|
830 |
.. rubric:: Request |
|
831 |
|
|
832 |
======================== ====== ======== ========== |
|
833 |
URI Method Cyclades OS/Compute |
|
834 |
======================== ====== ======== ========== |
|
835 |
``/servers/<server id>`` GET ✔ ✔ |
|
836 |
======================== ====== ======== ========== |
|
837 |
|
|
838 |
* **server-id** is the identifier of the virtual server |
|
839 |
|
|
840 |
| |
|
841 |
|
|
842 |
============== ========================= ======== ========== |
|
843 |
Request Header Value Cyclades OS/Compute |
|
844 |
============== ========================= ======== ========== |
|
845 |
X-Auth-Token User authentication token required required |
|
846 |
============== ========================= ======== ========== |
|
847 |
|
|
848 |
.. note:: Request parameters should be empty |
|
849 |
|
|
850 |
.. note:: Request body should be empty |
|
851 |
|
|
852 |
.. rubric:: Response |
|
853 |
|
|
854 |
=========================== ===================== |
|
855 |
Return Code Description |
|
856 |
=========================== ===================== |
|
857 |
200 (OK) Request succeeded |
|
858 |
400 (Bad Request) Malformed server id |
|
859 |
401 (Unauthorized) Missing or expired user token |
|
860 |
403 (Forbidden) Administratively suspended server |
|
861 |
404 (Not Found) Server not found |
|
862 |
500 (Internal Server Error) The request cannot be completed because of an |
|
863 |
\ internal error |
|
864 |
503 (Service Unavailable) No available backends or service currently |
|
865 |
\ unavailable |
|
866 |
=========================== ===================== |
|
867 |
|
|
868 |
| |
|
869 |
|
|
870 |
Response body contents:: |
|
871 |
|
|
872 |
server: { |
|
873 |
<server attribute>: <value>, |
|
874 |
... |
|
875 |
} |
|
876 |
|
|
877 |
================= ====================== ======== ========== |
|
878 |
Server Attributes Description Cyclades OS/Compute |
|
879 |
================= ====================== ======== ========== |
|
880 |
id The server id ✔ ✔ |
|
881 |
name The server name ✔ ✔ |
|
882 |
hostId Server playground empty ✔ |
|
883 |
created Creation date ✔ ✔ |
|
884 |
updated Creation date ✔ ✔ |
|
885 |
flavor The flavor id ✔ ✔ |
|
886 |
image The image id ✔ ✔ |
|
887 |
progress Build progress ✔ ✔ |
|
888 |
status Server status ✔ ✔ |
|
889 |
suspended If server is suspended ✔ **✘** |
|
890 |
attachments Network interfaces ✔ **✘** |
|
891 |
addresses Network interfaces **✘** ✔ |
|
892 |
metadata Server custom metadata ✔ ✔ |
|
893 |
diagnostics Diagnostic information ✔ **✘** |
|
894 |
================= ====================== ======== ========== |
|
895 |
|
|
896 |
* **hostId** is not used in Cyclades, but is returned as an empty string for |
|
897 |
compatibility |
|
898 |
|
|
899 |
* **progress** is changing while the server is building up and has values |
|
900 |
between 0 and 100. When it reaches 100 the server is built. |
|
901 |
|
|
902 |
* **status** refers to `the status <#status-ref>`_ of the server |
|
903 |
|
|
904 |
* **metadata** are custom key:value pairs used to specify various attributes of |
|
905 |
the VM (e.g. OS, super user, etc.) |
|
906 |
|
|
907 |
* **attachments** in Cyclades are lists of network interfaces (NICs). |
|
908 |
**Attachments** are different to OS/Compute's **addresses**. The former is a |
|
909 |
list of the server's `network interface connections <#nic-ref>`_ while the |
|
910 |
later is just a list of networks. Thus, a Cyclades virtual server may be |
|
911 |
connected to the same network through more than one distinct network |
|
912 |
interfaces. |
|
913 |
|
|
914 |
* **diagnostics** is a list of items that contain key:value information useful |
|
915 |
for diagnosing the server behavior and may be used by the administrators of |
|
916 |
deployed Synnefo setups. |
|
917 |
|
|
918 |
*Example Details for server with id 42042: JSON* |
|
919 |
|
|
920 |
.. code-block:: javascript |
|
921 |
|
|
922 |
{ |
|
923 |
"server": { |
|
924 |
"attachments": [ |
|
925 |
{ |
|
926 |
"network_id": "1888", |
|
927 |
"mac_address": "aa:0c:f5:ad:16:41", |
|
928 |
"firewallProfile": "DISABLED", |
|
929 |
"ipv4": "83.212.112.56", |
|
930 |
"ipv6": "2001:648:2ffc:1119:a80c:f5ff:fead:1641", |
|
931 |
"id": "nic-42042-0" |
|
932 |
} |
|
933 |
], |
|
934 |
"links": [ |
|
935 |
{ |
|
936 |
"href": "https://example.org/compute/v2.0/servers/42031", |
|
937 |
"rel": "self" |
|
938 |
}, |
|
939 |
{ |
|
940 |
"href": "https://example.org/compute/v2.0/servers/42042", |
|
941 |
"rel": "bookmark" |
|
942 |
} |
|
943 |
], |
|
944 |
"created": "2011-05-02T20:51:08.527759+00:00", |
|
945 |
"flavor": { |
|
946 |
"id": 1, |
|
947 |
"links": [ |
|
948 |
{ |
|
949 |
"href": "https://example.org/compute/v2.0/flavors/1", |
|
950 |
"rel": "self" |
|
951 |
}, |
|
952 |
{ |
|
953 |
"href": "https://example.org/compute/v2.0/flavors/1", |
|
954 |
"rel": "bookmark" |
|
955 |
} |
Also available in: Unified diff