Skip to content
Snippets Groups Projects
Select Git revision
  • develop
  • debian-develop
  • debian
  • master default
  • centos-develop
  • centos
  • 0.18.1
  • debian/0.18-1wheezy
  • 0.18
  • debian/0.17-2wheezy
  • debian/0.17-1wheezy
  • 0.17
  • debian/0.16.2-1wheezy
  • 0.16.2
  • debian/0.16.1-1wheezy
  • 0.16.1
  • debian/0.16.1rc1-1wheezy
  • 0.16.1rc1
  • debian/0.16-1wheezy
  • 0.16
  • debian/0.16rc3-1wheezy
  • 0.16rc3
  • debian/0.16rc2-1wheezy
  • 0.16rc2
  • debian/0.16rc1-1wheezy
  • 0.16rc1
26 results
Blame History Permalink
compute-api-guide.rst 94.24 KiB

API Guide

Cyclades is the Compute Service of Synnefo. The Cyclades/Compute API complies with OpenStack Compute with custom extensions when needed.

This document's goals are:

  • Define the Cyclades/Compute REST API
  • Clarify the differences between Cyclades and OpenStack/Compute

Users and developers who wish to access Cyclades through its REST API are advised to use the kamaki command-line client and associated python library, instead of making direct calls.

Overview

  • 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.

General API Information

Authentication

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.

Efficient Polling with the Changes-Since Parameter

  • Effectively limit support of the changes-since parameter in List Servers and List Images.
  • Assume that garbage collection of deleted servers will only affect servers deleted POLL_TIME seconds (default: 3600) in the past or earlier. Else loose the information of a server getting deleted.
  • Images do not support a deleted state, so deletions cannot be tracked.

Limitations

  • Version MIME type and vesionless requests are not currently supported.
  • Cyclades only supports JSON Requests and JSON/XML Responses. XML Requests are currently not supported.
  • Optional content compression support is currently not supported.
  • To prevent abuse, HTTP sessions have a timeout of 20 seconds before being closed.
  • Full URI references and self and bookmark links are not supported.
  • Pagination is currently not supported.
  • Cached responses are currently not supported.
  • Limits are currently not supported.
  • Extensions are currently not supported.

API Operations

Servers

Description URI Method Cyclades OS/Compute
List /servers GET ✔ ✔
/servers/detail GET ✔ ✔
Create /servers POST ✔ ✔
Get Stats /servers/<server-id>/stats GET ✔ ✘
Get Diagnostics /servers/<server-id>/diagnostics GET ✔ ✘
Get Details /servers/<server id> GET ✔ ✔
Rename /servers/<server id> PUT ✔ ✔
Delete /servers/<server id> DELETE ✔ ✔
List Addresses /servers/<server id>/ips GET ✔ ✔
Get NICs by Net /servers/<server id>/ips/<network id> GET ✔ ✔
List Metadata /servers/<server-id>/metadata GET ✔ ✔
Update Metadata /servers/<server-id>/metadata PUT ✘ ✔
/servers/<server-id>/metadata POST ✔ ✔
Get Meta Item /servers/<server-id>/metadata/<key> GET ✔ ✔
Update Meta Item /servers/<server-id>/metadata/<key> PUT ✔ ✔
Delete Meta Item /servers/<server-id>/metadata/<key> DELETE ✔ ✔
Actions servers/<server id>/action POST ✔ ✔

Flavors

Description URI Method Cyclades OS/Compute
List /flavors GET ✔ ✔
/flavors/detail GET ✔ ✘
Get details /flavors/<flavor-id> GET ✔ ✔

Images

Description URI Method Cyclades OS/Compute
List /images GET ✔ ✔
/images/detail GET ✔ ✔
Get details /images/<image-id> GET ✔ ✔
Delete /images/<image id> DELETE ✔ ✔
List Metadata /images/<image-id>/metadata GET ✔ ✔
Update Metadata /images/<image-id>/metadata POST ✔ ✔
/images/<image-id>/metadata PUT ✘ ✔
Get Meta Item /image/<image-id>/metadata/<key> GET ✔ ✔
Update Metadata /images/<image-id>/metadata/<key> PUT ✔ ✔
Delete Metadata /images/<image-id>/metadata/<key> DELETE ✔ ✔

List Servers

List all virtual servers owned by the user.

Request

URI Method Cyclades OS/Compute
/servers GET ✔ ✔
/servers/detail GET ✔ ✔
  • 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.

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required

Request Parameter Value Cyclades OS/Compute
json Respond in json default ✘
xml Respond in xml ✔ ✘
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 ✘ ✔
  • json and xml parameters are mutually exclusive. If none supported,

the response will be formated in json.

  • status refers to the server status
  • changes-since must be an ISO8601 date string

Response

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
403 (Forbidden) User is not allowed to perform this operation
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response body contents:

servers: [
  {
    <server attribute>: <value>,
    ...
  }, ...
]

The server attributes are listed here

Example List Servers: JSON (regular)

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

{
  "servers": [
    {
      "links": [
        {
          "href": "https://example.org/compute/v2.0/servers/42",
          "rel": "self"
        }, {
          "href": "https://example.org/compute/v2.0/servers/42",
          "rel": "bookmark"
        }
      ],
      "id": "42",
      "name": "My Server",
    }, {
      "links": [
        {
          "href": "https://example.org/compute/v2.0/servers/43",
          "rel": "self"
        }, {
          "href": "https://example.org/compute/v2.0/servers/43",
          "rel": "bookmark"
        }
      ],
      "id": "84",
      "name": "My Server",
    }
  ]
}

Example List Servers: JSON (detail)

{
  "servers": [
    {
      "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"
          }
        ]
      ],
      "attachments": [
          {
            "id": "18",
            "network_id": "2718",
            "mac_address": "aa:01:02:6c:34:ab",
            "firewallProfile": "DISABLED",
            "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"
          }
      ],
      "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"
          }
        ]
      },
      "suspended": false,
      "created': '2011-04-19T10:18:52.085737+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"
          }
        ]
      },
      "id": "42",
      "security_groups": [{"name": "default"}],
      "user_id": "s0m5-u5e7-1d",
      "accessIPv4": "",
      "accessIPv6": "",
      "progress": 100,
      "config_drive": "",
      "status": "ACTIVE",
      "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"
      }
    }, {
    {
      "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/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"
      }
    }
  ]
}

Create Server

Create a new virtual server

Request

URI Method Cyclades OS/Compute
/servers POST ✔ ✔

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required
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
json Respond in json
xml Respond in xml

Request body contents:

server: {
    <server attribute>: <value>,
    ...
    personality: [
      {
        <personality attribute>: <value>,
        ...
      },
      ...
    ],
    ...
}
Attributes Description Cyclades OS/Compute
name The server name ✔ ✔
imageRef Image id ✔ ✔
flavorRef Resources flavor ✔ ✔
personality Personality contents ✔ ✔
metadata Custom metadata ✔ ✔
  • name can be any string
  • imageRed and flavorRed should refer to existing images and hardware 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 ✔ ✘

Example Create Server Request: JSON

{
  "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"
    }
  }
}

Response

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
413 (Over Limit) Exceeded some resource limit (#VMs, personality
size, etc.)  
415 (Bad Media Type)  
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) No available backends or service currently
unavailable

Response body contents:

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

Server attributes are listed here.

Example Create Server Response: JSON

{
  "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"
          }
      ]
    },
    "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",
    "adminPass": "fKCqlZe2at",
    "suspended": false,
    "progress": 0
    "metadata": {
      "EloquentDescription": "Example server with personality",
      "ShortDescription": "Trying VMs"
    }
  }
}

Example Create Server Response: XML

<?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

Note

This operation is not part of OS/Compute v2.

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

Request

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
X-Auth-Token User authentication token required required

Request Parameter Value
json Respond in json
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

Response

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
internal error
503 (Service Unavailable) The server is not currently available

Response body contents:

stats: {<parameter>: <value> }
Parameter Description
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

Example Get Server Stats Response: JSON

{
  "stats": {
    "serverRef": 1,
    "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"
  }
}

Example Get Network Details Response: 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

Note

This operation is not part of OS/Compute v2.

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

Request

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

Response

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
internal error
503 (Service Unavailable) The server is not currently available

Response body contents:

[
  {
    <diagnostic attribute}: <value>,
    ...
  }, {
    <diagnostic attribute}: <value>,
    ...
  },
  ...
]
Diagnostic attribute Description
level Debug level
created Log entry timestamp
source Log source proccess
source_date Log source date
message Log description
details Detailed log description

Example Get Server Diagnostics Response: JSON

[
  {
    "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
  }, {
    "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."
  }
]

Get Server Details

This operation returns detailed information for a virtual server

Request

URI Method Cyclades OS/Compute
/servers/<server id> 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

Response

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
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) No available backends or service currently
unavailable

Response body contents:

server: {
  <server attribute>: <value>,
  ...
}
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 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 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": {
      "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"
          }
      ],
      "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
          }
      ],
    }
  }
}

Rename Server

Modify the name attribute of a virtual server. OS/Compute API also features the modification of IP addresses

Response

URI Method Cyclades OS/Compute
/servers/<server id> PUT ✔ ✔
  • server-id is the identifier of the virtual server

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required
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: 54

Note

Request parameters should be empty

Request body contents:

server: {
  <server attribute>: <value>,
  ...
}
Attribute Description Cyclades OS/Compute
name The server name ✔ ✔
accessIPv4 IP v4 address ✘ ✔
accessIPv6 IP v6 address ✘ ✔
  • Cyclades support multiple network connections per virtual server, which explains the above differences in request body attributes.

Example Rename Server Request: JSON

{"server": {"name": "A new name for my virtual server"}}

Response

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
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) No available backends or service currently
unavailable

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.

Delete Server

Delete a virtual server. When a server is deleted, all its connections are deleted as well.

Request

URI Method Cyclades OS/Compute
/servers/<server id> DELETE ✔ ✔
  • 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

Response

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
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) Action not supported or service currently
unavailable

Note

In case of a 204 code, response body should be empty

List Server Addresses

List all network connections of a server. In Cyclades API, connections are represented as Network Connection Interfaces (NICs), which describe a server - network relation through their respective identifiers. This mechanism ensures flexibility and multiple networks connecting the same virtual servers.

The Synnefo/Cyclades approach in this matter differs substantially to the one suggested by the OS/Compute API.

Request

URI Method Cyclades OS/Compute
/servers/<server id>/ips 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

Response

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
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) Service currently unavailable

Response body contents:

addresses: [
  {
    <NIC attribute>: <value>,
    ...
  },
  ...
]

A Network Interface Connection (or NIC) connects the current server to a network, through their respective identifiers. More information in NIC attributes are enlisted here.

Example List Addresses: JSON

{
  "addresses": [
    {
      "id": "nic-25455-0"
      "network_id": "1",
      "mac_address": "aa:00:03:7a:84:bb",
      "firewallProfile": "DISABLED",
      "ipv4": "192.168.0.27",
      "ipv6": "2001:646:2ffc:1222:a820:3fd:fe7a:84bb",
    }, {
      "id": "nic-25455-1"
      "network_id": "7",
      "mac_address": "aa:00:03:7a:84:cc",
      "firewallProfile": "DISABLED",
      "ipv4": "192.168.0.28",
      "ipv6": "2002:646:2fec:1222:a820:3fd:fe7a:84bc",
    },
  ]
}

Get Server NICs by Network

Return the NIC that connects a server to a network.

The semantics of this operation are substantially different to the respective OS/Compute List Addresses by Network semantics.

Request

URI Method Cyclades OS/Compute
/servers/<server id>/ips/<network id> GET ✔ ✔
  • server id is the identifier of the virtual server
  • network id is the identifier of the network

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

Response

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
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) Service currently unavailable

Response body contents:

network: {
  <NIC attributes>: <value>,
  ...
}

Network Interface Connection (NIC) attributes are listed here.

List Server NICs Example with server id 25455, network id 7: JSON

{
  "network": {
    "id": "nic-25455-0"
    "network_id": "7",
    "mac_address": "aa:00:03:7a:84:bb",
    "firewallProfile": "DISABLED",
    "ipv4": "192.168.0.27",
    "ipv6": "2001:646:2ffc:1222:a820:3fd:fe7a:84bb",
  }
}

List Server Metadata

List the metadata of a server

Note

This operation is semantically equivalent in Cyclades and OS/Compute besides the different URI.

Request

URI Method Cyclades OS/Compute
/servers/<server-id>/metadata 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

Response

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
internal error
503 (Service Unavailable) The server is not currently available

Response body contents:

metadata: {
  <key>: <value>,
    ...
}

Example List Server Metadata: JSON

{
  ""metadata": {
    "OS": "Linux",
    "users": "root"
  }
}

Set / Update Server Metadata

In Cyclades API, setting new metadata and updating the values of existing ones is achieved with the same type of request (POST), while in OS/Compute API there are two separate request types (PUT and POST for setting new and updating existing metadata, respectively).

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

Request

  • server-id is the identifier of the virtual server

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required
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: 56

Note

Request parameters should be empty

Request body contents:

metadata: {
  <key>: <value>,
  ...
}

Example Request Set / Update Server Metadata: JSON

{"metadata": {"role": "webmail", "users": "root,maild"}}

Response

Return Code Description
201 (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
413 (OverLimit) Maximum number of metadata exceeded
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response body contents:

metadata: {
  <key>: <value>,
  ...
}

Example Response Set / Update Server Metadata: JSON

{"metadata": {"OS": "Linux", "role": "webmail", "users": "root,maild"}}

Get Server Metadata Item

Get the value of a specific piece of metadata of a virtual server

Request

URI Method Cyclades OS/Compute
/servers/<server-id>/metadata/<key> GET ✔ ✔
  • server-id is the identifier of the virtual server
  • key is the key of a mata key:value pair

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

Response

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) Meta key not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response body content:

metadata: {<key>: <value>}

Example Get Server Metadata for Item 'role', JSON

{"metadata": {"role": "webmail"}}

Update Server Metadata Item

Set a new or update an existing a metadum value for a virtual server.

Request

URI Method Cyclades OS/Compute
/servers/<server-id>/metadata/<key> PUT ✔ ✔
  • server-id is the identifier of the virtual server
  • key is the key of a key:value pair piece of metadata

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required
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: 29

Note

Request parameters should be empty

Request body content:

metadata: {<key>: <value>}

Example Request to Set or Update Server Metadata "role": JSON

{"metadata": {"role": "gateway"}}

Response

Response body content:

metadata: {<key>: <value>}

Example Set or Update Server Metadata "role":"gateway": JSON

{"metadata": {"role": "gateway"}}

Delete Server Metadata

Delete a metadata of a virtual server

Request

URI Method Cyclades OS/Compute
/servers/<server-id>/metadata/<key> DELETE ✔ ✔
  • server-id is the identifier of the virtual server
  • key is the key of a mata key:value pair

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

Response

Return Code Description
204 (OK) Request succeeded
400 (Bad Request) Invalid server ID
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Administratively suspended server
404 (Not Found) Metadata key not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Note

In case of a 204 code, response body should be empty

Server Actions

Actions are operations that are achieved through the same type of request (POST). There are differences in the implementations of some operations between Synnefo/Cyclades and OS/Compute. Although this document focuses on Synnefo/Cyclades, differences and similarities between the APIs are also briefed.

Operations Cyclades OS/Compute
Start ✔ ✘
Shutdown ✔ ✘
Reboot ✔ ✔
Get Console ✔ ✘
Set Firewall ✔ ✘
Change Admin Password ✘ ✔
Rebuild ✘ ✔
Resize ✘ ✔
Confirm Resized ✘ ✔
Revert Resized ✘ ✔
Create Image ✘ ✔

Request

URI Method Cyclades OS/Compute
/servers/<server id>/action POST ✔ ✔

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required
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: 32

Note

Request parameters should be empty

Note

Request body varies between operations (see bellow)

Response

Return Code Description
200 (OK) Request succeeded (for console operation)
202 (OK) Request succeeded
400 (Bad Request) Invalid request or unknown action
401 (Unauthorized) Missing or expired user token
403 (Forbidden) User is not allowed to perform this operation
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Note

Response body varies between operations (see bellow)

Start server

This operation transitions a server from a STOPPED to an ACTIVE state.

Request body contents:

start: {}

Example Start Server: JSON

{"start": {}}

Note

Response body should be empty

Reboot Server

This operation transitions a server from ACTIVE to REBOOT and then ACTIVE again.

Synnefo and OS/Compute APIs offer two reboot modes: soft and hard. OS/Compute distinguishes between the two intermediate states (REBOOT and HARD_REBOOT) while rebooting, while Synnefo/Cyclades use only the REBOOT term. The expected behavior is the same, though.

Request body contents:

reboot: {type: <reboot type>}
  • reboot type can be either SOFT or HARD.

Example (soft) Reboot Server: JSON

{"reboot" : { "type": "soft"}}

Note

Response body should be empty

Shutdown server

This operation transitions a server from an ACTIVE to a STOPPED state.

Request body contents:

shutdown: {}

Example Shutdown Server: JSON

{"shutdown": {}}

Note

Response body should be empty

Get Server Console

Note

This operation is not part of OS/Compute API

The console operation arranges for an OOB console of the specified type. Only consoles of type vnc are supported for now. Cyclades server uses a running instance of vncauthproxy to setup proper VNC forwarding with a random password, then returns the necessary VNC connection info to the caller.

Request body contents:

console: {type: vnc}

Example Get Server Console: JSON

{"console": {"type": "vnc" }

Response body contents:

console: {
  <vnc attribute>: <value>,
  ...
}
VNC Attributes Description
host The vncprocy host
port vncprocy port
password Temporary password
type Connection type (only VNC)

Example Action Console Response: JSON

{
  "console": {
    "type": "vnc",
    "host": "vm42.example.org",
    "port": 1234,
    "password": "513NR14PN0T"
  }
}

Set Server Firewall Profile

The firewallProfile function sets a firewall profile for the public interface of a server.

Request body contents:

firewallProfile: {profile: <firewall profile>, nic: <nic id>}
  • firewall profile can be ENABLED, DISABLED or PROTECTED

Example Action firewallProfile: JSON*

{"firewallProfile": {"profile": "ENABLED", "nic": 123}}

Note

Response body should be empty

OS/Compute Specific

The following operations are meaningless or not supported in the context of Synnefo/Cyclades, but are parts of the OS/Compute API:

List Flavors

List the flavors that are accessible by the user

Request

URI Method Cyclades OS/Compute
/flavors GET ✔ ✔
/flavors/detail GET ✔ ✔

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required

Request Parameter Value
json Respond in json
xml Respond in xml

Note

Request body should be empty

Response

Return Code Description
200 (OK) Request succeeded
400 (Bad Request) Malformed request
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Forbidden to use this flavor
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response code contents:

flavors: [
  {
    <flavor attribute>: <value>,
    ...
  },
  ...
]

Flavor attributes are listed here. Regular listing contains only id and name attributes.

Example List Flavors (regular): JSON

{
  "flavors": [
    {
      "id": 1,
      "name": "One code",
      "links": [
          {
              "href": "https://example.org/compute/v2.0/flavors/1",
              "rel": "self"
          },
          {
              "href": "https://example.org/compute/v2.0/flavors/1",
              "rel": "bookmark"
          }
      ]
    }, {
      "id": 3,
      "name": "Four core",
      "links": [
          {
              "href": "https://example.org/compute/v2.0/flavors/3",
              "rel": "self"
          },
          {
              "href": "https://example.org/compute/v2.0/flavors/3",
              "rel": "bookmark"
          }
      ]
    }
  ]
}

Example List Flavors (regular): XML

<?xml version="1.0" encoding="UTF-8"?>
<flavors xmlns="http://docs.openstack.org/compute/api/v1"
  xmlns:atom="http://www.w3.org/2005/Atom">
  <flavor id="1" name="One core"/>
  <flavor id="3" name="Four core"/>
</flavors>

Example List Flavors (detail): JSON

{
  "flavors": [
    {
      "id": 1,
      "name": "One core",
      "ram": 1024,
      "SNF:disk_template": "drbd",
      "disk": 20,
      "cpu": 1,
      "links": [
          {
              "href": "https://example.org/compute/v2.0/flavors/1",
              "rel": "self"
          },
          {
              "href": "https://example.org/compute/v2.0/flavors/1",
              "rel": "bookmark"
          }
      ]
    }, {
      "id": 3,
      "name": "Four core",
      "ram": 1024,
      "SNF:disk_template": "drbd",
      "disk": 40,
      "cpu": 4,
      "links": [
          {
              "href": "https://example.org/compute/v2.0/flavors/3",
              "rel": "self"
          },
          {
              "href": "https://example.org/compute/v2.0/flavors/3",
              "rel": "bookmark"
          }
      ]
    }
  ]
}

Get Flavor Details

Get the configuration of a specific flavor

Request

URI Method Cyclades OS/Compute
/flavors/<flavor-id GET ✔ ✔
  • flavor-id is the identifier of the flavor

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required

Request Parameter Value
json Respond in json
xml Respond in xml

Note

Request body should be empty

Response

Return Code Description
200 (OK) Request succeeded
400 (Bad Request) Malformed flavor ID
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Forbidden to use this flavor
404 (Not Found) Flavor id not founmd
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response code contents:

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

All flavor attributes are listed here.

Example Flavor Details: JSON

{
  "flavor": {
    {
      "id": 1,
      "name": "One core",
      "ram": 1024,
      "SNF:disk_template": "drbd",
      "disk": 20,
      "cpu": 1,
      "links": [
          {
              "href": "https://example.org/compute/v2.0/flavors/1",
              "rel": "self"
          },
          {
              "href": "https://example.org/compute/v2.0/flavors/1",
              "rel": "bookmark"
          }
      ]
    }
  }
}

Example Flavor Details: XML

<?xml version="1.0" encoding="UTF-8"?>
<flavor xmlns="http://docs.openstack.org/compute/api/v1"
  xmlns:atom="http://www.w3.org/2005/Atom"
  id="1" name="One core" ram="1024" disk="20" cpu="1" />

List Images

List all images accessible by the user

Request


Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required

Request Parameter Value Cyclades OS/Compute
server Server filter ✘ ✔
name Image name filter ✘ ✔
status Server status filter ✘ ✔
changes-since Change timestamp filter ✔ ✔
marker Last list last ID filter ✘ ✔
limit Page size filter ✘ ✔
type Request filter type ✘ ✔
  • changes-since must be an ISO8601 date string. In Cyclades it refers to the image updated_at attribute and it should be a date in the window [- POLL_LIMIT ... now]. POLL_LIMIT default value is 3600 seconds except if it is set otherwise at server side.

Note

Request body should be empty

Response

Return Code Description
200 (OK) Request succeeded
304 (No images 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
403 (Forbidden) User is not allowed to perform this operation
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response body contents:

images: [
  {
    <image attribute>: <value>,
    ...
    metadata: {
      <image meta key>: <value>,
      ...
    },
    ...
  },
  ...
]

The regular response returns just id and name, while the detail returns a collections of the image attributes listed here.

Example List Image (detail): JSON

{
  "images: [
    {
      "status": "ACTIVE",
      "updated": "2013-03-02T15:57:03+00:00",
      "name": "edx_saas",
      "created": "2013-03-02T12:21:00+00:00",
      "progress": 100,
      "id": "175716...526236",
      "links": [
        {
          "href": "https://example.org/compute/v2.0/images/175716...526236",
          "rel": "self"
        },
        {
          "href": "https://example.org/compute/v2.0/images/175716...526236",
          "rel": "bookmark"
        },
        {
          "href": "https://example.org/image/v1.0/images/175716...526236",
          "rel": "alternate"
        }
      ],
      "metadata": {
        "partition_table": "msdos",
        "osfamily": "linux",
        "users": "root saasbook",
        "exclude_task_changepassword": "yes",
        "os": "ubuntu",
        "root_partition": "1",
        "description": "Ubuntu 12.04 LTS"
      }
    }, {
      "status": "ACTIVE",
      "updated": "2013-03-02T15:57:03+00:00",
      "name": "edx_saas",
      "created": "2013-03-02T12:21:00+00:00",
      "progress": 100,
      "id": "1357163d...c526206",
      "links": [
        {
          "href": "https://example.org/compute/v2.0/images/1357163d...c526206",
          "rel": "self"
        },
        {
          "href": "https://example.org/compute/v2.0/images/1357163d...c526206",
          "rel": "bookmark"
        },
        {
          "href": "https://example.org/image/v1.0/images/1357163d...c526206",
          "rel": "alternate"
        }
      ],
      "metadata": {
        "partition_table": "msdos",
        "osfamily": "windows",
        "users": "Administratior",
        "exclude_task_changepassword": "yes",
        "os": "WinME",
        "root_partition": "1",
        "description": "Rerto Windows"
      }
    }
  ]
}

Get Image Details

Get the details of a specific image

Request

URI Method Cyclades OS/Compute
/images/<image-id> GET ✔ ✔
  • image-id is the identifier of the virtual image

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

Response

Return Code Description
200 (OK) Request succeeded
400 (Bad Request) Malformed image id
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Not allowed to use this image
404 (Not Found) Image not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) No available backends or service currently
unavailable

Response body contents:

image: {
  <image attribute>: <value>,
  ...
  metadata: {
    <image meta key>: <value>
  }
}

Image attributes are listed here.

Example Details for an image with id 6404619d-...-aef57eaff4af, in JSON

{
"image": {
  "id": "6404619d-...-aef57eaff4af",
  "name": "FreeBSD",
  "status": "ACTIVE",
  "updated": "2013-04-24T12:06:02+00:00",
  "created": "2013-04-24T11:52:16+00:00",
  "progress": 100,
  "links": [
    {
      "href": "https://example.org/compute/v2.0/images/6404619d-...-aef57eaff4af",
      "rel": "self"
    },
    {
      "href": "https://example.org/compute/v2.0/images/6404619d-...-aef57eaff4af",
      "rel": "bookmark"
    },
    {
      "href": "https://example.org/image/v1.0/images/6404619d-...-aef57eaff4af",
      "rel": "alternate"
    }
  ],
  "metadata": {
    "kernel": "9.1 RELEASE",
    "osfamily": "freebsd",
    "users": "root",
    "gui": "No GUI",
    "sortorder": "9",
    "os": "freebsd",
    "root_partition": "2",
    "description": "FreeBSD 9"
    }
  }
}

Delete Image

Delete an image, by changing its status from ACTIVE to DELETED.

Request

URI Method Cyclades OS/Compute
/images/<image id> DELETE ✔ ✔
  • image id is the identifier of the image

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

Response

Return Code Description
204 (OK) Request succeeded
400 (Bad Request) Invalid request or image id
401 (Unauthorized) Missing or expired user token
404 (Not Found) Image not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) Action not supported or service currently
unavailable

Note

In case of a 204 code, request body should be empty

List Image Metadata

Request

URI Method Cyclades OS/Compute
/images/<image-id>/metadata GET ✔ ✔
  • image-id is the identifier of the virtual image

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

Response

Return Code Description
201 (OK) Request succeeded
400 (Bad Request) Invalid image ID or Malformed request
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Administratively suspended server
404 (Not Found) Server not found
409 (Build In Progress) The image is not ready yet
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response body content:

metadata: {
  <meta key>: <value>,
...
}

Example List Image Metadata: JSON

{
  "metadata": {
    "partition_table": "msdos",
    "kernel": "3.2.0",
    "osfamily": "linux",
    "users": "user",
    "gui": "Unity 5",
    "sortorder": "3",
    "os": "ubuntu",
    "root_partition": "1",
    "description": "Ubuntu 12 LTS"
  }
}

Note

In OS/Compute API the values level is missing from the response.

Update Image Metadata

In Cyclades API, setting new metadata and updating the values of existing ones is achieved using one type of request (POST), while in OS/Compute API two different types are used (PUT and POST for setting new and updating existing metadata, respectively).

In Cyclades API, unmentioned metadata keys will remain intact, while metadata referred by the operation will be overwritten.

Request

URI Method Cyclades OS/Compute
/images/<image-id>/metadata PUT ✘ ✔
/images/<image-id>/metadata POST ✔ ✔
  • image-id is the identifier of the virtual image

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required
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: 52

Note

Request parameters should be empty

Request body content:

metadata: {
  <meta key>: <value>,
  ...
}

Example Update Image Metadata Request: JSON

{"metadata": {"NewAttr": "NewVal", "os": "Xubuntu'}}

Response

Return Code Description
201 (OK) Request succeeded
400 (Bad Request) Malformed request or image id
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Not allowed to modify this image
404 (Not Found) Image or meta key not found
413 (OverLimit) Maximum number of metadata exceeded
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response body content:

metadata: {
  <key>: <value>,
  ...
}

Example Update Image Response: JSON

{
  "metadata": {
    "partition_table": "msdos",
    "kernel": "3.2.0",
    "osfamily": "linux",
    "users": "user",
    "gui": "Unity 5",
    "sortorder": "3",
    "os": "Xubuntu",
    "root_partition": "1",
    "description": "Ubuntu 12 LTS",
    "NewAttr": "NewVal"
  }
}

Get Image Metadata

Request

URI Method Cyclades OS/Compute
/images/<image-id>/metadata/<key> GET ✔ ✔
  • image-id is the identifier of the image
  • key is the key of a mata key:value pair

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

Response

Return Code Description
200 (OK) Request succeeded
400 (Bad Request) Malformed request or image id
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Not allowed to access this information
404 (Not Found) Meta key not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Response body content:

metadata: {<key>: <value>}

Example Get Image Metadata Item: JSON

{"metadata": {"os": "Xubuntu"}}

Note

In OS/Compute, metadata is meta

Update Image Metadata

Request

URI Method Cyclades OS/Compute
/images/<image-id>/metadata/<key> PUT ✔ ✔
  • image-id is the identifier of the image
  • key is the key of a matadata key:value pair

Request Header Value Cyclades OS/Compute
X-Auth-Token User authentication token required required
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: 27

Note

Request parameters should be empty

Request body content:

metadata: {<key>: <value>}

Example Update Image Metadata Item Request: JSON

{"metadata": {"os": "Kubuntu"}}

Response

Return Code Description
201 (OK) Request succeeded
400 (Bad Request) Malformed request or image id
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Not allowed to modify this image
404 (Not Found) Metadata key not found
413 (OverLimit) Maximum number of metadata exceeded
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Request body content:

metadata: {<key>: <value>}

Example Update Image Metadata Item Response: JSON

{"metadata": {"os": "Kubuntu"}}

Delete Image Metadata

Delete an image metadata by its key.

Request

URI Method Cyclades OS/Compute
/images/<image-id>/metadata/<key> DELETE ✔ ✔
  • image-id is the identifier of the image
  • key is the key of a mata key:value pair

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

Response

Return Code Description
204 (OK) Request succeeded
400 (Bad Request) Malformed image ID
401 (Unauthorized) Missing or expired user token
403 (Forbidden) Not allowed to modify this image
404 (Not Found) Metadata key not found
500 (Internal Server Error) The request cannot be completed because of an
internal error
503 (Service Unavailable) The server is not currently available

Note

In case of a 204 code, the response body should be empty.

Index of Attributes

Server Attributes

Server attribute Cyclades OS/Compute
id ✔ ✔
name ✔ ✔
addresses ✔ ✔
links ✔ ✔
image ✔ ✔
flavor ✔ ✔
user_id ✔ ✔
tenant_id ✔ ✔
accessIPv4 ✔ ✔
accessIPv6 ✔ ✔
progress ✔ ✔
status ✔ ✔
updated ✔ ✔
hostId ✔ ✔
created ✔ ✔
adminPass ✔ ✔
metadata ✔ ✔
suspended ✔ ✘
security_groups ✔ ✘
attachments ✔ ✘
config_drive ✔ ✘
SNF:fqdn ✔ ✘
key_name ✔ ✘
SNF:port_forwarding ✔ ✘
SNF:task_state ✔ ✘
diagnostics ✔ ✘
deleted ✔ ✘
  • addresses Networks related to this server. All information in this field is redundant, since it can be infered from the attachments field, but it is used for compatibility with OS/Computet
  • user_id The UUID of the owner of the virtual server
  • tenant_id The UUID of the main project for this user
  • hostId, accessIPv4 and accessIPv6 are always empty and are used for compatibility with OS/Compute
  • progress Shows the building progress of a virtual server. After the server is built, it is always 100
  • status values are described here
  • updated and created are date-formated
  • adminPass is shown only once (in create server response). This information is not preserved in a clear text form, so it is not recoverable
  • suspended is True only if the server is suspended by the cloud administrations or policy
  • progress is a number between 0 and 100 and reflects the server building status
  • metadata are custom key:value pairs. In Cyclades, the OS and USERS metadata are automatically retrieved from the servers image during creation
  • attachments List of connection ports. Details here.

Server Status

Status Description Cyclades OS/Compute
BUILD Building ✔ ✔
ACTIVE Up and running ✔ ✔
STOPPED Shut down ✔ ✘
REBOOT Rebooting ✔ ✔
DELETED Removed ✔ ✔
UNKNOWN Unexpected error ✔ ✔
ERROR In error ✔ ✔
HARD_REBOOT Hard rebooting ✘ ✔
PASSWORD Resetting password ✘ ✔
REBUILD Rebuilding server ✘ ✔
RESCUE In rescue mode ✘ ✔
RESIZE Resizing ✘ ✔
REVERT_RESIZE Failed to resize ✘ ✔
SHUTOFF Shut down by user ✘ ✔
SUSPENDED Suspended ✘ ✔
VERIFY_RESIZE Waiting confirmation ✘ ✔

Attachments (ports)

In Cyclades, a port connects a virtual server to a public or private network.

Ports can be handled separately through the Cyclades/Network API.

In a virtual server context, a port may contain the following information:

Port Attributes Description
id Port id
mac_address NIC's mac address
network_id Network ID
OS-EXT-IPS:type fixed or floating
firewallProfile ENABLED, DISABLED, PROTECTED
ipv4 IP v4 address
ipv6 IP v6 address
  • ipv4 and ipv6 are mutually exclusive in practice, since a port
    either handles an IPv4, an IPv6, or none, but not both.

Flavor

A flavor is a hardware configuration for a server. It contains the following information:

Flavor Attributes Description Cyclades OS/Compute
id The flavor id ✔ ✔
name The flavor name ✔ ✔
ram Server RAM size ✔ ✔
SNF:disk_template Storage mechanism ✔ ✘
disk Server disk size ✔ ✔
vcpus # of Virtual CPUs ✔ ✔
links rel Atom link rel field ✘ ✔
links href Atom link href field ✘ ✔
  • id is the flavor unique id (a possitive integer)
  • name is the flavor name (a string)
  • ram is the server RAM size in MB
  • SNF:disk_template is a reference to the underlying storage mechanism used by the Cyclades server. It is Cyclades specific.
  • disk the servers disk size in GB
  • vcpus refer to the number of virtual CPUs assigned to a server
  • link ref and link href refer to the Atom link attributes that are used in OS/Compute API.

Image

An image is a collection of files you use to create or rebuild a server.

An image item may have the fields presented bellow:

Image Attributes Description Cyclades OS/Compute
id Image ID ✔ ✔
name Image name ✔ ✔
updated Last update date ✔ ✔
created Image creation date ✔ ✔
progress Ready status progress ✔ ✘
status Image status ✘ ✔
tenant_id Image creator ✘ ✔
user_id Image users ✘ ✔
metadata Custom metadata ✔ ✔
links Atom links ✘ ✔
minDisk Minimum required disk ✘ ✔
minRam Minimum required RAM ✘ ✔
  • id is the image id and name is the image name. They are both strings.
  • updated and created are both ISO8601 date strings
  • progress varies between 0 and 100 and denotes the status of the image
  • metadata is a collection of key:values pairs of custom metadata, under the tag values which lies under the tag metadata.

Note

in OS/Compute, the values layer is missing