OpenStack API Quick Start

This page covers the basics for talking to your OpenStack cloud through the Compute API after authorizing with the Identity Service API. You can then build a cloud by launching images and assigning metadata to instances, all through the API. For an API reference of all the possible commands, see the OpenStack Compute API v2 specification and the Identity Service 2.0 specification published at docs.openstack.org/api.

Credentials are a combination of your user name, password, and what tenant (or project) your cloud is running under. You only need to generate an additional token if you are interacting with your cloud directly with API endpoints, and not with a client. Your cloud administrator can give you a user name and a password as well as your tenant identifier so you can generate authorization tokens. You can also get the tenant ID from the Dashboard URLs, for example https://trystack.org/dash/296/images/ indicates a tenant ID of 296.

These tokens are typically good for 24 hours, and when the token expires, you will find out with a 401 (Unauthorized) error and can request another token programmatically. The general work flow goes something like this:

For a typical OpenStack deployment running the Identity Service you can request a token with this command in cURL if you know your tenantId:

$ curl -X 'POST' -v 
https://arm.trystack.org:5443/v2.0/tokens -d 
'{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'
         

In return, you should get a 200 OK response with a token in the form of "id": "cd427a33-bb4a-4079-a6d7-0ae148bdeda9" and an expiration date 24 hours from now. Here's what it looks like, the exact response may vary from cloud-to-cloud:

{
    "access": {
        "serviceCatalog": [
            {
                "endpoints": [
                    {
                        "adminURL": "https://arm.trystack.org:9774/v1.1/1", 
                        "internalURL": "https://arm.trystack.org:9774/v1.1/1", 
                        "publicURL": "https://arm.trystack.org:9774/v1.1/1", 
                        "region": "RegionOne"
                    }
                ], 
                "name": "nova", 
                "type": "compute"
            }, 
            {
                "endpoints": [
                    {
                        "adminURL": "https://GLANCE_API_IS_NOT_DISCLOSED/v1.1/1", 
                        "internalURL": "https://GLANCE_API_IS_NOT_DISCLOSED/v1.1/1", 
                        "publicURL": "https://GLANCE_API_IS_NOT_DISCLOSED/v1.1/1", 
                        "region": "RegionOne"
                    }
                ], 
                "name": "glance", 
                "type": "image"
            }, 
            {
                "endpoints": [
                    {
                        "adminURL": "https://arm.trystack.org:5443/v2.0", 
                        "internalURL": "https://keystone.trystack.org:5000/v2.0", 
                        "publicURL": "https://keystone.trystack.org:5000/v2.0", 
                        "region": "RegionOne"
                    }
                ], 
                "name": "keystone", 
                "type": "identity"
            }
        ], 
        "token": {
            "expires": "2012-02-15T19:32:21", 
            "id": "5df9d45d-d198-4222-9b4c-7a280aa35666", 
            "tenant": {
                "id": "1", 
                "name": "admin"
            }
        }, 
        "user": {
            "id": "14", 
            "name": "joecool", 
            "roles": [
                {
                    "id": "2", 
                    "name": "Member", 
                    "tenantId": "1"
                }
            ]
        }
    }
    }    

If you don't know your tenantId, you can send a request with an empty tenantId, such as this JSON example:

'{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":""}}'
        

Then, with the auth token that returns, fill in a request using the X-Auth-Token header as an authentication to get your tenantId:

curl -H "X-Auth-Token:6de6d45d-d198-4222-9b4c-7a280aa24888" http://arm.trystack.org:5000/v2.0/tenants

In return, you get a list of tenants:

{
    "tenants_links": [],
    "tenants": [
        {
            "enabled": "true",
            "description": "joecool",
            "name": "joecool",
            "id": "tenantnnnnnn"
        }
    ]
    }

Use the resulting token to make a new POST request containing the tenantId so you can retrieve endpoints:

curl -k -X 'POST' -v http://arm.trystack.org:5000/v2.0/tokens -d 
            '{"auth":{"passwordCredentials":{"username": "usern4me", "password":"passwerd"}, "tenantId":"tenantnnnnnn"}}' -H 'Content-type: application/json'

The resulting JSON contains a list of endpoints, for example:

{
    "endpoints": [
        {
            "adminURL": "http://10.225.0.8:8774/v2/tenantnnnnnn",
            "region": "Calxeda-AUS1",
            "internalURL": "http://10.225.0.8:8774/v2/tenantnnnnnn",
            "publicURL": "http://208.123.85.197:8774/v2/tenantnnnnnn"
        }
    ],
    "endpoints_links": [],
    "type": "compute",
    "name": "nova"
}

In addition, you can see a valid token matched to your user and tenantId:

{
    "access": {
        "token": {
            "expires": "2012-10-31T17: 13: 12Z",
            "id": "new_token***",
            "tenant": {
                "enabled": true,
                "id": "tenantnnnnnn",
                "name": "joecool",
                "description": "joecool"
            }
        }
}

You have a couple of options for sending requests to OpenStack through an API. Developers and testers may prefer to use cURL, the command-line tool from http://curl.haxx.se/. With cURL you can send HTTP requests and receive responses back from the command line.

If you like to use a more graphical interface, the REST client for Firefox also works well for testing and trying out commands, see https://addons.mozilla.org/en-US/firefox/addon/restclient/. You can also download and install rest-client, a Java application to test RESTful web services, from http://code.google.com/p/rest-client/.

You need to generate a token as shown above if you use cURL or a REST client.

It's also recommended that you install and use a Command-Line-Client (CLI) such as python-novaclient, which is documented in CLI guide.

Here's an example of curl commands that can check your list of servers.

curl -v -H "X-Auth-Token:tokengoeshere" http://208.123.85.197:8774/v2/tenantnnnnnn/servers

Here's what you get in return if you have a running server.

{
    "servers": [
        {
            "id": "server***",
            "links": [
                {
                    "href": "http://208.123.85.197:8774/v2/tenantnnnnnn/servers/server***",
                    "rel": "self"
                },
                {
                    "href": "http://208.123.85.197:8774/tenantnnnnnn/servers/server***",
                    "rel": "bookmark"
                }
            ],
            "name": "Staging Server"
        }
    ]
}

Before you can go about the business of building your cloud, you want to know what images are available to you by asking the image service what kinds of configurations are available. The image service could be compared to iTunes for your cloud - you can view the playlist of images before using your favorite image to create a new instance in the cloud. To get the list of images, their names, status, and ID, use this command:

$ nova image-list

+----+--------------------------------------+--------+--------+
| ID |                 Name                 | Status | Server |
+----+--------------------------------------+--------+--------+
| 12 | natty-server-cloudimg-amd64-kernel   | ACTIVE |        |
| 13 | natty-server-cloudimg-amd64          | ACTIVE |        |
| 14 | oneiric-server-cloudimg-amd64-kernel | ACTIVE |        |
| 15 | oneiric-server-cloudimg-amd64        | ACTIVE |        |
+----+--------------------------------------+--------+--------+
        

Next you need to know the relative sizes of each of these.

With the information about what is available to you, you can choose the combination of image and flavor to create your virtual servers and launch instances.

You also need to know the ID of the flavor To get the list of flavors, their names, status, and ID, use this command:

$ nova flavor-list
        
+----+-----------+-----------+------+-----------+------+-------+-------------+
| ID |    Name   | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor |
+----+-----------+-----------+------+-----------+------+-------+-------------+
| 1  | m1.tiny   | 512       | 0    | N/A       | 0    | 1     |             |
| 2  | m1.small  | 2048      | 20   | N/A       | 0    | 1     |             |
| 3  | m1.medium | 4096      | 40   | N/A       | 0    | 2     |             |
| 4  | m1.large  | 8192      | 80   | N/A       | 0    | 4     |             |
| 5  | m1.xlarge | 16384     | 160  | N/A       | 0    | 8     |             |
+----+-----------+-----------+------+-----------+------+-------+-------------+        
    

With the information about what is available to you, you can choose the combination of image and flavor to create your virtual servers and launch instances.

To launch a server, you choose an image you want to match up to a size, find the ID for the image and the ID for the flavor so you can size it, and create the command with the IDs. From the information we got previously, we know that an Ubuntu Natty image has an ID of 13, and if you want to start small with about 2 GB of memory and 20 GB of disk space, you'd choose the m1.small flavor which has an ID of 2 when using the 1.1 API on TryStack. Put those parameters in with the "boot" command and you can create a new virtual server.

	Note
	When using an endpoint that supports 1.1 of the Compute API, you can launch instances with an ID. When using an endpoint that supports v2 of the Compute API, you must use the UUID to launch an instance.

 $ nova boot --flavor=2 --image=13 testserver
 
 +-----------+--------------------------------------+
|  Property |                Value                 |
+-----------+--------------------------------------+
| adminPass | ****************                     |
| created   | 2011-09-01T21:40:41Z                 |
| flavor    | m1.small                             |
| hostId    |                                      |
| id        | 1805                                 |
| image     | natty                                |
| metadata  | {}                                   |
| name      | testserver                           |
| progress  | 0                                    |
| status    | BUILD                                |
| updated   | 2011-09-01T21:40:41Z                 |
| uuid      | ce044452-f22e-4ea4-a3ec-d1cde80cf996 |
+-----------+--------------------------------------+
 

Now, you can view this server in your new cloud by using the nova list command:

$ nova list
+------+------------+--------+--------------------------------+
|  ID  |    Name    | Status |            Networks            |
+------+------------+--------+--------------------------------+
| 1805 | testserver | ACTIVE | private=10.4.96.81             |
+------+------------+--------+--------------------------------+
            

There are three statuses you may see - ACTIVE, BUILDING, and UNKNOWN. The BUILDING status is transient and you likely will not see it. If you see UNKNOWN, run nova list again until it goes away.

To view all the information about a particular server, use nova show with the ID of the server that you got from the nova list command.

$ nova show 1805

+-----------------+----------------------------------------------------------+
|     Property    |                          Value                           |
+-----------------+----------------------------------------------------------+
| created         | 2011-09-01T21:40:41Z                                     |
| flavor          | m1.small                                                 |
| hostId          | 58a7430169aa42cde5ce2456b0cb5bb5ac1ab0703bab6420e8a49e6e |
| id              | 1805                                                     |
| image           | natty                                                    |
| metadata        | {}                                                       |
| name            | testserver                                               |
| private network | 10.4.96.81                                               |
| progress        | 100                                                      |
| status          | ACTIVE                                                   |
| updated         | 2011-09-01T21:40:46Z                                     |
| uuid            | ce044452-f22e-4ea4-a3ec-d1cde80cf996                     |
+-----------------+----------------------------------------------------------+

        

You can now launch that image again, but add more information to the server when you boot it so that you can more easily identify it amongst your ever-growing elastic cloud. Use the -meta option with a key=value pair, where you can make up the string for both the key and the value. For example, you could add a description and also the creator of the server.

$ nova boot --flavor=2 --image=13 testserver --meta description='Use for testing purposes' --meta creator=joecool