Skip to content

GitLab

Commit eda3ef59 authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Update compute server API to current state 

Refs: #5064
parent d9adcaf6
Hide whitespace changes
Inline Side-by-side
Showing with 350 additions and 453 deletions
docs/compute-api-guide.rst
View file @ eda3ef59
......@@ -88,8 +88,8 @@ Description URI
`Get Details <#get-server-details>`_ ``/servers/<server id>`` GET ✔ ✔
`Rename <#rename-server>`_ ``/servers/<server id>`` PUT ✔ ✔
`Delete <#delete-server>`_ ``/servers/<server id>`` DELETE ✔ ✔
`List Addresses <#list-server-addresses>`_ ``/servers/<server id>/ips`` GET ✔ ✔
`Get NICs by Net <#get-server-nics-by-network>`_ ``/servers/<server id>/ips/<network id>`` GET ✔ ✔
`List Connections <#list-server-connections>`_ ``/servers/<server id>/ips`` GET ✔ ✔
`Get Connection <#connection-with-network>`_ ``/servers/<server id>/ips/<network id>`` GET ✔ ✔
`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 ✔ ✔
......@@ -207,6 +207,7 @@ The server attributes are listed `here <#server-ref>`_
GET https://example.org/compute/v2.0/servers
{
"servers": [
{
......@@ -239,6 +240,9 @@ The server attributes are listed `here <#server-ref>`_
*Example List Servers: JSON (detail)*
GET https://example.org/compute/v2.0/servers/detail
.. code-block:: javascript
{
......@@ -473,7 +477,6 @@ URI Method Cyclades OS/Compute
============ ====== ======== ==========
|
============== ========================= ======== ==========
Request Header Value Cyclades OS/Compute
============== ========================= ======== ==========
......@@ -482,14 +485,7 @@ Content-Type Type or request body required required
Content-Length Length of request body required required
============== ========================= ======== ==========
*Example Request Headers*::
X-Auth-Token: z31uRXUn1LZy45p1r7V==
Content-Type: application/json
Content-Length: 735
|
================= ===============
Request Parameter Value
================= ===============
......@@ -503,24 +499,25 @@ Request body contents::
<server attribute>: <value>,
...
personality: [
{
<personality attribute>: <value>,
...
},
...
],
networks: [
...
]
...
}
=========== ==================== ======== ==========
Attributes Description Cyclades OS/Compute
=========== ==================== ======== ==========
name The server name ✔ ✔
imageRef Image id ✔ ✔
flavorRef Resources flavor ✔ ✔
personality Personality contents ✔ ✔
metadata Custom metadata ✔ ✔
=========== ==================== ======== ==========
=========== ====================== ======== ==========
Attributes Description Cyclades OS/Compute
=========== ====================== ======== ==========
name The server name ✔ ✔
imageRef Image id ✔ ✔
flavorRef Resources flavor ✔ ✔
personality Personality contents ✔ ✔
metadata Custom metadata ✔ ✔
networks Connection information ✔ ✔
project Project UUID ✔ **✘**
=========== ====================== ======== ==========
* **name** can be any string
......@@ -528,55 +525,14 @@ metadata Custom metadata ✔ ✔
flavors accessible by the user
* **metadata** are ``key``:``value`` pairs of custom server-specific metadata.
There are no semantic limitations.
* **personality** (optional) is a list of personality injections. A personality
injection is a way to add a file into a virtual server while creating it.
Each change modifies/creates a file on the virtual server. The injected data
(``contents``) should not exceed 10240 *bytes* in size and must be base64
encoded. The file mode should be a number, not a string. 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 ✔ **✘**
====================== =================== ======== ==========
There are no semantic limitations, although the ``OS`` and ``USERS`` values
should rather be defined
*Example Create Server Request: JSON*
* **personality** (optional) is a list of
`personality injections <#personality-ref>`_
.. code-block:: javascript
{
"server": {
"name": "My Server Name: Example Name",
"imageRef": "da7a211f-...-f901ce81a3e6",
"flavorRef": 289,
"personality": [
{
"path": "/Users/myusername/personlities/example1.file",
"contents": "some data to inject",
"group": "remotely-set user group",
"mode": 0600,
"owner": "ausername"
}, {
"path": "/Users/myusername/personlities/example2.file",
"contents": "some more data to inject",
"group": "",
"mode": 0777,
"owner": "anotherusername"
}
],
"metadata": {
"EloquentDescription": "Example server with personality",
"ShortDescription": "Trying VMs"
}
}
}
* **networks** (optional) is a list of
`network connections <#network-on-vm-ref>`_.
.. rubric:: Response
......@@ -588,8 +544,7 @@ Return Code Description
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
413 (Over Limit) Exceeded some resource limit (#VMs, personality
size, etc.)
413 (Over Limit) Exceeded some resource limit
415 (Bad Media Type)
500 (Internal Server Error) The request cannot be completed because of an
\ internal error
......@@ -608,84 +563,134 @@ Response body contents::
Server attributes are `listed here <#server-ref>`_.
.. note:: The ``adminPass`` attribute is generated in the response. This is the
only case where this attribute appears in a response.
*Example Create Server Response: JSON*
.. code-block:: javascript
POST https://example.org/compute/v2.0/servers
{
"server": {
"addresses":
"id": 28130,
"links": [
{
"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": [
{
"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"
}
]
},
"flavor": {
"id": 289
"links": [
{
"href": "https://example.org/compute/v2.0/flavors/289"
"rel": "self"
}, {
"href": "https://example.org/compute/v2.0/flavors/289"
"rel": "bookmark"
}
]
},
"name": "My Example Server",
"id": 5678,
"status": "BUILD",
"updated": "2013-04-10T13:52:18.140686+00:00",
"hostId": "",
"name": "My Server Name: Example Name",
"created": "2013-04-10T13:52:17.085402+00:00",
"updated": "2013-04-10T13:52:17.085402+00:00",
"adminPass": "fKCqlZe2at",
"suspended": false,
"progress": 0
"metadata": {
"EloquentDescription": "Example server with personality",
"ShortDescription": "Trying VMs"
}
"OS": "debian",
"USERS": "root"
},
...
}
}
*Example Create Server Response: XML*
.. _personality-ref:
.. code-block:: xml
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"},
],
...
}
}
<?xml version="1.0" encoding="UTF-8"?>
<server xmlns="http://docs.openstack.org/compute/api/v1.1"\
xmlns:atom="http://www.w3.org/2005/Atom"
id="1"
status="BUILD"
hostId="",
name="My Server Name: Example Name"
created="2013-04-10T13:52:17.085402+00:00"
adminPass="fKCqlZe2at"
suspended="false"
progress="0"
...
/>
Get Server Stats
----------------
......@@ -702,10 +707,7 @@ URI Method Cyclades OS/Compute
``/servers/<server-id>/stats`` GET ✔ **✘**
============================== ====== ======== ==========
* **server-id** is the identifier of the virtual server
|
============== ========================= ======== ==========
Request Header Value Cyclades OS/Compute
============== ========================= ======== ==========
......@@ -713,7 +715,6 @@ X-Auth-Token User authentication token required required
============== ========================= ======== ==========
|
================= ===============
Request Parameter Value
================= ===============
......@@ -724,8 +725,6 @@ xml Respond in xml
* **json** and **xml** parameters are mutually exclusive. If none supported,
the response will be formated in json.
.. note:: Request body should be empty
.. rubric:: Response
=========================== =====================
......@@ -763,10 +762,10 @@ netTimeSeries Network load / time graph URL
*Example Get Server Stats Response: JSON*
.. code-block:: javascript
GET https://example.org/compute/v2.0/servers/5678/stats
{
"stats": {
"serverRef": 1,
"serverRef": 5678,
"refresh": 60,
"cpuBar": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-bar.png",
"cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a...048c/cpu-ts.png",
......@@ -775,21 +774,6 @@ netTimeSeries Network load / time graph URL
}
}
*Example Get Network Details Response: XML*
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8"?>
<stats xmlns="http://docs.openstack.org/compute/api/v1.1"\
xmlns:atom="http://www.w3.org/2005/Atom"
serverRef="1"
refresh="60"
cpuBar="https://www.example.org/stats/snf-42/cpu-bar/",
netTimeSeries="https://example.org/stats/snf-42/net-ts/",
netBar="https://example.org/stats/snf-42/net-bar/",
cpuTimeSeries="https://www.example.org/stats/snf-42/cpu-ts/"
</stats>
Get Server Diagnostics
----------------------
......@@ -805,20 +789,13 @@ URI Method Cyclades OS/Compute
``/servers/<server-id>/diagnostics`` GET ✔ **✘**
==================================== ====== ======== ==========
* **server-id** is the identifier of the virtual server
|
============== ========================= ======== ==========
Request Header Value Cyclades OS/Compute
============== ========================= ======== ==========
X-Auth-Token User authentication token required required
============== ========================= ======== ==========
.. note:: Request parameters should be empty
.. note:: Request body should be empty
.. rubric:: Response
=========================== =====================
......@@ -842,9 +819,6 @@ Response body contents::
{
<diagnostic attribute}: <value>,
...
}, {
<diagnostic attribute}: <value>,
...
},
...
]
......@@ -864,6 +838,7 @@ details Detailed log description
.. code-block:: javascript
GET https://example.org/compute/v2.0/servers/5678/diagnostics
[
{
"level": "DEBUG",
......@@ -879,13 +854,6 @@ details Detailed log description
"source_date": "2013-04-09T15:25:46.404477+00:00",
"message": "Starting customization VM...",
"details": null
}, {
"level": "DEBUG",
"created": "2013-04-09T15:25:46.207038+00:00",
"source": "image-info",
"source_date": "2013-04-09T15:25:46.197183+00:00",
"message": "Image copy finished.",
"details": "All operations finished as they should. No errors reported."
}
]
......@@ -902,8 +870,6 @@ URI Method Cyclades OS/Compute
``/servers/<server id>`` GET ✔ ✔
======================== ====== ======== ==========
* **server-id** is the identifier of the virtual server
|
============== ========================= ======== ==========
......@@ -912,10 +878,6 @@ Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required
============== ========================= ======== ==========
.. note:: Request parameters should be empty
.. note:: Request body should be empty
.. rubric:: Response
=========================== =====================
......@@ -941,123 +903,120 @@ Response body contents::
...
}
================= ====================== ======== ==========
Server Attributes Description Cyclades OS/Compute
================= ====================== ======== ==========
id The server id ✔ ✔
name The server name ✔ ✔
hostId Server playground empty ✔
created Creation date ✔ ✔
updated Creation date ✔ ✔
flavor The flavor id ✔ ✔
image The image id ✔ ✔
progress Build progress ✔ ✔
status Server status ✔ ✔
suspended If server is suspended ✔ **✘**
attachments Network interfaces ✔ **✘**
addresses Network interfaces **✘** ✔
metadata Server custom metadata ✔ ✔
diagnostics Diagnostic information ✔ **✘**
================= ====================== ======== ==========
* **hostId** is not used in Cyclades, but is returned as an empty string for
compatibility
* **progress** is changing while the server is building up and has values
between 0 and 100. When it reaches 100 the server is built.
* **status** refers to `the status <#status-ref>`_ of the server
* **metadata** are custom key:value pairs used to specify various attributes of
the VM (e.g. OS, super user, etc.)
* **attachments** in Cyclades are lists of network interfaces (NICs).
**Attachments** are different to OS/Compute's **addresses**. The former is a
list of the server's `network interface connections <#attachments-ref>`_ while the
later is just a list of networks. Thus, a Cyclades virtual server may be
connected to the same network through more than one distinct network
interfaces.
* **diagnostics** is a list of items that contain key:value information useful
for diagnosing the server behavior and may be used by the administrators of
deployed Synnefo setups.
*Example Details for server with id 42042: JSON*
Server attributes are explained `here <#server-ref>`_
*Example get server Details*
.. code-block:: javascript
GET https://example.org/compute/v2.0/servers/84
{
"server": {
"attachments": [
{
"network_id": "1888",
"mac_address": "aa:0c:f5:ad:16:41",
"firewallProfile": "DISABLED",
"ipv4": "83.212.112.56",
"ipv6": "2001:648:2ffc:1119:a80c:f5ff:fead:1641",
"id": "nic-42042-0"
}
"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"
}
],
"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",
"links": [
{
"href": "https://example.org/compute/v2.0/servers/42031",
"rel": "self"
},
{
"href": "https://example.org/compute/v2.0/servers/42042",
"rel": "bookmark"
}
],
"created": "2011-05-02T20:51:08.527759+00:00",
"flavor": {
"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"
}
]
},
"hostId": "",
"id": "42042",
"image": {
"id": "im4g3-1d",
"links": [
{
"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"
}
]
},
"name": "My Example Server",
"description": "A sample server to showcase server requests",
"progress": "0",
"status": "ACTIVE",
"updated": "2011-05-29T14:59:11.267087+00:00",
"suspended": false,
"diagnostics": [
{
"level": "DEBUG",
"created": "2013-04-18T10:09:52.776920+00:00",
"source": "image-info",
"source_date": "2013-04-18T10:09:52.709791+00:00",
"message": "Image customization finished successfully.",
"details": null
}
],
{
"href": "https://example.org/compute/v2.0/images/im4g3-1d",
"rel": "self"
}, {