| 3 |
3 |
API Guide
|
| 4 |
4 |
*********
|
| 5 |
5 |
|
| 6 |
|
.. todo:: Document the relation of the API to the OpenStack API v1.1.
|
|
6 |
`Cyclades <cyclades.html>`_ is the compute service developed by `GRNET <http://www.grnet.gr>`_ as part of the `synnefo <http://www.synnefo.org>`_ software, that implements an extension of the `OpenStack Compute API <http://docs.openstack.org/api/openstack-compute/2/content>`_.
|
| 7 |
7 |
|
| 8 |
|
This is the guide to the REST API of the synnefo Compute Service.
|
| 9 |
|
It is meant for users wishing to make calls to the REST API directly.
|
|
8 |
This document's goals are:
|
| 10 |
9 |
|
| 11 |
|
The `kamaki <http://docs.dev.grnet.gr/kamaki>`_ command-line client
|
| 12 |
|
and associated python library can be used instead of making direct calls to
|
| 13 |
|
:ref:`cyclades <cyclades>`.
|
|
10 |
* Define the Cyclades/Compute ReST API
|
|
11 |
* Clarify the differences between Cyclades and OOS Compute
|
|
12 |
|
|
13 |
Users and developers who wish to access a synnefo Cyclades service through its ReST API are adviced to use the `kamaki <http://docs.dev.grnet.gr/kamaki>`_ command-line client and associated python library, instead of making direct calls.
|
| 14 |
14 |
|
| 15 |
15 |
Overview
|
| 16 |
16 |
========
|
| ... | ... | |
| 92 |
92 |
* Version MIME type support is missing.
|
| 93 |
93 |
* Versionless requests are not supported.
|
| 94 |
94 |
* We hardcode the ``updated`` field in versions list
|
| 95 |
|
* Deployment note: The Atom metadata need to be fixed
|
|
95 |
* Deployment note: The Atom metadata needs to be fixed
|
| 96 |
96 |
|
| 97 |
97 |
|
| 98 |
98 |
Extensions
|
| ... | ... | |
| 121 |
121 |
List Servers
|
| 122 |
122 |
............
|
| 123 |
123 |
|
| 124 |
|
* **List Servers** returns just ``id`` and ``name`` if details are not
|
| 125 |
|
requested.
|
| 126 |
|
* **List Servers** can return 304 (even though not explicitly stated) when
|
| 127 |
|
``changes-since`` is given.
|
|
124 |
=================== ====== ======== ==========
|
|
125 |
URI Method Cyclades OS Compute
|
|
126 |
=================== ====== ======== ==========
|
|
127 |
``/servers`` GET ✔ ✔
|
|
128 |
``/servers/detail``
|
|
129 |
=================== ====== ======== ==========
|
|
130 |
|
|
131 |
* Both requests return a list of servers. The first returns just ``id`` and ``name``, while the second returns the full set of server attributes.
|
|
132 |
|
|
133 |
================= =================================== ======== ==========
|
|
134 |
Request Parameter Value Cyclades OS Compute
|
|
135 |
================= =================================== ======== ==========
|
|
136 |
changes-since Servers delete since that timestamp ✔ ✔
|
|
137 |
image Image reference **✘** ✔
|
|
138 |
flavor VM flavor reference **✘** ✔
|
|
139 |
server Server flavor reference **✘** ✔
|
|
140 |
status Server status **✘** ✔
|
|
141 |
marker Last list last ID **✘** ✔
|
|
142 |
limit Page size **✘** ✔
|
|
143 |
================= =================================== ======== ==========
|
|
144 |
|
|
145 |
|
|
|
146 |
|
|
147 |
============== ========================= ======== ==========
|
|
148 |
Request Header Value Cyclades OS Compute
|
|
149 |
============== ========================= ======== ==========
|
|
150 |
X-Auth-Token User authentication token required required
|
|
151 |
============== ========================= ======== ==========
|
|
152 |
|
|
153 |
|
|
|
154 |
|
|
155 |
=========================== =====================
|
|
156 |
Return Code Description
|
|
157 |
=========================== =====================
|
|
158 |
200 (OK) Request succeeded
|
|
159 |
304 (No servers since date) Can be returned if ``changes-since`` is given
|
|
160 |
400 (Bad Request) Invalid or malformed ``changes-since`` parameter
|
|
161 |
401 (Unauthorized) Missing or expired user token
|
|
162 |
403 (Unauthorized) User is not allowed to perform this operation
|
|
163 |
500 (Internal Server Error) The request cannot be completed because of an internal error
|
|
164 |
503 (Service Unavailable) The server is not currently available
|
|
165 |
=========================== =====================
|
|
166 |
|
|
167 |
|
|
168 |
The response data format is a list of servers, under the ``servers`` label. A server may have the fields presented bellow (only *id* and *name* if not a detail request)
|
|
169 |
|
|
170 |
================ ====================== ======== ==========
|
|
171 |
Name Description Cyclades OS Compute
|
|
172 |
================ ====================== ======== ==========
|
|
173 |
id The server id ✔ ✔
|
|
174 |
name The server name ✔ ✔
|
|
175 |
hostId Server playground empty ✔
|
|
176 |
created Creation date ✔ ✔
|
|
177 |
updated Creation date ✔ ✔
|
|
178 |
flavorRef The flavor id ✔ **✘**
|
|
179 |
flavor The flavor id **✘** ✔
|
|
180 |
imageRef The image id ✔ **✘**
|
|
181 |
image The image id **✘** ✔
|
|
182 |
progress Build progress ✔ ✔
|
|
183 |
status Server status ✔ ✔
|
|
184 |
attachments Network interfaces ✔ **✘**
|
|
185 |
addresses Network interfaces **✘** ✔
|
|
186 |
metadata Server custom metadata ✔ ✔
|
|
187 |
================ ====================== ======== ==========
|
|
188 |
|
|
189 |
* **hostId** is not used in Cyclades, but is returned as an empty string for compatibility
|
|
190 |
|
|
191 |
|
|
192 |
* **progress** is changing while the server is building up and has values between 0 and 100. When it reaches 100 the server is built.
|
|
193 |
|
|
194 |
|
|
195 |
* **status** referes to the status of the server
|
|
196 |
|
|
197 |
============= ==================== ======== ==========
|
|
198 |
Status Description Cyclades OS Compute
|
|
199 |
============= ==================== ======== ==========
|
|
200 |
BUILD Building ✔ ✔
|
|
201 |
ACTIVE Up and running ✔ ✔
|
|
202 |
STOPPED Shut down ✔ **✘**
|
|
203 |
REBOOT Rebooting ✔ ✔
|
|
204 |
DELETED Removed ✔ ✔
|
|
205 |
UNKNOWN Unexpected error ✔ ✔
|
|
206 |
ERROR In error ✔ ✔
|
|
207 |
HARD_REBOOT Hard rebooting **✘** ✔
|
|
208 |
PASSWORD Resetting password **✘** ✔
|
|
209 |
REBUILD Rebuilding server **✘** ✔
|
|
210 |
RESCUE In rescue mode **✘** ✔
|
|
211 |
RESIZE Resizing **✘** ✔
|
|
212 |
REVERT_RESIZE Failed to resize **✘** ✔
|
|
213 |
SHUTOFF Shut down by user **✘** ✔
|
|
214 |
SUSPENDED Suspended **✘** ✔
|
|
215 |
VERIFY_RESIZE Waiting confirmation **✘** ✔
|
|
216 |
============= ==================== ======== ==========
|
|
217 |
|
|
218 |
|
|
|
219 |
|
|
220 |
* **metadata** are custom key:value pairs used to specify various attributes of the VM (e.g. OS, super user, etc.)
|
|
221 |
|
|
222 |
|
|
223 |
* **attachments** in Cyclades are lists of network interfaces (nics). Each server can handle various nics. Each nic connects the current server with a network. **Attachments** are different to OS Compute's **addresses** the former is a list of the server's network interfaces (network reference + mac address) while the later is a just list of networks. For example, a Cyclades server may be connected to the same network through more than one distinct network interfaces (e.g. server 43 is connected to network 101 with nic-43-1 and nic-43-2 in the example bellow).
|
|
224 |
|
|
225 |
* **Network Interfaces (NICs)** contain information about a server's connection to a network. Each nic is identified by an id of the form nic-<server-id>-<ordinal-number> and may contain a ``network_id``, a ``mac_address``, ``ipv4`` and ``ipv6`` addresses and the ``firewallProfile`` of the connection.
|
| 128 |
226 |
|
| 129 |
227 |
**Example List Servers: JSON**
|
| 130 |
228 |
|
| ... | ... | |
| 134 |
232 |
'servers':
|
| 135 |
233 |
{'values': [
|
| 136 |
234 |
{
|
| 137 |
|
'addresses': {'values': [
|
|
235 |
'attachments': {'values': [
|
| 138 |
236 |
{
|
| 139 |
|
'id': 'public',
|
| 140 |
|
'mac': 'aa:00:00:49:2e:7e',
|
| 141 |
|
'name': 'public',
|
| 142 |
|
'values': [ {'addr': '192.168.32.6', 'version': 4} ]
|
|
237 |
'id': 'nic-42-0',
|
|
238 |
'network_id': '101',
|
|
239 |
'mac_address': 'aa:00:00:49:2e:7e',
|
|
240 |
'firewallProfile': DISABLED,
|
|
241 |
'ipv4': '192.168.4.5',
|
|
242 |
'ipv6': '2001:648:2ffc:1222:a800:ff:fef5:3f5b'
|
| 143 |
243 |
}
|
| 144 |
244 |
]},
|
| 145 |
245 |
'created': '2011-04-19T10:18:52.085737+00:00',
|
| 146 |
246 |
'flavorRef': 1,
|
| 147 |
247 |
'hostId': '',
|
| 148 |
|
'id': 1,
|
|
248 |
'id': 42,
|
| 149 |
249 |
'imageRef': 3,
|
| 150 |
250 |
'metadata': {'values': {'foo': 'bar'}},
|
| 151 |
251 |
'name': 'My Server',
|
| ... | ... | |
| 153 |
253 |
'updated': u'2011-05-29T14:07:07.037602+00:00'
|
| 154 |
254 |
},
|
| 155 |
255 |
{
|
| 156 |
|
'addresses': {'values': [
|
|
256 |
'attachments': {'values': [
|
| 157 |
257 |
{
|
| 158 |
|
'id': 'public',
|
|
258 |
'id': 'nic-43-0',
|
| 159 |
259 |
'mac': 'aa:00:00:91:2f:df',
|
| 160 |
|
'name': 'public',
|
| 161 |
|
'values': [ {'addr': '192.168.32.7', 'version': 4} ]
|
|
260 |
'network_id': '1',
|
|
261 |
'ipv4': '192.168.32.2'
|
| 162 |
262 |
},
|
| 163 |
263 |
{
|
| 164 |
|
'id': '2',
|
| 165 |
|
'mac': 'aa:00:00:c3:69:6f',
|
| 166 |
|
'name': 'private'
|
|
264 |
'id': 'nic-43-1',
|
|
265 |
'network_id': '101',
|
|
266 |
'mac_address': 'aa:00:00:49:2g:7f',
|
|
267 |
'firewallProfile': DISABLED,
|
|
268 |
'ipv4': '192.168.32.6',
|
|
269 |
'ipv6': '2001:648:2ffc:1222:a800:ff:fef5:3f5c'
|
| 167 |
270 |
},
|
|
271 |
{
|
|
272 |
'id': 'nic-43-2',
|
|
273 |
'network_id': '101',
|
|
274 |
'mac_address': 'aa:00:00:51:2h:7f',
|
|
275 |
'firewallProfile': DISABLED,
|
|
276 |
'ipv4': '192.168.32.7',
|
|
277 |
'ipv6': '2001:638:2eec:1222:a800:ff:fef5:3f5c'
|
|
278 |
}
|
| 168 |
279 |
]},
|
| 169 |
280 |
'created': '2011-05-02T20:51:08.527759+00:00',
|
| 170 |
281 |
'flavorRef': 1,
|
| 171 |
282 |
'hostId': '',
|
| 172 |
|
'id': 2,
|
|
283 |
'id': 43,
|
| 173 |
284 |
'imageRef': 3,
|
| 174 |
285 |
'name': 'Other Server',
|
|
286 |
'description': 'A sample server to showcase server requests',
|
| 175 |
287 |
'progress': 0,
|
| 176 |
288 |
'status': 'ACTIVE',
|
| 177 |
289 |
'updated': '2011-05-29T14:59:11.267087+00:00'
|