Overview

How does Cloud Servers work?

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.

The optional supernova client lets you to use the nova client with multiple OpenStack nova environments. For example, if you maintain multiple Cloud Servers accounts or call different cloud services, you can export a different set of environment variables for each environment. Then, when you run supernova, you pass a parameter that indicates which environment you want to use.

Though this guide does not explicitly show supernova client commands, you can easily modify the examples in this guide for supernova. The supernova client commands are identical to the nova client commands except that you include the parameter in each supernova command that indicates which environment you are sourcing. For example, you might run the following supernova command to source the production environment and list images:

$ supernova production image-list

You install the supernova client through the supernova package in the section called “Step 3. (Optional) Install the supernova Client”.

After you install the client, you must create a supernova profile that defines nova environment variables for one or more environments.

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

Rackspace does not maintain the nova and supernova clients, which are considered to be software in development.

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:

$ 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

	Note
	The carriage returns in the cURL request examples are escaped with a backslash (\) 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:

json.tool

For commands that return a response, you can append the following code to the command to call the json.tool to pretty-print output: | python -m json.tool To use the json.tool, import the json module. For information about the json.tool, see json — JSON encoder and decoder. If you run a Python version older than 2.6, import the simplejson module and use the simplejson.tool. For information about the simple.json tool, see simplejson — JSON encoder and decoder. If you do not want to pretty-print JSON output, omit this code.

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

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

<?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"
  name="api-test-server-xml2">
  <metadata>
    <meta key="My Server Name">API Test Server XML</meta>
  </metadata>
  <personality>
    <file path="/etc/banner.txt">
      ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
      dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
      IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
      c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
      QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
      ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
      dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
      c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
      b25zLiINCg0KLVJpY2hhcmQgQmFjaA==</file>
  </personality>
  <networks>
    <uuid>0ef47ac7-6797-4e01-8a47-ed26ec3aaa56</uuid>
    <uuid>00000000-0000-0000-0000-000000000000</uuid>
    <uuid>11111111-1111-1111-1111-111111111111</uuid>
  </networks>
</server>

<?xml version='1.0' encoding='UTF-8'?>
<server
    xmlns:OS-DCF="http://docs.openstack.org/compute/ext/disk_config/api/v1.1"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://docs.openstack.org/compute/api/v1.1"
    id="ed5c7754-29b6-45fa-96cb-ab64958c8c0a" adminPass="Dd5pNZtpVVQ3"
    OS-DCF:diskConfig="AUTO">
    <metadata/>
    <atom:link
        href="https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/ed5c7754-29b6-45fa-96cb-ab64958c8c0a"
        rel="self"/>
    <atom:link
        href="https://dfw.servers.api.rackspacecloud.com/010101/servers/ed5c7754-29b6-45fa-96cb-ab64958c8c0a"
        rel="bookmark"/>
</server>

Next generation Cloud Servers is part of the Rackspace Cloud and your use through the API will be billed as per 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.