The next generation Cloud Servers powered by OpenStack is a fast, reliable, and scalable cloud compute solution that lets you provision servers in the Rackspace cloud in minutes.

Cloud Servers provides the core features of the OpenStack Compute API v2 and also deploys certain Rackspace extensions. The OpenStack Compute API and the Rackspace extensions are known collectively as API v2.

The simple exercises in this guide help you get started with the API v2.


Before using the available API and cURL commands to create and manage a server, you need to authenticate. Please review the section called “Step 3. Authenticate” for more information about authentication.

For each exercise in this guide, you choose one of the following methods to make API v2 calls:

  • The nova client. We recommend that you use the nova client to run simple commands that make API v2 calls. These open-source Python clients run on Linux or Mac OS X systems and are easy to learn and use. You can specify a debug parameter on any nova to show the underlying API v2 request for the command. This is a good way to become familiar with the API v2 requests.

    See the section called “How the nova Client Works”.


    There is an optional supernova client, which is useful for managing multiple nova environments, but it is not supported.

  • cURL commands. If you are familiar with or want to learn cURL commands, choose this method. With cURL, you send HTTP requests with embedded API v2 calls from the command line. The cURL examples in this guide include request bodies that are in JSON format. See the section called “How cURL Commands Work”.

If you like, you can use cURL in one example and switch to the nova client in the next example. If you choose to use a cURL command for any example, you must export the environment variables required to run the cURL examples. See the section called “Step 4. (Optional) Export Environment Variables to Run cURL Commands”.

Each example, whether nova client or cURL, points you to the next step in the process.

To use the API v2, it helps to be familiar with HTTP/1.1, RESTful web services, the Rackspace Cloud Servers service, and JSON or XML data serialization formats.

We welcome feedback, comments, and bug reports at http://feedback.rackspace.com/.

 How Cloud Servers Works

  1. Select a region for your Cloud Server


    To help you decide which regionalized endpoint to use, read about special considerations for choosing a data center at http://www.rackspace.com/knowledge_center/article/about-regions.

  2. Select your operating system

    Choose from a variety of popular Linux® or Windows distributions. The operating system for a server is known as its image.

  3. Select a flavor for your Cloud Server

    Cloud Server flavors are a combination of RAM, disk space, disk I/O, vCPUs, and network throughput.

    For more information on flavors, see the section called “Flavors”.

  4. Your server is online in just a few minutes

    By using either our online control panel or the API directly, you can upgrade or remove each Cloud Server as your needs change. You can manage your Cloud Servers through the Cloud Control Panel or through a program or script that calls the API v2, which requires some coding effort.

    The simple exercises in this guide help you get started with the API v2 by showing you how to access the API through nova client commands or cURL commands.

 How the nova Client Works

The nova client is an open-source Python client that lets you run simple commands to make API v2 calls. This client is easy to learn and use. Each nova client command runs cURL commands that embed API v2 requests. You can run the nova client from a desktop machine or remote system, such as a Cloud Server.

You install the nova client on a Linux distribution or on Mac OS X. You install the nova client in the section called “Step 2. Install the nova Client with the Cloud Networks Extension”.

To configure the nova client, you update your bash profile to set and export nova environment variables.


You can specify a debug parameter on any nova command to show the underlying API request for the command. This is a good way to become familiar with the API requests.


If you upgrade the operating system of the desktop or remote machine where you installed nova, you may need to reinstall nova.

 How cURL Commands Work

cURL is a command-line tool that you can use to interact with REST interfaces. cURL lets you to transmit and receive HTTP requests and responses from the command line or a shell script, which enables you to work with the API directly. It is available for Linux distributions, Mac OS X, and Windows. For information about cURL, see http://curl.haxx.se/.

To use XML requests and responses, see the section called “XML Requests and Responses”.

To run the cURL request examples shown in this guide, copy each example from the HTML version of this guide directly to the command line or a script.

The following command is an example cURL command that provisions a server with an isolated network:


Example 1. cURL Command Example: JSON Request

$ curl https://dfw.servers.api.rackspacecloud.com/v2/$account/servers \
       -X POST \
       -H "X-Auth-Project-Id: $account" \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "X-Auth-Token: $token" \
       -d '{"server": {"name": "my_server_with_network", "imageRef": "d42f821e-c2d1-4796-9f07-af5ed7912d0e", "flavorRef": "2", "max_count": 1, "min_count": 1, "networks": [{"uuid": "538a112a-34d1-47ff-bf1e-c40639e886e2"}, {"uuid": "00000000-0000-0000-0000-000000000000"}, {"uuid": "11111111-1111-1111-1111-111111111111"}]}}' \
      | python -m json.tool


The carriage returns in the cURL request examples use a backslash (\) as an escape character. The escape character allows continuation of the command across multiple lines. However, do not include the escape character in the JSON or XML request body within the cURL command.

The cURL examples in this guide use the following command-line options:

Table 1. cURL Command-Line Options
Option Description

Sends the specified data in a POST request to the HTTP server. Use this option to send a JSON or XML request body to the server.


Specifies an extra HTTP header in the request. You can specify any number of extra headers. Precede each header with the -H option.

Common headers in Rackspace API requests are as follows:

  • Content-Type. Required for operations with a request body.

    Specifies the format of the request body. Following is the syntax for the header where format is either json or xml.

    Content-Type: application/format
  • X-Auth-Token. Required. Specifies the authentication token.

  • X-Auth-Project-Id. Optional. Specifies the project ID, which can be your account number or another value.

  • Accept. Optional.

    Specifies the format of the response body. Following is the syntax for the header where format is either json or xml. The default is json.

    Accept: application/format

Includes the HTTP header in the output.


Specifies silent or quiet mode, which makes cURL mute. No progress or error messages are shown.


Transfers the specified local file to the remote URL.


Specifies the request method to use when communicating with the HTTP server. The specified request is used instead of the default method, which is GET.

[Note] Note

For commands that return a response, you can append the following code to the command to call json.tool to pretty-print output:

| python -m json.tool

To use json.tool, import the json module. For information about json.tool, see json — JSON encoder and decoder.

If you run a Python version older than 2.6, import the simplejson module and use simplejson.tool. For information about simplejson.tool, see simplejson — JSON encoder and decoder.

If you do not want to pretty-print JSON output, omit this code.

 XML Requests and Responses

The following example shows a cURL command that specifies an XML request body and returns an XML response. The command creates a server.


Example 2. cURL Command Example: XML Request

$ curl -i https://dfw.servers.api.rackspacecloud.com/v2/$account/servers.xml \        (1)
     -X POST \
     -H "X-Auth-Project-Id: $account" \
     -H "Content-Type: application/xml" \    (2)
     -H "Accept: application/xml" \    (3)
     -H "X-Auth-Token: $token" \
     -T server_post_req.xml (4)| ppxml  (5)        

This example includes the following changes to the basic JSON request format in Example 1, “cURL Command Example: JSON Request”:


The endpoint in the cURL command has .xml appended to it to return an XML response.


The Content-Type: header specifies application/xml instead of application/json.


The Accept: header specifies application/xml instead of application/json.


The request body, if required, should be specified it in XML format. In this example, the XML body is passed in the server_post_req.xml file, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<server xmlns="http://docs.openstack.org/compute/api/v1.1" imageRef="3afe97b2-26dc-49c5-a2cc-a2fc8d80c001" flavorRef="2"
    <meta key="My Server Name">API Test Server XML</meta>
    <file path="/etc/banner.txt"> ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
      dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
      c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
      ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
      c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA==</file>
    <network uuid="0ef47ac7-6797-4e01-8a47-ed26ec3aaa56"/>
    <network uuid="00000000-0000-0000-0000-000000000000"/>
    <network uuid="11111111-1111-1111-1111-111111111111"/>


To pretty-print the XML output, set the ppxml alias, as follows:

$ alias ppxml='python -c "import sys, xml.dom.minidom; print xml.dom.minidom.parseString(sys.stdin.read()).toprettyxml()"'

Then, append the ppxml alias to the cURL command.

The cURL command returns information about the new server in XML format, as shown in the following example.


Example 3. cURL Command Example: XML Response

<?xml version='1.0' encoding='UTF-8'?>
    id="ed5c7754-29b6-45fa-96cb-ab64958c8c0a" adminPass="Dd5pNZtpVVQ3"


The term flavor refers to a server's combination of RAM size, vCPUs, disk I/O, network throughput, and disk space. You build a Linux or Windows server by choosing its flavor. You also use flavors to choose between cloud servers, which are multi-tenant virtual servers, and OnMetal servers, which are single-tenant physical servers.

 Virtual Cloud Server Flavors

Cloud Server Flavors are divided into two classes: Standard and Performance, with the following distinctions:

  • Standard flavors range in size from 512 MB to 30 GB and use a single disk for system and data information storage. These flavors are recommended for general-purpose workloads. All storage is located on RAID 10-protected SATA hard disk drives.

  • Performance flavors range in size from 1 GB to 120 GB of RAM and have separate system and data disks. They also offer significantly faster disk I/O. All storage is located on RAID 10-protected SSD hard disk drives.

Performance flavors are subdivided into two types: Performance 1 (P1) and Performance 2 (P2).

  • P1 flavors have the following characteristics:

    • Sizes range from 1 GB to 8 GB.

    • Linux servers can be any size. Windows servers must be 2 GB or larger.

    • These servers are built for many use cases, from general-purpose workloads to high performance websites.

    • vCPUs are oversubscribed and “burstable”, which means that there are more vCPUs allocated to the Cloud Servers on a physical host than there are physical CPU threads. This over-subscription model assumes that under normal conditions not all vCPUs will be needed by all Cloud Servers at the same time, and allows your Cloud Server to take advantage of those additional resources during such times of under-utilization.

  • P2 flavors have the following characteristics:

    • Sizes range from 15 GB to 120 GB.

    • These servers are ideal for high performance applications and databases that benefit from fast disk I/O, such as Cassandra and MongoDB.

    • vCPUs are “reserved”, which means that there are never more vCPUs allocated to the Cloud Servers on a physical host than there are physical CPU threads on that host. This model ensures that your Cloud Server will always have full access to all its vCPUs.

If you require additional storage beyond what is provided by the local disks on a specific flavor, you can extend both Standard and Performance flavors with Cloud Block Storage.

 OnMetal Cloud Server Flavors

OnMetal Cloud Server flavors differ significantly from Virtual Cloud Server flavors. Virtual Cloud Server flavors are used to create virtual servers with a hypervisor to manage multi-tenancy, which means one or more virtual instances are located on the same physical server. OnMetal Cloud Server flavors are used to rapidly build a server instance on a physical server with no hypervisor and no multi-tenancy.

There are three configurations within the OnMetal flavor class.

  • Compute - recommended for high CPU activity like network requests, application logic, web servers, load balancers, and so on.

  • Memory - recommended for high RAM activity like in-memory SQL configurations, caching, searching indexes, and so on.

  • IO - recommended for high I/O activity like NoSQL and SQL databases.

OnMetal server disk space may not be extended with Cloud Block Storage.

 Pricing and Service Level

Next generation Cloud Servers is part of the Rackspace Cloud and your use through the API is billed according to the pricing schedule at http://www.rackspace.com/cloud/public/servers/pricing.

The Service Level Agreement (SLA) for Cloud Servers is available at http://www.rackspace.com/cloud/legal/sla/#cloud_servers.