cs gettingstarted 20150528

docs.rackspace.com/api

Next Generation Cloud ServersGetting Started

May 28, 2015 API v2

ii

Next Generation Cloud Servers Getting StartedAPI v2 (2015-05-28)2015 Rackspace US, Inc.

This document is intended for software developers who want to develop applications by using the next generation Rackspace CloudServers powered by OpenStack. In addition to the core features of the OpenStack Compute Application Programming Interface(API) v2, Rackspace has deployed certain extensions as permitted by the OpenStack Compute API contract. The document is for infor-mational purposes only and is provided AS IS.

RACKSPACE MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, AS TO THE ACCURACY OR COM-PLETENESS OF THE CONTENTS OF THIS DOCUMENT AND RESERVES THE RIGHT TO MAKE CHANGES TO SPECIFICATIONS AND PROD-UCT/SERVICES DESCRIPTION AT ANY TIME WITHOUT NOTICE. RACKSPACE SERVICES OFFERINGS ARE SUBJECT TO CHANGE WITH-OUT NOTICE. USERS MUST TAKE FULL RESPONSIBILITY FOR APPLICATION OF ANY SERVICES MENTIONED HEREIN. EXCEPT AS SETFORTH IN RACKSPACE GENERAL TERMS AND CONDITIONS AND/OR CLOUD TERMS OF SERVICE, RACKSPACE ASSUMES NO LIABILITYWHATSOEVER, AND DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO ITS SERVICES INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

Except as expressly provided in any written license agreement from Rackspace, the furnishing of this document does not give you anylicense to patents, trademarks, copyrights, or other intellectual property.

Rackspace, Rackspace logo and Fanatical Support are registered service marks of Rackspace US, Inc. All other product names andtrademarks used in this document are for identification purposes only and are property of their respective owners.


May 28, 2015 API v2

iii

Table of ContentsOverview ......................................................................................................................... 1

How Cloud Servers Works ....................................................................................... 3How the nova Client Works .................................................................................... 4How cURL Commands Work ................................................................................... 5Flavors .................................................................................................................... 8Pricing and Service Level ....................................................................................... 12

Create Your First Cloud Server ....................................................................................... 13Step 1. Sign up for a Rackspace Cloud Account ..................................................... 14Step 2. Install the nova Client with the Cloud Networks Extension .......................... 15Step 3. Authenticate ............................................................................................. 21Step 4. (Optional) Export Environment Variables to Run cURL Commands .............. 28Step 5. List Images ................................................................................................ 29Step 6. List Flavors ................................................................................................ 34Step 7. Create and Boot Your Server ..................................................................... 38Step 8. Get Server Details ...................................................................................... 42Step 9. List Servers and Attached Networks ........................................................... 47Step 10. Set up Ubuntu ......................................................................................... 52Step 11. Manage Your Server ................................................................................ 54Step 12. Delete Your Server .................................................................................. 55

Create Your First Cloud Network ................................................................................... 57Step 1. Create an Isolated Network ....................................................................... 57Step 2. List Networks ............................................................................................ 59Step 3. Provision a Server with an Isolated Network .............................................. 61Step 4. List Servers ................................................................................................ 67Step 5. Show Network Information ....................................................................... 71Step 6. Delete Your Network ................................................................................ 73

Attach Your Network to an Existing Server ................................................................... 76Step 1. Install the Cloud Networks Virtual Interface Extension ................................ 77Step 2. List Servers ................................................................................................ 78Step 3. List Networks ............................................................................................ 82Step 4. Create a Virtual Interface .......................................................................... 84Step 5. List Virtual Interfaces for a Server .............................................................. 86Step 6. Delete a Virtual Interface from a Server ..................................................... 90

nova Client Command Summary .................................................................................... 92Limits .................................................................................................................... 92Servers .................................................................................................................. 92Server Key Pairs ..................................................................................................... 93Server Actions ....................................................................................................... 94Flavors ................................................................................................................... 96Images .................................................................................................................. 96Metadata .............................................................................................................. 96Networks .............................................................................................................. 96Virtual Interfaces ................................................................................................... 99

Environment Variables for the nova Client ................................................................... 101cURL Command Summary ........................................................................................... 103

Limits .................................................................................................................. 103Servers ................................................................................................................. 103Server Actions ..................................................................................................... 104


May 28, 2015 API v2

iv

Flavors ................................................................................................................. 106Images ................................................................................................................ 106Metadata ............................................................................................................ 106Networks ............................................................................................................. 107Virtual Interfaces ................................................................................................. 107

Document Change History ........................................................................................... 109Resources .................................................................................................................... 112Glossary ....................................................................................................................... 113


May 28, 2015 API v2

v

List of Tables1. cURL Command-Line Options ...................................................................................... 62. Supported Flavors for Next Generation Cloud Servers ................................................ 103. Nova Client Prerequisite Software ............................................................................. 154. Show Network Response Fields ................................................................................. 715. Environment Variables for the nova Client ............................................................... 101


May 28, 2015 API v2

1

OverviewHow Cloud Servers Works ............................................................................................... 3How the nova Client Works ............................................................................................ 4How cURL Commands Work ........................................................................................... 5Flavors ............................................................................................................................ 8Pricing and Service Level ............................................................................................... 12

The next generation Cloud Servers powered by OpenStack is a fast, reliable, and scalablecloud 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 de-ploys certain Rackspace extensions. The OpenStack Compute API and the Rackspace exten-sions are known collectively as API v2.

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

NoteBefore using the available API and cURL commands to create and manage aserver, you need to authenticate. Please review the section called Step 3. Au-thenticate [21] for more information about authentication.

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

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

See the section called How the nova Client Works [4].

NoteThere is an optional supernova client, which is useful for managing multiplenova environments, but it is not supported.

cURL commands. If you are familiar with or want to learn cURL commands, choose thismethod. With cURL, you send HTTP requests with embedded API v2 calls from the com-mand line. The cURL examples in this guide include request bodies that are in JSON for-mat. See the section called How cURL Commands Work [5].

If you like, you can use cURL in one example and switch to the nova client in the next exam-ple. If you choose to use a cURL command for any example, you must export the environ-ment variables required to run the cURL examples. See the section called Step 4. (Option-al) Export Environment Variables to Run cURL Commands [28].

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 RackspaceCloud Servers service, and the JSON data serialization format.


May 28, 2015 API v2

2

Important

During 2015, all First Generation servers will be migrated to Next Generationservers, on a rolling basis.

Notification from Rackspace will be sent to customers informing them of their30-day window to complete the migration of the specified servers. If you takeno action, your server will be migrated for you.

To migrate your servers, during your migration window, simply perform a SOFTreboot on your first gen server, either from the Control Panel or by using the re-boot API operation. The migration process will preserve all data and configura-tion settings.

During the 30-day migration window, performing a HARD reboot on a first genserver will reboot the server without triggering the migration.

You can see information about your migration window's open and closedates, use the Get Server Details on your first gen server, and look in the meta-data section of the response for "FG2NG_self_migration_available_till" and"FG2NG_self_migration_available_from" key pairs. If your migration windowhas not been scheduled, you will not see these metadata keys.

For more information about the server migration see the Knowledge Center ar-ticle: First Generation to Next Generation cloud server migration FAQ

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


May 28, 2015 API v2

3

How Cloud Servers Works1. Select a region for your Cloud Server

Tip

To help you decide which regionalized endpoint to use, read about specialconsiderations 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 sys-tem 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 networkthroughput.

For more information on flavors, see the section called Flavors [8].

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 removeeach Cloud Server as your needs change. You can manage your Cloud Servers throughthe Cloud Control Panel or through a program or script that calls the API v2, which re-quires some coding effort.

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


May 28, 2015 API v2

4

How the nova Client WorksThe nova client is an open-source Python client that lets you run simple commands to makeAPI v2 calls. This client is easy to learn and use. Each nova client command runs cURL com-mands that embed API v2 requests. You can run the nova client from a desktop machine orremote system, such as a Cloud Server.

You install the nova client on a Linux distribution or on Mac OS X. You install the novaclient in the section called Step 2. Install the nova Client with the Cloud Networks Exten-sion [15].

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

Note

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

Warning

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


May 28, 2015 API v2

5

How cURL Commands WorkcURL is a command-line tool that you can use to interact with REST interfaces. cURL letsyou to transmit and receive HTTP requests and responses from the command line or a shellscript, 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 run the cURL request examples shown in this guide, copy each example from the HTMLversion 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 iso-lated network:

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

Note

The carriage returns in the cURL request examples use a backslash (\) as anescape character. The escape character allows continuation of the commandacross multiple lines. However, do not include the escape character in the JSONrequest body within the cURL command.


May 28, 2015 API v2

6

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

Table1.cURL Command-Line Options

Option Description

-d Sends the specified data in a POST request to theHTTP server. Use this option to send a JSON re-quest body to the server.

-H 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 areas follows:

Content-Type. Required for operations witha request body.

Specifies the format of the request body. Fol-lowing is the syntax for the header whereformat is json .Content-Type: application/format

X-Auth-Token. Required. Specifies the au-thentication token.

X-Auth-Project-Id. Optional. Specifies theproject ID, which can be your account numberor another value.

Accept. Optional.

Specifies the format of the response body.Following is the syntax for the header whereformat is json. If no format is specified, thedefault is json.Accept: application/format

-i Includes the HTTP header in the output.

-s Specifies silent or quiet mode, which makes cURLmute. No progress or error messages are shown.

-T Transfers the specified local file to the remoteURL.

-X Specifies the request method to use when com-municating with the HTTP server. The specifiedrequest is used instead of the default method,which is GET.

Note

For commands that return a response, you can append the following code tothe 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, seejson JSON encoder and decoder.

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


May 28, 2015 API v2

7

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


May 28, 2015 API v2

8

FlavorsThe term flavor refers to a server's combination of RAM size, vCPUs, network throughput(RXTX factor), and disk space. You build a Linux or Windows server by choosing its fla-vor. You also use flavors to choose between cloud servers, which are multi-tenant virtualservers, and OnMetal servers, which are single-tenant physical servers.

Virtual Cloud Server FlavorsVirtual Cloud Server Flavors are divided into the following classes:

Standard These flavors, which are being phased out and should not beused for new servers, have the following characteristics:

Sizes range from 512 MB to 30 GB.

These flavors are recommended for general-purpose work-loads.

They use a single disk for system and data information stor-age.

All storage is located on RAID 10-protected SATA hard diskdrives.

General Purpose v1 These flavors, formerly Performance 1, have the following char-acteristics:

Sizes range from 1 GB to 8 GB.

Linux servers can be any size. Windows servers must be 2 GBor larger.

These flavors are useful for many use cases, from general-pur-pose workloads to high performance websites.

They use a single disk for system and data information stor-age.

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

All storage is located on RAID 10-protected SSD hard diskdrives.

I/O v1 These flavors, formerly Performance 2, have the following char-acteristics:


May 28, 2015 API v2

9


These flavors are ideal for high performance applications anddatabases that benefit from fast disk I/O, such as Cassandraand MongoDB.

They have separate system and data disks.

vCPUs are reserved, which means that there are never morevCPUs allocated to the Cloud Servers on a physical host thanthere are physical CPU threads on that host. This model en-sures that your Cloud Server will always have full access to allits vCPUs.


Compute v1 These flavors have the following characteristics:

Sizes range from 3.75 GB to 60 GB.

These flavors are optimized for web servers, applicationservers, and other CPU-intensive workloads.

They have no local data disks.

They are backed by Cloud Block Storage (additional chargesapply for Cloud Block Storage).

vCPUs are reserved, which means that there are never morevCPUs allocated to the Cloud Servers on a physical host thanthere are physical CPU threads on that host. This model en-sures that your Cloud Server will always have full access to allits vCPUs.


Memory v1 These flavors have the following characteristics:


These flavors are recommended for memory-intensive work-loads.

They have no local data disks.

They are backed by Cloud Block Storage (additional chargesapply for Cloud Block Storage).

vCPUs are reserved, which means that there are never morevCPUs allocated to the Cloud Servers on a physical host thanthere are physical CPU threads on that host. This model en-


May 28, 2015 API v2

10

sures that your Cloud Server will always have full access to allits vCPUs.


If you require additional storage beyond what is provided by the local disks on a specific fla-vor, you can extend all the preceding server flavors with Cloud Block Storage.

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

There are three configurations within the OnMetal flavor class.

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

OnMetal Memory - recommended for high RAM activity like in-memory SQL configura-tions, caching, searching indexes, and so on.

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

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

Supported Flavors for Cloud ServersThe Rackspace Cloud Servers service currently supports the following flavors for next gener-ation Cloud Servers:

Table2.Supported Flavors for Next Generation Cloud Servers

ID Flavor name Memory (MB) Disk space Ephemeral VCPUs RXTX factor

2 512 MB Stan-dard Instance

512 20 0 1 80.0

3 1 GB StandardInstance

1024 40 0 1 120.0


2048 80 0 2 240.0


4096 160 0 2 400.0


8192 320 0 4 600.0


15360 620 0 6 800.0


30720 1200 0 8 1200.0

general1-1 1 GB GeneralPurpose v1

1024 20 0 1 200.0


May 28, 2015 API v2

11

ID Flavor name Memory (MB) Disk space Ephemeral VCPUs RXTX factor


2048 40 0 2 400.0


4096 80 0 4 800.0


8192 160 0 8 1600.0

compute1-4 3.75 GB Com-pute v1

3840 0 0 2 625.0

compute1-8 7.5 GB Com-pute v1

7680 0 0 4 1250.0

compute1-15 15 GB Computev1

15360 0 0 8 2500.0


30720 0 0 16 5000.0


61440 0 0 32 10000.0

io1-15 15 GB I/O v1 15360 40 150 4 1250.0

io1-30 30 GB I/O v1 30720 40 300 8 2500.0

io1-60 60 GB I/O v1 61440 40 600 16 5000.0

io1-90 90 GB I/O v1 92160 40 900 24 7500.0

io1-120 120 GB I/O v1 122880 40 1200 32 10000.0

memory1-15 15 GB Memoryv1

15360 0 0 2 625.0


30720 0 0 4 1250.0


61440 0 0 8 2500.0

memory1-120 120 GB Memo-ry v1

122880 0 0 16 5000.0

memory1-240 240 GB Memo-ry v1

245760 0 0 32 10000.0

onmetal-com-pute1

OnMetal Com-pute v1

32768 32 0 20 10000.0

onmetal-io1 OnMetal I/O v1 131072 32 3200 40 10000.0

onmetal-mem-ory1

OnMetal Mem-ory v1

524288 32 0 24 10000.0


May 28, 2015 API v2

12

Pricing and Service LevelNext generation Cloud Servers is part of the Rackspace Cloud and your use through theAPI is billed according to the pricing schedule at http://www.rackspace.com/cloud/pub-lic/servers/pricing.

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


May 28, 2015 API v2

13

Create Your First Cloud ServerStep 1. Sign up for a Rackspace Cloud Account ............................................................. 14Step 2. Install the nova Client with the Cloud Networks Extension .................................. 15Step 3. Authenticate ..................................................................................................... 21Step 4. (Optional) Export Environment Variables to Run cURL Commands ...................... 28Step 5. List Images ........................................................................................................ 29Step 6. List Flavors ........................................................................................................ 34Step 7. Create and Boot Your Server ............................................................................. 38Step 8. Get Server Details .............................................................................................. 42Step 9. List Servers and Attached Networks ................................................................... 47Step 10. Set up Ubuntu ................................................................................................. 52Step 11. Manage Your Server ........................................................................................ 54Step 12. Delete Your Server .......................................................................................... 55

These examples walk you through the steps to create an Ubuntu 11.10 server instancewith 8 GBs of physical memory. The simple exercises show you how to access the API v2through nova client commands or cURL commands so that you can quickly create and man-age servers. You can also opt to use the supernova client with the nova client if you usemultiple nova environments.

The exercises also help you learn how cURL commands and the API v2 work.

You can modify these examples to create other types and sizes of servers.


May 28, 2015 API v2

14

Step 1. Sign up for a Rackspace Cloud AccountIf you do not already have a Rackspace Cloud account, create one. Your account gives youpay-as-you-go access to Rackspace cloud products and you are charged only for the re-sources that you use.

To sign up for a Rackspace Cloud account:

1. Go to http://mycloud.rackspace.com and click Join the Cloud Now.

2. Select your account type, and follow the instructions.


May 28, 2015 API v2

15

Step 2. Install the nova Client with the Cloud Net-works Extension

If you want to run the cURL examples, skip this step and proceed to the section called Step3. Authenticate [21].

To manage your servers from the command line, you can use the open-source nova clientapplication called python-novaclient.

To install the nova client, you first install the rackspace-novaclient package, which in-cludes the nova client and the Rackspace extensions including the Cloud Networks exten-sion.

If you want to use the Cloud Networks virtual interface extension, you must also install theos_virtual_interfacesv2_python_novaclient_ext package.

Note

The python-novaclient is developed and maintained by the OpenStack commu-nity. While we do not directly support python-novaclient, you can post in thecomments below if you run into any difficulties.

Before you begin, install the following prerequisite software:

Table3.Nova Client Prerequisite Software

Prerequisite Description

Python 2.6 or later Currently, the nova client does not support Python 3.

setuptools package Installed by default on Mac OS X.

Many Linux distributions provide packages to make setuptools easy to install.

Search your package manager for setuptools to find an installation package.If you cannot find one, download the setuptools package directly from http://pypi.python.org/pypi/setuptools.

pip package To install the nova client on a Mac OS X or Linux system, use pip because it iseasy and ensures that you get the latest version of the nova client from thePython Package Index. Also, it lets you update the package later on.

Install pip through the package manager for your system:

Mac OS X

$ sudo easy_install pip

Ubuntu

$ aptitude install python-pip

Debian

$ aptitude install python-pip

Fedora

$ yum install python-pip

CentOS, or RHEL (from EPEL or another 3rd party repository)

$ yum install python-pip


May 28, 2015 API v2

16


May 28, 2015 API v2

17

To install the nova client with Rackspace extensions:

1. Install or update the nova client package with Rackspace extensions

The rackspace-novaclient package includes the nova client and Rackspace exten-sions, including the Cloud Networks extension.

Run the following command to install the rackspace-novaclient package:

$ sudo pip install rackspace-novaclient

Note

If you previously installed the rackspace-novaclient package, run thefollowing command for your operating system to upgrade it:

$ sudo pip install --upgrade rackspace-novaclient

Important

If you previously installed the earlierrax_networks_python_novaclient_ext package, run the follow-ing command for your operating system to remove it:

$ sudo pip uninstall rax_networks_python_novaclient_ext

If you have trouble using pip to install the nova client, you can:

Download a nova client installation package from the python packagerepository.

or

Use pip to individually install the python-novaclient andrackspace-auth-openstack packages.

or

Use python-pip or yum commands instead of pip.

2. Set environment variables

Edit your bash profile to add and set environment variables that enable the nova clientto connect to your Rackspace Cloud account. Use nano or an editor of your choice toedit your .bash_profile file:

$ nano ~/.bash_profile

Depending on your account location, add one of the following sets of lines to yourbash profile and save the file:


May 28, 2015 API v2

18

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

Example2.US Data Center Exampleexport OS_AUTH_URL=https://identity.api.rackspacecloud.com/v2.0/export OS_AUTH_SYSTEM=rackspaceexport OS_REGION_NAME=DFWexport OS_USERNAME=export OS_TENANT_NAME=export NOVA_RAX_AUTH=1export OS_PASSWORD=export OS_PROJECT_ID=export OS_NO_CACHE=1

Example3.UK Data Center Exampleexport OS_AUTH_URL=https://lon.identity.api.rackspacecloud.com/v2.0/export OS_AUTH_SYSTEM=rackspace_ukexport OS_REGION_NAME=LONexport OS_USERNAME=export OS_TENANT_NAME=export NOVA_RAX_AUTH=1export OS_PASSWORD=export OS_PROJECT_ID=export OS_NO_CACHE=1

For descriptions of the environment variables, see Environment Variables for the novaClient [101].

3. Set permissions on the bash profile

Because the bash profile contains a password, set permissions on it so other peoplecannot read it:

$ chmod 600 ~/.bash_profile

4. Source the environment variables

To source the variables to make them available in your current shell, run the followingcommand:

$ source ~/.bash_profile

5. Test the nova client

To verify that you can talk to the API server, authenticate and list images:

$ nova credentials $ nova image-list

6. Get help for nova client commands

To get help for nova client commands, run the following command:


May 28, 2015 API v2

19

$ nova help

To get help for a specific command, type the command name after the help parame-ter, as follows:

$ nova help

You cannot use every command that is listed. The nova client was written for use withrecent development versions of OpenStack, so it includes support for some featuresthat are not available in the Rackspace Cloud.

Note

To show and become familiar with the underlying API v2 request for acommand, specify the --debug parameter as the first parameter on anycommand. For example:

$ nova --debug list

7. Troubleshooting

The python-novaclient is developed and maintained by the OpenStack community.

If you cannot run commands successfully, make sure that you entered your username, password, and account number correctly in the bash profile file.

If you change any environment variables, either log out and back in or source yourbash profile again.

To override some environment variable settings, you can use the options thatare listed at the end of the nova help output. For example, you can override theOS_PASSWORD setting in the bash profile by specifying a password on a nova com-mand, as follows:

$ nova --password image-list

Where password is your Rackspace password.

While Rackspace does not directly support python-novaclient, if the above stepsdon't help, you can post a question in the comments below.


May 28, 2015 API v2

20


May 28, 2015 API v2

21

Step 3. AuthenticateTo authenticate access to Rackspace Cloud services, you issue an authentication request tothe Rackspace Cloud Identity Service, which is an implementation of the OpenStack Key-stone Identity Service v2.0, using this endpoint: https://identity.api.rackspacecloud.com/v2.0

In response to valid credentials, an authentication request to the Rackspace Cloud IdentityService returns an authentication token and a service catalog that contains a list of all ser-vices and endpoints available for this token. Because the authentication token expires after24 hours, you must generate a token once a day.

For detailed information about the OpenStack Keystone Identity Service v2.0, see CloudIdentity Client Developer Guide API v2.0. For information about support for legacy identityendpoints, see Alternate Authentication Endpoints.

Next step: Choose one of the following methods:

Authenticate with the nova client

Authenticate with cURL


May 28, 2015 API v2

22

Authenticate with the nova Client

To authenticate with the nova client:

1. Get an authentication token:

$ nova credentials

Successful authentication returns user credentials, including ID, name, roles, and theauthentication token. The token appears in the id field in the Token box.

+------------------

+---------------------------------------------------------------------------------------

+

| User Credentials | Value |+------------------

+---------------------------------------------------------------------------------------

+

| id | 170454 || name | MyRackspaceAcct || roles | [{u'description': u'User Admin Role.', u'id': u'3', u'name': u'identity:user-admin'}] |+------------------

+---------------------------------------------------------------------------------------

+

+---------+----------------------------------------+

| Token | Value |+---------+----------------------------------------+

| expires | 2012-07-28T13:58:56.000-05:00 || id | 1bd336d5-e0c6-49d9-b902-d3dbdc463062 || tenant | {u'id': u'010101', u'name': u'010101'} |+---------+----------------------------------------+

After you generate a token, the nova client automatically injects the token into anynova client commands that you issue.

However, because the token expires after 24 hours, you must generate a new tokenonce a day.

2. Get the service catalog with a list of endpoints:

$ nova endpoints

For each service, the response includes the public URL, which is the endpoint that youuse to access the service, the region, service name, tenant ID, the version ID, and end-points that you can use to get version information for the API.

To access the Cloud Networks or next generation Cloud Servers service, use the pub-licURL value for the cloudServersOpenStack service.

The following output shows the information returned for the DFW region for theCloud Networks or next generation Cloud Servers service:


May 28, 2015 API v2

23

+-----------------------

+------------------------------------------------------+

| cloudServersOpenStack | Value |+-----------------------

+------------------------------------------------------+

| publicURL | https://dfw.servers.api.rackspacecloud.com/v2/010101 || region | DFW || serviceName | cloudServersOpenStack || tenantId | 010101 || versionId | 2 || versionInfo | https://dfw.servers.api.rackspacecloud.com/v2 || versionList | https://dfw.servers.api.rackspacecloud.com/ |+-----------------------

+------------------------------------------------------+

The cloudServersOpenStack service might show multiple endpoints to enable re-gional choice.Select the appropriate endpoint for the region that you want to interactwith by examining the region field.

3. Copy the values in the publicURL and tenantId fields for the cloudServer-sOpenStack service for your region.

Next step: Export environment variables to run cURL commands


May 28, 2015 API v2

24

Authenticate with cURLTo authenticate, you issue a POST /tokens request to the Identity Service endpoint(https://identity.api.rackspacecloud.com/v2.0).

In the request body, supply one of the following sets of credentials:

user name and password

user name and API key

Your username and password are the ones that you use to log into the Rackspace CloudControl Panel.

NoteIf you authenticate with username and password credentials, you can use mul-ti-factor authentication to add an additional level of account security. This fea-ture is not implemented for username and API credentials. For more infor-mation, see Multifactor authentication in the Cloud Identity Client DeveloperGuide.

To obtain your API key, log into http://mycloud.rackspace.com, click your username, andselect API Keys to get your key.

To authenticate with cURL:

1. Get an authentication token and a service catalog with a list of endpoints.

Use one of the following cURL commands to authenticate to the Identity endpoint:

Example4.Authenticate with Username and Password: JSON Request$ curl -s https://identity.api.rackspacecloud.com/v2.0/tokens -X 'POST' \ -d '{"auth":{"passwordCredentials":{"username":"theUserName", "password":"thePassword"}}}' \ -H "Content-Type: application/json" | python -m json.tool

Example5.Authenticate with Username and API Key: JSON Request$ curl -s https://identity.api.rackspacecloud.com/v2.0/tokens -X 'POST' \ -d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"theUserName", "apiKey":"0000000000000000000"}}}' \ -H "Content-Type: application/json" | python -m json.tool

NoteFor information about the json.tool, see Note [6].

In response to valid credentials, your request returns an authentication token and aservice catalog with the endpoints to request services.

NoteIf you authenticated with username and password credentials, and theIdentity service returns a 401 message requesting additional credentials,your account is configured for multi-factor authentication. To completethe authentication process, submit a second POST tokens request with mul-ti-factor authentication credentials.


May 28, 2015 API v2

25

Do not include explicit API endpoints in your scripts and applications. Instead, find theendpoint for your service and region.

The following output shows a partial authentication response in JSON format:

Example6.Authenticate: JSON Response{ "access": { "serviceCatalog": [ { "endpoints": [ { "internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_530f8649-324c-499c-a075-2195854d52a7", "publicURL": "https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_530f8649-324c-499c-a075-2195854d52a7", "region": "DFW", "tenantId": "MossoCloudFS_530f8649-324c-499c-a075-2195854d52a7" }, { "internalURL": "https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_530f8649-324c-499c-a075-2195854d52a7", "publicURL": "https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_530f8649-324c-499c-a075-2195854d52a7", "region": "ORD", "tenantId": "MossoCloudFS_530f8649-324c-499c-a075-2195854d52a7" } ], "name": "cloudFiles", "type": "object-store" }, { "endpoints": [ { "publicURL": "https://servers.api.rackspacecloud.com/v1.0/010101", "tenantId": "010101", "versionId": "1.0", "versionInfo": "https://servers.api.rackspacecloud.com/v1.0", "versionList": "https://servers.api.rackspacecloud.com/" } ], "name": "cloudServers", "type": "compute" }, { "endpoints": [ { "publicURL": "https://dfw.servers.api.rackspacecloud.com/v2/010101", "region": "DFW",

"tenantId": "010101", "versionId": "2", "versionInfo": "https://dfw.servers.api.rackspacecloud.com/v2", "versionList": "https://dfw.servers.api.rackspacecloud.com/" }, { "publicURL": "https://ord.servers.api.rackspacecloud.com/v2/010101", "region": "ORD", "tenantId": "010101", "versionId": "2", "versionInfo": "https://ord.servers.api.rackspacecloud.com/v2", "versionList": "https://ord.servers.api.rackspacecloud.com/" } ], "name": "cloudServersOpenStack", "type": "compute" } ], "token": { "expires": "2012-09-14T15:11:57.585-05:00",

"id": "858fb4c2-bf15-4dac-917d-8ec750ae9baa" ,

"tenant": { "id": "010101", "name": "010101" } }, "user": { "RAX-AUTH:defaultRegion": "DFW", "id": "170454", "name": "MyRackspaceAcct", "roles": [ { "description": "User Admin Role.", "id": "3",


May 28, 2015 API v2

26

"name": "identity:user-admin" } ] } }}

Successful authentication returns the following information:

Endpoints to request Rackspace Cloud services. Appears in the endpoints ele-ment in the serviceCatalog element.

Endpoints information includes the public URL, which is the endpoint that you useto access the service, region, tenant ID, and version information.Tenant ID. Appears in the tenantId field in the endpoints element. Alsoknown as the account number.

You include the tenant ID in the endpoint URL when you call a Cloud service.

In the following example, you export the tenant ID, 010101, to the account en-vironment variable and the authentication token to the token environment vari-able. Then, you issue a cURL command, as follows:$ export account="010101"$ export token="00000000-0000-0000-000000000000"$ curl -s https://dfw.servers.api.rackspacecloud.com/v2/$account/images/detail \ -H "X-Auth-Token: $token" | python -m json.toolThe name of the service. Appears in the name field.

Locate the correct service name in the service catalog, as follows:

First generation Cloud Servers. Named cloudServers in the catalog.

If you use the authentication token to access this service, you can view and per-form first generation Cloud Servers API operations against your first generationCloud Servers.

Cloud Networks or next generation Cloud Servers. Named cloudServer-sOpenStack in the catalog.

To access the Cloud Networks or next generation Cloud Servers service, use thepublicURL value for the cloudServersOpenStack service.

Might show multiple endpoints to enable regional choice.Select the appropri-ate endpoint for the region that you want to interact with by examining theregion field.

Tip

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

If you use the authentication token to access this service, you can view and per-form Cloud Networks or next generation Cloud Servers API operations againstyour next generation Cloud Servers. To complete Cloud Networks API opera-tions, you must also get access to this service. To request access, click here.


May 28, 2015 API v2

27

Expiration date and time for authentication token. Appears in the expiresfield in the token element.

After this date and time, the token is no longer valid.

This field predicts the maximum lifespan for a token, but does not guarantee thatthe token reaches that lifespan.

Clients are encouraged to cache a token until it expires.

Because the authentication token expires after 24 hours, you must generate a to-ken once a day.Authentication token. Appears in the id field in the token element.

You pass the authentication token in the X-Auth-Token header each time thatyou send a request to a service.

In the following example, you export the tenant ID, 010101, to the ac-count environment variable. You also export the authentication token,00000000-0000-0000-000000000000, to the token environment variable.Then, you issue a cURL command, as follows:$ export account="010101"$ export token="00000000-0000-0000-000000000000"$ curl -s https://dfw.servers.api.rackspacecloud.com/v2/$account/images/detail \ -H "X-Auth-Token: $token" | python -m json.tool

2. Copy the values in the publicURL and tenantId fields for the cloudServer-sOpenStack service for your region.

Copy the authentication token from the id field in the token element.

In the next step, you set environment variables to these values.

Next step: Export environment variables to run cURL commands


May 28, 2015 API v2

28

Step 4. (Optional) Export Environment Variablesto Run cURL Commands

To run the cURL command examples in this guide, follow this procedure to export environ-ment variables.

Otherwise, proceed to the section called Step 5. List Images [29].

Export your tenant ID and authentication token to environment variables. All cURL exam-ples in this guide use these environment variables.

To export environment variables:

1. Export your tenant ID to the account environment variable:

$ export account=""

Where tenantId is the value in the tenantId field in the authentication response.

2. Export your authentication token to the token environment variable:

$ export token=""

Where id is the authentication token value in the id field in the token element in theauthentication response.

Next step: List images


May 28, 2015 API v2

29

Step 5. List ImagesBefore you create a server, list images so that you can choose one for your new server.

After you choose an image, copy its image ID. You use this image ID when you create theserver.


List images with the nova client

List images with cURL


May 28, 2015 API v2

30

List Images with the nova ClientTo list images with the nova client:

1. Issue the following command:

$ nova image-list

For each image, the command returns the image ID, name, and status, as shown in thefollowing output:

+--------------------------------------

+-----------------------------------------------------------------------------

+--------+--------+

| ID | Name | Status | Server |+--------------------------------------

+-----------------------------------------------------------------------------

+--------+--------+

| 0d589460-f177-4b0f-81c1-8ab8903ac7d8 | Arch 2011.10 | ACTIVE | || 03318d19-b6e6-4092-9b5c-4758ee0ada60 | CentOS 5.6 | ACTIVE | || a3a2c42f-575f-4381-9c6d-fcd3b7d07d17 | CentOS 6.0 | ACTIVE | || 0cab6212-f231-4abd-9c70-608d0d0e04ba | CentOS 6.2 | ACTIVE | || c195ef3b-9195-4474-b6f7-16e5bd86acd0 | CentOS 6.3 | ACTIVE | || a10eacf7-ac15-4225-b533-5744f1fe47c1 | Debian 6 (Squeeze) | ACTIVE | || bca91446-e60e-42e7-9e39-0582e7e20fb9 | Fedora 16 (Verne) | ACTIVE | || d42f821e-c2d1-4796-9f07-af5ed7912d0e | Fedora 17 (Beefy Miracle) | ACTIVE | || c79fecf7-2c37-4c51-a240-e9fa913c90a3 | FreeBSD 9 | ACTIVE | || 040e6c82-6618-4f53-9f27-44db2c4ce9ee | Gentoo 11.0 | ACTIVE | || 644be485-411d-4bac-aba5-5f60641d92b5 | Red Hat Enterprise Linux 5.5 | ACTIVE | || d6dd6c70-a122-4391-91a8-decb1a356549 | Red Hat Enterprise Linux 6.1 | ACTIVE | || d531a2dd-7ae9-4407-bb5a-e5ea03303d98 | Ubuntu 10.04 LTS (Lucid Lynx) | ACTIVE | || 8bf22129-8483-462b-a020-1754ec822770 | Ubuntu 11.04 (Natty Narwhal) | ACTIVE | || 3afe97b2-26dc-49c5-a2cc-a2fc8d80c001 | Ubuntu 11.10 (Oneiric Oncelot) | ACTIVE | || 5cebb13a-f783-4f8c-8058-c4182c724ccd | Ubuntu 12.04 LTS (Precise Pangolin) | ACTIVE | || b9ea8426-8f43-4224-a182-7cdb2bb897c8 | Windows Server 2008 R2 SP1 | ACTIVE | || 7957e53d-b3b9-41fe-8e0d-5252bf20a5bf | Windows Server 2008 R2 SP1 (with updates) | ACTIVE | || 535d5453-79dd-4635-bbd6-d87b1f1cd717 | Windows Server 2008 R2 SP1 (with updates) + SQL Server 2008 R2 SP1 Standard | ACTIVE | || 80599479-b5a2-49f2-bb46-2bc75a8be98b | Windows Server 2008 R2 SP1 (with updates) + SQL Server 2008 R2 SP1 Web | ACTIVE | |


May 28, 2015 API v2

31

| e4589dc6-b972-482f-91ef-67feb891b559 | Windows Server 2008 R2 SP1 (with updates) + SQL Server 2012 Standard | ACTIVE | || 6f8ab5a1-42ff-433b-be40-e17374f2fff4 | Windows Server 2008 R2 SP1 (with updates) + SQL Server 2012 Web | ACTIVE | || 2a4a02aa-523a-4649-9802-3a09de8e5f1b | Windows Server 2008 R2 SP1 + SQL Server 2008 R2 Standard | ACTIVE | || d6153e86-f4e0-4053-a711-d35632e512cd | Windows Server 2008 R2 SP1 + SQL Server 2008 R2 Web | ACTIVE | || f7d06722-2b30-4c02-b74d-da5a7337f357 | Windows Server 2008 R2 SP1 + SQL Server 2012 Standard | ACTIVE | || e7a11eed-d348-44da-8210-f136d4256e81 | Windows Server 2008 R2 SP1 + SQL Server 2012 Web | ACTIVE | || 096c55e5-39f3-48cf-a413-68d9377a3ab6 | openSUSE 12.1 | ACTIVE | |+--------------------------------------

+-----------------------------------------------------------------------------

+--------+--------+

2. Copy the image ID for you desired image from the ID field in the output.

In this example, use the ID value for the Ubuntu 11.10 image, which is3afe97b2-26dc-49c50a2cc-a2fc8d80c001.

Next step: List flavors


May 28, 2015 API v2

32

List Images with cURLTo list images with cURL:

1. Issue the following cURL command:$ curl -s https://dfw.servers.api.rackspacecloud.com/v2/$account/images/detail \ -H "X-Auth-Token: $token" | python -m json.tool

Options

-s. Runs the command in silent mode.

-H. Specifies the authentication token in the X-Auth-Token header. You export-ed the authentication token to the token environment variable in the section calledStep 4. (Optional) Export Environment Variables to Run cURL Commands [28].

-m json.tool. Specifies the json.tool, which pretty-prints the JSON output. For in-formation about the json.tool, see Note [6].

Because this is a GET request, which is the default method, you do not have to specifythe -X option in the command.

For each image, the command returns the ID, links, metadata, and name. The follow-ing output shows the information returned for the Ubuntu 11.10 image. For brevity,other images in the array are not shown.{ "images": [ { "OS-DCF:diskConfig": "AUTO", "created": "2012-02-28T19:38:57Z", "id": "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", "links": [ { "href": "https://dfw.servers.api.rackspacecloud.com/v2/010101/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", "rel": "self" }, { "href": "https://dfw.servers.api.rackspacecloud.com/010101/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", "rel": "bookmark" }, { "href": "https://dfw.servers.api.rackspacecloud.com/010101/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", "rel": "alternate", "type": "application/vnd.openstack.image" } ], "metadata": { "arch": "x86-64", "auto_disk_config": "True", "com.rackspace__1__build_core": "1", "com.rackspace__1__build_managed": "1", "com.rackspace__1__build_rackconnect": "1", "com.rackspace__1__options": "0", "com.rackspace__1__visible_core": "1", "com.rackspace__1__visible_managed": "1", "com.rackspace__1__visible_rackconnect": "1", "image_type": "base", "org.openstack__1__architecture": "x64", "org.openstack__1__os_distro": "org.ubuntu", "org.openstack__1__os_version": "11.10", "os_distro": "ubuntu", "os_type": "linux", "os_version": "11.10", "rax_managed": "false", "rax_options": "0" },


May 28, 2015 API v2

33

"minDisk": 10, "minRam": 256, "name": "Ubuntu 11.10 (Oneiric Oncelot)", "progress": 100, "status": "ACTIVE", "updated": "2012-02-28T19:39:05Z" } ]}

2. Copy the image ID for the Ubuntu 11.10 image from the id field in the output.

In this example, the id value for the Ubuntu 11.10 image is3afe97b2-26dc-49c50a2cc-a2fc8d80c001.

Next step: List flavors


May 28, 2015 API v2

34

Step 6. List FlavorsBefore you create a server, list flavors so that you can choose one for your new server.

After you choose a flavor, copy its flavor ID to use when you create the server.

For more information about flavors and which flavors might be best for you, see the sec-tion called Flavors [8].


List flavors with the nova client

List flavors with cURL


May 28, 2015 API v2

35

List Flavors with the nova Client

To list flavors with the nova client:


$ nova flavor-list

Optional parameter: --extra-specs

The command returns details that describe each flavor.

ID Flavor ID

Name Flavor name

Memory_MB Amount of memory

Disk Size of disk in GB (for IO and General Purpose flavors, it is the size ofthe system disk)

Ephemeral Size of data disks in GB for IO flavors

Swap Size of swap space

VCPUs Number of virtual CPUs

RXTX_Factor Aggregate outbound bandwidth, in megabits per second, across allattached network interfaces (PublicNet, ServiceNet, and Cloud Net-works). Outbound public Internet bandwidth can be up to 40% ofthe aggregate limit. Host networking is redundant, and bandwidthis delivered over two separate bonded interfaces, each able to carry50% of the aggregate limit. We recommend using multiple Layer 4connections to maximize throughput. Inbound traffic is not limited.

Is_Public Not used

extra_specs Extra specifications

Class flavor class: standard1, compute1, io1, memory1, or on-metal1

Disk_io_index Relative measure of disk I/O performance from0-99, where higher is faster

Number_of_data_disks Number of data disks

Note

In order to see the extra-specs column, pass --extra-specs argument incommand.

Flavor List+------------------+-------------------------+-----------+------+-----------+------+-------+-------------+-----------+

| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |


May 28, 2015 API v2

36

+------------------+-------------------------+-----------+------+-----------+------+-------+-------------+-----------+

| 2 | 512MB Standard Instance | 512 | 20 | 0 | 512 | 1 | 80.0 | N/A || 3 | 1GB Standard Instance | 1024 | 40 | 0 | 1024 | 1 | 120.0 | N/A || 4 | 2GB Standard Instance | 2048 | 80 | 0 | 2048 | 2 | 240.0 | N/A || 5 | 4GB Standard Instance | 4096 | 160 | 0 | 2048 | 2 | 400.0 | N/A || 6 | 8GB Standard Instance | 8192 | 320 | 0 | 2048 | 4 | 600.0 | N/A || 7 | 15GB Standard Instance | 15360 | 620 | 0 | 2048 | 6 | 800.0 | N/A || 8 | 30GB Standard Instance | 30720 | 1200 | 0 | 2048 | 8 | 1200.0 | N/A || compute1-15 | 15 GB Compute v1 | 15360 | 0 | 0 | | 8 | 1250.0 | N/A || compute1-30 | 30 GB Compute v1 | 30720 | 0 | 0 | | 16 | 2500.0 | N/A || compute1-4 | 4 GB Compute v1 | 3840 | 0 | 0 | | 2 | 312.5 | N/A || compute1-60 | 60 GB Compute v1 | 61440 | 0 | 0 | | 32 | 5000.0 | N/A || compute1-8 | 8 GB Compute v1 | 7680 | 0 | 0 | | 4 | 625.0 | N/A || general1-1 | 1 GB General Purpose v1 | 1024 | 20 | 0 | | 1 | 200.0 | N/A || general1-2 | 2 GB General Purpose v1 | 2048 | 40 | 0 | | 2 | 400.0 | N/A || general1-4 | 4 GB General Purpose v1 | 4096 | 80 | 0 | | 4 | 800.0 | N/A || general1-8 | 8 GB General Purpose v1 | 8192 | 160 | 0 | | 8 | 1600.0 | N/A || io1-120 | 120 GB I/O v1 | 122880 | 40 | 1200 | | 32 | 10000.0 | N/A || io1-15 | 15 GB I/O v1 | 15360 | 40 | 150 | | 4 | 1250.0 | N/A || io1-30 | 30 GB I/O v1 | 30720 | 40 | 300 | | 8 | 2500.0 | N/A || io1-60 | 60 GB I/O v1 | 61440 | 40 | 600 | | 16 | 5000.0 | N/A || io1-90 | 90 GB I/O v1 | 92160 | 40 | 900 | | 24 | 7500.0 | N/A || memory1-120 | 120 GB Memory v1 | 122880 | 0 | 0 | | 16 | 5000.0 | N/A || memory1-15 | 15 GB Memory v1 | 15360 | 0 | 0 | | 2 | 625.0 | N/A || memory1-240 | 240 GB Memory v1 | 245760 | 0 | 0 | | 32 | 10000.0 | N/A || memory1-30 | 30 GB Memory v1 | 30720 | 0 | 0 | | 4 | 1250.0 | N/A || memory1-60 | 60 GB Memory v1 | 61440 | 0 | 0 | | 8 | 2500.0 | N/A || performance1-1 | 1 GB Performance | 1024 | 20 | 0 | | 1 | 200.0 | N/A || performance1-2 | 2 GB Performance | 2048 | 40 | 20 | | 2 | 400.0 | N/A || performance1-4 | 4 GB Performance | 4096 | 40 | 40 | | 4 | 800.0 | N/A || performance1-8 | 8 GB Performance | 8192 | 40 | 80 | | 8 | 1600.0 | N/A || performance2-120 | 120 GB Performance | 122880 | 40 | 1200 | | 32 | 10000.0 | N/A || performance2-15 | 15 GB Performance | 15360 | 40 | 150 | | 4 | 1250.0 | N/A || performance2-30 | 30 GB Performance | 30720 | 40 | 300 | | 8 | 2500.0 | N/A || performance2-60 | 60 GB Performance | 61440 | 40 | 600 | | 16 | 5000.0 | N/A || performance2-90 | 90 GB Performance | 92160 | 40 | 900 | | 24 | 7500.0 | N/A |+------------------+-------------------------+-----------+------+-----------+------+-------+-------------+-----------+

2. Copy the ID of the flavor you want to use from the ID field in the output.

In this example, use the flavor ID for the 8GB Standard Instance, which is 6.

Next step: Create and boot your server


May 28, 2015 API v2

37

List Flavors with cURLTo list flavors with cURL:

1. Issue the following cURL command:$ curl -s https://dfw.servers.api.rackspacecloud.com/v2/$account/flavors \ -H "X-Auth-Token: $token" | python -m json.tool

Options


-H. Specifies the authentication token in the X-Auth-Token header. You export-ed the authentication token to the token environment variable in the section calledStep 4. (Optional) Export Environment Variables to Run cURL Commands [28].

-X. Omit this option. Because this is a GET request, which is the default method, youdo not have to specify this option in the command.

For each flavor, the command returns the flavor ID, links, and name.

The following output shows just the information returned for an 15 GB Compute1server. For brevity, other flavors in the array were removed. Your listening will returnall available flavors.{ "flavors": [ { "id": "6", "links": [ { "href": "https://dfw.servers.api.rackspacecloud.com/v2/820712/flavors/6", "rel": "self" }, { "href": "https://dfw.servers.api.rackspacecloud.com/820712/flavors/6", "rel": "bookmark" } ], "name": "8GB Standard Instance" } ] }

2. Copy the ID of the flavor you want to use from the id field in the output. The valuefrom this field will be used for the flavorRef field when you create a server.

In this example, use the flavor ID for the 8GB Standard Instance, which is 6.

Next step:Create and boot your server


May 28, 2015 API v2

38

Step 7. Create and Boot Your ServerTo create your new server, you need the following information:

The name of the new server. Use a name of your choice.

The image ID.

The flavor ID.

You specify these values as parameters in a nova command or as attributes in the requestbody in a cURL command.


Create a server with the nova client

Create a server with cURL


May 28, 2015 API v2

39

Create Your Server with the nova ClientTo create and boot your server with the nova client:

1. Issue the following command. In the command, specify the server name, flavor ID, andimage ID. You may optionally include the keypair name:$ nova boot myUbuntuServer --image "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001" --flavor 6 --key-name myKey

For more information about keypairs, see Cloud Servers API Developer Guide.

The command returns a list of server properties. The status field indicates whether theserver is being built or is active. A status of BUILD indicates that your server is beingbuilt.

+-------------------------+--------------------------------------+

| Property | Value |+-------------------------+--------------------------------------+

| OS-DCF:diskConfig | AUTO || OS-EXT-STS:power_state | 0 || OS-EXT-STS:task_state | scheduling || OS-EXT-STS:vm_state | building || accessIPv4 | || accessIPv6 | || adminPass | j3Peu626UnDJ || created | 2012-08-16T16:28:13Z || flavor | 8GB Standard Instance || hostId | || id | 9da98125-0de8-4b84-880c-b42977c32773 || image | Ubuntu 11.10 (Oneiric Oncelot) || metadata | {} || name | myUbuntuServer || progress | 0 || status | BUILD || tenant_id | 010101 || updated | 2012-08-16T16:28:14Z || user_id | 170454 |+-------------------------+--------------------------------------+

2. Copy the server ID value from the id field in the output. You use this ID to get detailsfor your server to determine if it built successfully.

Copy the administrative password value from the adminPass field. You use this valueto log into your server.

Next step: Get server details


May 28, 2015 API v2

40

Create Your Server with cURLTo create and boot a server, you must specify a request body in the API request. The re-quest body includes the name of the server, its flavor and image, and other informationthat is required to create the server.

To specify a request body in a cURL command, use one of the following options:

-d. Sends the specified data in a POST request to the HTTP server.

-T. Transfers the specified local file to the remote URL. The following example uses thismethod.

To create and boot your server with cURL:

1. Create a JSON file named server_build.json that contains the following requestbody:{ "server" : { "name" : "myUbuntuServer", "imageRef" : "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", "flavorRef" : "6", "metadata" : { "My Server Name" : "Ubuntu 11.10 server" } }}

Attributes

name. The server name. Use any name you like.

imageRef. The image ID. This is the image ID that you copied in the section calledList Images with cURL [32].

flavorRef. The flavor ID. This is the flavor ID that you copied in the section calledList Flavors with cURL [37].

metadata. In this example, you specify a server name.

Save the file in the directory from where you will run the cURL command.

2. Issue the following cURL command:$ curl -s https://dfw.servers.api.rackspacecloud.com/v2/$account/servers \ -X POST \ -H "Content-Type: application/json" \ -H "X-Auth-Token: $token" \ -H "X-Auth-Project-Id: test-project" \ -T server_build.json | python -m json.tool

Options


-X. Specifies the POST method because this request does not use the default GETmethod.

-H. Specifies the application content type in the Content-Type header, the au-thentication token in the X-Auth-Token header, and the project name in the X-


May 28, 2015 API v2

41

Auth-Project-Id header. You exported the authentication token to the tokenenvironment variable in the section called Step 4. (Optional) Export EnvironmentVariables to Run cURL Commands [28].

-T. Transfers the server_build.json file, which contains the request body, tothe remote URL.

The command returns a list of server properties, including the administrative password,the server ID, and links, as shown in the following output:{ "server": { "OS-DCF:diskConfig": "AUTO", "adminPass": "T8GTdH29GmzG", "id": "1a861bf7-2a5e-40a4-acb3-1fb058cf2a74", "links": [ { "href": "https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/1a861bf7-2a5e-40a4-acb3-1fb058cf2a74", "rel": "self" }, { "href": "https://dfw.servers.api.rackspacecloud.com/010101/servers/1a861bf7-2a5e-40a4-acb3-1fb058cf2a74", "rel": "bookmark" } ] }}

3. Copy the server ID value from the id field in the output. You use this ID to get de-tails for your server to determine if it built successfully in the section called Step 8. GetServer Details [42].

Copy the administrative password value from the adminPass field. You use this valueto log into your server.

Next step: Get server details


May 28, 2015 API v2

42

Step 8. Get Server DetailsGet details for your server to determine whether it built successfully.

The response for the get server details call shows the following information for your server:

Name Description

OS-DCF:diskConfig The disk configuration value, which is AUTO or MANUAL.

OS-EXT-STS:power_state Extended attribute. The power state.

OS-EXT-STS:task_state The task state.

OS-EXT-STS:vm_state The VM state.

created The time stamp for when the server was created.

flavor The flavor ID and links.

hostId The host ID.

id The server ID.

image The image name.

metadata Any metadata key and value pairs.

name The server name.

private network Your private IP address.

public network The public IP address. Use this address to log into the server.

status The server status. A status of ACTIVE indicates that your server built successfullyand is active.

progress The percentage value of the build status. For example, if the status is BUILD andthe progress is 60, the server is 60% built.


Get server details with the nova client

Get server details with cURL


May 28, 2015 API v2

43

Get Server Details with the nova Client

To get details for your server with the nova client:


$ nova show

Where id is the server ID that you copied in the section called Step 7. Create andBoot Your Server [38].

The command shows information for your server, including its private and public IP ad-dresses, and status:

+-------------------------

+-----------------------------------------------------------------------------------------------------------------

+

| Property | Value |+-------------------------

+------------------------------------------------------------------------------------------------------------------

+

| OS-DCF:diskConfig | AUTO || OS-EXT-STS:power_state | 1 || OS-EXT-STS:task_state | None || OS-EXT-STS:vm_state | active || accessIPv4 | 198.101.231.59 || accessIPv6 | 2001:4800:780d:0509:d87b:9cbc:ff04:488b || created | 2012-08-16T16:28:18Z || flavor | 8GB Standard Instance (6) || hostId | d934ece70c2df646ee9fa45958d254819c46dfe244c51f880224b8f2 || id | 9da98125-0de8-4b84-880c-b42977c32773 || image | Ubuntu 11.10 (Oneiric Oncelot) (3afe97b2-26dc-49c5-a2cc-a2fc8d80c001) || metadata | {} || name | myUbuntuServer || private network | 10.179.224.74 || progress | 100 || public network | 2001:4800:780d:0509:d87b:9cbc:ff04:488b, 198.101.231.59 || status | ACTIVE |


May 28, 2015 API v2

44

| tenant_id | 010101 || updated | 2012-08-16T16:32:48Z || user_id | 170454 |+-------------------------

+------------------------------------------------------------------------------------------------------------------

+

2. Run the command until the status of your server is ACTIVE. Typically, servers take afew minutes to build.

3. Copy the public IP address that is returned for your server from the public networkfield in the output before the comma (,).

You use this address when you log into your server.

Next step: List servers with attached networks


May 28, 2015 API v2

45

Get Server Details with cURLTo get details for your server with cURL:

1. Issue the following command:$ curl -s https://dfw.servers.api.rackspacecloud.com/v2/$account/servers/ \ -H "X-Auth-Token: $token" | python -m json.tool

Where id is the server ID that you copied in the section called Step 7. Create andBoot Your Server [38].

As with the list flavors and list images requests, you do not have to specify the GETmethod in the request because GET is the default method.

The command shows information for your server, including its private and public IP ad-dresses, and status, as shown in the following output:{ "server": { "OS-DCF:diskConfig": "AUTO", "OS-EXT-STS:power_state": 0, "OS-EXT-STS:task_state": "spawning", "OS-EXT-STS:vm_state": "building", "accessIPv4": "", "accessIPv6": "", "addresses": { "private": [ { "addr": "10.180.16.21", "version": 4 } ], "public": [ { "addr": "2001:4800:780e:0510:d87b:9cbc:ff04:4bac", "version": 6 }, { "addr": "198.101.242.47", "version": 4 } ] }, "created": "2012-08-16T17:11:43Z", "flavor": { "id": "6", "links": [ { "href": "https://dfw.servers.api.rackspacecloud.com/010101/flavors/6", "rel": "bookmark" } ] }, "hostId": "692f611d2d84e5368b5995d7733ca5f175dc670eda91eded50a47eab", "id": "1a861bf7-2a5e-40a4-acb3-1fb058cf2a74", "image": { "id": "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", "links": [ { "href": "https://dfw.servers.api.rackspacecloud.com/010101/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001", "rel": "bookmark" } ] }, "links": [ { "href": "https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/1a861bf7-2a5e-40a4-acb3-1fb058cf2a74", "rel": "self" }, { "href": "https://dfw.servers.api.rackspacecloud.com/010101/servers/1a861bf7-2a5e-40a4-acb3-1fb058cf2a74", "rel": "bookmark" }


May 28, 2015 API v2

46

], "metadata": { "My Server Name": "Ubuntu 11.10 server" }, "name": "myUbuntuServer", "progress": 50, "status": "BUILD", "tenant_id": "010101", "updated": "2012-08-16T17:12:46Z", "user_id": "170454" }}

2. Run the command until the status of your server is ACTIVE. Typically, servers take afew minutes to build.

3. Copy the public IP version 4 address from the output. Use this address when you log in-to your server.

Next step: List servers with attached networks


May 28, 2015 API v2

47

Step 9. List Servers and Attached NetworksTo show all the servers in your Cloud account, you can list servers. When you list servers, theaddresses for any attached networks are displayed. The networks include any isolated net-works that you have created and Rackspace public and private networks.


List servers with the nova client

List servers with cURL


May 28, 2015 API v2

48

List Servers with the nova ClientTo list servers with the nova client:


$ nova list

For each server, the command returns the server ID, name, status, and addresses forany attached networks, as shown in the following output:+--------------------------------------+----------------+--------+---------------------------------------------------------------------------------------+

| ID | Name | Status | Networks |+--------------------------------------+----------------+--------+---------------------------------------------------------------------------------------+

| 9da98125-0de8-4b84-880c-b42977c32773 | myUbuntuServer | ACTIVE | public=2001:4800:780d:0509:d87b:9cbc:ff04:488b, 198.101.231.59; private=10.179.224.74 || a09e7493-7429-41e1-8d3f-384d7ece09c0 | UbuntuDevStack | ACTIVE | public=2001:4800:780e:0510:d87b:9cbc:ff04:3e81, 50.56.186.185; private=10.180.13.75 |+--------------------------------------+----------------+--------+---------------------------------------------------------------------------------------+

The networks include any isolated networks that you have created and Rackspace pub-lic and private networks.

2. Look for your server in the list of servers. Servers are listed by server ID.

Copy the server ID for your server. To update or delete your server, you need this ID.

You use the public IP address when you log into your server.

Next step: Set up Ubuntu


May 28, 2015 API v2

49

List Servers with cURLTo list servers with cURL:

1. Issue the following command:$ curl -s https://dfw.servers.api.rackspacecloud.com/v2/$account/servers/detail \ -H "X-Auth-Token: $token" | python -m json.tool

For each server, the command returns the disk configuration, the addresses of any at-tached networks, flavor and image information, the server ID, and the server status.The networks include any isolated networks that you have created and Rackspace pub-lic and private networks.

The following output shows the list servers information, including information for theUbuntu server that you just created:{ "servers": [ { "OS-DCF:diskConfig": "AUTO", "OS-EXT-STS:power_state": 0, "OS-EXT-STS:task_state": "spawning", "OS-EXT-STS:vm_state": "building", "accessIPv4": "", "accessIPv6": "", "addresses": { "private": [ { "addr": "10.180.16.21", "version": 4 } ], "public": [ { "addr": "2001:4800:780e:0510:d87b:9cbc:ff04:4bac", "version": 6

cs gettingstarted 20150528

Documents

rackspace cloud account

rackspace logo

rackspace services offerings

rackspace general terms

cloud servers works

cloud networks extension

openstack compute api

service level