OpenStack API Quick Start

Although you install each OpenStack service separately, the OpenStack services work together to meet your cloud needs: Identity, Compute, Image Service, Block Storage, Networking (neutron), Object Storage, Orchestration, and Telemetry. With the TryStack OpenStack installation, these services work together in the background of the installation.

After you authenticate through Identity, you can use the other OpenStack APIs to create and manage resources in your OpenStack cloud. You can launch instances from images and assign metadata to instances through the Compute API or the nova command-line client.

To begin sending API requests, use one of the following methods:

  • cURL

    A command-line tool that lets you send HTTP requests and receive responses. See the section called “OpenStack APIs”.

  • OpenStack command-line clients

    Each OpenStack project provides a command-line client that enables you to access its API through easy-to-use commands. See the section called “OpenStack command-line clients”.

  • REST clients

    Both Mozilla and Google provide browser-based graphical interfaces for REST. For Firefox, see RESTClient. For Chrome, see rest-client.

  • OpenStack Python Software Development Kit (SDK)

    Use this SDK to write Python automation scripts that create and manage resources in your OpenStack cloud. The SDK implements Python bindings to the OpenStack API, which enables you to perform automation tasks in Python by making calls on Python objects rather than making REST calls directly. All OpenStack command-line tools are implemented by using the Python SDK. See OpenStack Python SDK in the OpenStack End User Guide.

 OpenStack APIs

To authenticate access to OpenStack services, you must first issue an authentication request to OpenStack Identity to acquire an authentication token. To request an authentication token, you must supply a payload of credentials in the authentication request.

Credentials are usually a combination of your user name and password, and optionally, the name or ID of the tenant in which your cloud runs. Ask your cloud administrator for your user name, password, and tenant so that you can generate authentication tokens. Alternatively, you can supply a token rather than a user name and password.

When you send API requests, you include the token in the X-Auth-Token header. If you access multiple OpenStack services, you must get a token for each service. A token is valid for a limited time before it expires. A token can also become invalid for other reasons. For example, if the roles for a user change, existing tokens for that user are invalid.

Authentication and API request workflow

  1. Request an authentication token from the Identity endpoint that your cloud administrator gave you. Send a payload of credentials in the request:

    Parameter Type Description
    username (Optional) xsd:string The user name. If you do not provide a user name and password, you must provide a token.
    password (Optional) xsd:string The password for the user.
    tenantName (Optional) xsd:string The tenant name. Both the tenantId and tenantName are optional, but should not be specified together. If both attributes are specified, the server responds with a 400 Bad Request.
    tenantId (Optional) capi:UUID The tenant ID. Both the tenantId and tenantName are optional, but should not be specified together. If both attributes are specified, the server responds with a 400 Bad Request.
    token (Optional) capi:UUID A token. If you do not provide a token, you must provide a user name and password.

    If the request succeeds, the server returns an authentication token.

  2. Send API requests and include the token in the X-Auth-Token header. Continue to send API requests with that token until the job completes or a 401 Unauthorized error occurs.

  3. If the 401 Unauthorized error occurs, request another token.

The examples in this section use cURL commands. For information about cURL, see http://curl.haxx.se/. For information about the OpenStack APIs, see OpenStack API Reference.

 Authenticate

For a typical OpenStack deployment that runs Identity, use a cURL command like the following command to request a token:

$ curl -i 'http://127.0.0.1:5000/v2.0/tokens' -X POST -H "Content-Type: application/json" -H "Accept: application/json"  -d '{"auth": {"tenantName": "admin", "passwordCredentials": {"username": "admin", "password": "devstack"}}}'

If the request succeeds, you receive a 200 OK response followed by a response body that contains a token in the form "id":"token" and an expiration date and time in the form "expires":"datetime".

The following example shows a successful response:

HTTP/1.1 200 OK
Vary: X-Auth-Token
Content-Type: application/json
Content-Length: 5858
Date: Wed, 06 Nov 2013 20:06:24 GMT
{
   "access":{
      "token":{
         "issued_at":"2013-11-06T20:06:24.113908",
         "expires":"2013-11-07T20:06:24Z",
         "id":"{token}",
         "tenant":{
            "description":null,
            "enabled":true,
            "id":"604bbe45ac7143a79e14f3158df67091",
            "name":"admin"
         }
      },
      "serviceCatalog":[
         {
            "endpoints":[
               {
                  "adminURL":"http://166.78.21.23:8774/v2/604bbe45ac7143a79e14f3158df67091",
                  "region":"RegionOne",
                  "internalURL":"http://166.78.21.23:8774/v2/604bbe45ac7143a79e14f3158df67091",
                  "id":"9851cb538ce04283b770820acc24e898",
                  "publicURL":"http://166.78.21.23:8774/v2/604bbe45ac7143a79e14f3158df67091"
               }
            ],
            "endpoints_links":[

            ],
            "type":"compute",
            "name":"nova"
         },
         {
            "endpoints":[
               {
                  "adminURL":"http://166.78.21.23:3333",
                  "region":"RegionOne",
                  "internalURL":"http://166.78.21.23:3333",
                  "id":"0bee9a113d294dda86fc23ac22dce1e3",
                  "publicURL":"http://166.78.21.23:3333"
               }
            ],
            "endpoints_links":[

            ],
            "type":"s3",
            "name":"s3"
         },
         {
            "endpoints":[
               {
                  "adminURL":"http://166.78.21.23:9292",
                  "region":"RegionOne",
                  "internalURL":"http://166.78.21.23:9292",
                  "id":"4b6e9ece7e25479a8f7bb07eb58845af",
                  "publicURL":"http://166.78.21.23:9292"
               }
            ],
            "endpoints_links":[

            ],
            "type":"image",
            "name":"glance"
         },
         {
            "endpoints":[
               {
                  "adminURL":"http://166.78.21.23:8776/v1/604bbe45ac7143a79e14f3158df67091",
                  "region":"RegionOne",
                  "internalURL":"http://166.78.21.23:8776/v1/604bbe45ac7143a79e14f3158df67091",
                  "id":"221a2df63537400e929c0ce7184c5d68",
                  "publicURL":"http://166.78.21.23:8776/v1/604bbe45ac7143a79e14f3158df67091"
               }
            ],
            "endpoints_links":[

            ],
            "type":"volume",
            "name":"cinder"
         },
         {
            "endpoints":[
               {
                  "adminURL":"http://166.78.21.23:8773/services/Admin",
                  "region":"RegionOne",
                  "internalURL":"http://166.78.21.23:8773/services/Cloud",
                  "id":"356f334fdb7045f7a35b0eebe26fca53",
                  "publicURL":"http://166.78.21.23:8773/services/Cloud"
               }
            ],
            "endpoints_links":[

            ],
            "type":"ec2",
            "name":"ec2"
         },
         {
            "endpoints":[
               {
                  "adminURL":"http://166.78.21.23:35357/v2.0",
                  "region":"RegionOne",
                  "internalURL":"http://166.78.21.23:5000/v2.0",
                  "id":"10f3816574c14a5eb3d455b8a72dc9b0",
                  "publicURL":"http://166.78.21.23:5000/v2.0"
               }
            ],
            "endpoints_links":[

            ],
            "type":"identity",
            "name":"keystone"
         }
      ],
      "user":{
         "username":"admin",
         "roles_links":[

         ],
         "id":"3273a50d6cfb4a2ebc75e83cb86e1554",
         "roles":[
            {
               "name":"admin"
            }
         ],
         "name":"admin"
      },
      "metadata":{
         "is_admin":0,
         "roles":[
            "b0d525aa42784ee0a3df1730aabdcecd"
         ]
      }
   }
}
[Note]Note

If you do not know your tenant name or ID, you can send an authentication request with an empty tenant, as follows:

$ curl -i 'http://127.0.0.1:5000/v2.0/tokens' -X POST -H "Content-Type: application/json" -H "Accept: application/json"  -d '{"auth": {"tenantName": "", "passwordCredentials": {"username": "admin", "password": "devstack"}}}'

 Send API requests

This section shows how to make some Identity API and Compute API calls. For a complete list of Identity API calls, see Identity APIs. For a complete list of Compute API calls, see Compute APIs and Extensions.

Use the Identity API to request a list of tenants, as follows:

$ curl -i -X GET http://166.78.21.23:35357/v2.0/tenants -H "User-Agent: python-keystoneclient" -H "X-Auth-Token: token"
{
   "tenants_links":[

   ],
   "tenants":[
      {
         "description":null,
         "enabled":true,
         "id":"3eddf34c2f814bd5bc50a382f8fba1c6",
         "name":"demo"
      },
      {
         "description":null,
         "enabled":true,
         "id":"604bbe45ac7143a79e14f3158df67091",
         "name":"admin"
      },
      {
         "description":null,
         "enabled":true,
         "id":"78323d3574e6421b98fe5894475c69fe",
         "name":"service"
      },
      {
         "description":null,
         "enabled":true,
         "id":"da73856734d84ec29958b048d8708d82",
         "name":"invisible_to_admin"
      },
      {
         "description":null,
         "enabled":true,
         "id":"ee30a93eaade41acbcf210780dd7a0ba",
         "name":"alt_demo"
      }
   ]
}

Use the Identity API to request a list of endpoints, as follows:

$ curl -i -X GET http://166.78.21.23:35357/v2.0/endpoints -H "User-Agent: python-keystoneclient" -H "X-Auth-Token: token"
{
   "endpoints":[
      {
         "adminurl":"http://166.78.21.23:3333",
         "service_id":"95ce5af0aab747e497925a5be1d88b6b",
         "region":"RegionOne",
         "publicurl":"http://166.78.21.23:3333",
         "id":"406cae0574614d829adcbdcf16b4949b",
         "internalurl":"http://166.78.21.23:3333"
      },
      {
         "adminurl":"http://166.78.21.23:8773/services/Admin",
         "service_id":"5f1f74decf1f4478a962bcc64fc085bf",
         "region":"RegionOne",
         "publicurl":"http://166.78.21.23:8773/services/Cloud",
         "id":"14c4ae919d4045b78154744f8de08bc8",
         "internalurl":"http://166.78.21.23:8773/services/Cloud"
      },
      {
         "adminurl":"http://166.78.21.23:8776/v1/$(tenant_id)s",
         "service_id":"1d95b26ad4744e6bb0010f3755655986",
         "region":"RegionOne",
         "publicurl":"http://166.78.21.23:8776/v1/$(tenant_id)s",
         "id":"c2c8807f17f544f2a4e813adce7997a4",
         "internalurl":"http://166.78.21.23:8776/v1/$(tenant_id)s"
      },
      {
         "adminurl":"http://166.78.21.23:35357/v2.0",
         "service_id":"f7c3f51731df49cf876c816b96dba615",
         "region":"RegionOne",
         "publicurl":"http://166.78.21.23:5000/v2.0",
         "id":"f872f18d21ac4a57ae6337bf7c3b4ff0",
         "internalurl":"http://166.78.21.23:5000/v2.0"
      },
      {
         "adminurl":"http://166.78.21.23:9292",
         "service_id":"675b9a6b5d9140d794f0ca72414ed688",
         "region":"RegionOne",
         "publicurl":"http://166.78.21.23:9292",
         "id":"9883108c61af480c8715448086ec59b0",
         "internalurl":"http://166.78.21.23:9292"
      },
      {
         "internalurl":"http://166.78.21.23:8774/v2/$(tenant_id)s",
         "adminurl":"http://166.78.21.23:8774/v2/$(tenant_id)s",
         "service_id":"ea8d30c196904f569645bb5f6558b7dc",
         "region":"RegionOne",
         "id":"552b1ad2d28a42c6a80f908c6047fc06",
         "publicurl":"http://166.78.21.23:8774/v2/$(tenant_id)s"
      }
   ]
}

Use the Compute API to list servers, as follows:

$ curl -v -H "X-Auth-Token:token" http://208.123.85.197:8774/v2/tenant_id/servers
{
    "server": {
        "adminPass": "MVk5HPrazHcG",
        "id": "5bbcc3c4-1da2-4437-a48a-66f15b1b13f9",
        "links": [
            {
                "href": "http://openstack.example.com/v2/openstack/servers/5bbcc3c4-1da2-4437-a48a-66f15b1b13f9",
                "rel": "self"
            },
            {
                "href": "http://openstack.example.com/openstack/servers/5bbcc3c4-1da2-4437-a48a-66f15b1b13f9",
                "rel": "bookmark"
            }
        ]
    }
}

 OpenStack command-line clients

For scripting work, you can use a command-line client like the python-novaclient client. This client enables you to use the Compute API through a command-line interface.

For information about the command-line clients, see OpenStack Command Line Interface Reference.

 Install the clients

Use pip to install the OpenStack clients on a Mac OS X or Linux system. It is easy and ensures that you get the latest version of the client from the Python Package Index. Also, pip lets you update or remove a package. After you install the clients, you must source an openrc file to set required environment variables before you can request OpenStack services through the clients or the APIs. For complete information about the OpenStack clients including how to source the openrc file, see OpenStack End User Guide, OpenStack Admin User Guide, and OpenStack Command Line Interface Reference.

You must install each client separately.

Run the following command to install or update a client package:

$ sudo pip install [--upgrade] python-PROJECTclient

Where PROJECT is the project name.

For example, to install the nova client, run the following command:

$ sudo pip install python-novaclient

To update the nova client, run the following command:

$ sudo pip install --upgrade python-novaclient

To remove the nova client, run the following command:

$ sudo pip uninstall python-novaclient

Before you can issue client commands, you must download and source the openrc file to set environment variables.

 Launch an instance

To launch instances, you must choose a name, an image, and a flavor for your instance.

To list available images, call the Compute API through the nova client, as follows:

$ nova image-list
+--------------------------------------+---------------------------------+--------+--------+
| ID                                   | Name                            | Status | Server |
+--------------------------------------+---------------------------------+--------+--------+
| 949c80c8-b4ac-4315-844e-69f9bef39ed1 | cirros-0.3.1-x86_64-uec         | ACTIVE |        |
| 2d96f33d-ff66-4cac-b377-820cdf51204a | cirros-0.3.1-x86_64-uec-kernel  | ACTIVE |        |
| eda9e5cb-4c8c-4e88-b580-7fac80ad8e78 | cirros-0.3.1-x86_64-uec-ramdisk | ACTIVE |        |
+--------------------------------------+---------------------------------+--------+--------+

To list flavors, run the following command:

$ nova flavor-list
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| ID | Name      | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+
| 1  | m1.tiny   | 512       | 0    | 0         |      | 1     | 1.0         | True      |
| 2  | m1.small  | 2048      | 20   | 0         |      | 1     | 1.0         | True      |
| 3  | m1.medium | 4096      | 40   | 0         |      | 2     | 1.0         | True      |
| 4  | m1.large  | 8192      | 80   | 0         |      | 4     | 1.0         | True      |
| 42 | m1.nano   | 64        | 0    | 0         |      | 1     | 1.0         | True      |
| 5  | m1.xlarge | 16384     | 160  | 0         |      | 8     | 1.0         | True      |
| 84 | m1.micro  | 128       | 0    | 0         |      | 1     | 1.0         | True      |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+       

To launch an instance, note the IDs of your desired image and flavor.

To launch an instance named my_instance, run the nova boot command with the image and flavor IDs and the server name, as follows:

$ nova boot --image 949c80c8-b4ac-4315-844e-69f9bef39ed1 --flavor 2 my_instance
+-------------------------------------+--------------------------------------+
| Property                            | Value                                |
+-------------------------------------+--------------------------------------+
| OS-DCF:diskConfig                   | MANUAL                               |
| OS-EXT-AZ:availability_zone         | nova                                 |
| OS-EXT-SRV-ATTR:host                | None                                 |
| OS-EXT-SRV-ATTR:hypervisor_hostname | None                                 |
| OS-EXT-SRV-ATTR:instance_name       | instance-00000001                    |
| OS-EXT-STS:power_state              | 0                                    |
| OS-EXT-STS:task_state               | scheduling                           |
| OS-EXT-STS:vm_state                 | building                             |
| accessIPv4                          |                                      |
| accessIPv6                          |                                      |
| adminPass                           | XysUgJRnkB2y                         |
| config_drive                        |                                      |
| created                             | 2013-11-07T17:34:16Z                 |
| flavor                              | m1.small                             |
| hostId                              |                                      |
| id                                  | 66129319-1f1d-420d-a226-bf9fc5ea0138 |
| image                               | cirros-0.3.1-x86_64-uec              |
| key_name                            | None                                 |
| metadata                            | {}                                   |
| name                                | my_instance                          |
| progress                            | 0                                    |
| security_groups                     | [{u'name': u'default'}]              |
| status                              | BUILD                                |
| tenant_id                           | 604bbe45ac7143a79e14f3158df67091     |
| updated                             | 2013-11-07T17:34:16Z                 |
| user_id                             | 3273a50d6cfb4a2ebc75e83cb86e1554     |
+-------------------------------------+--------------------------------------+

Use the nova list command to view your server:

$ nova list
+--------------------------------------+-------------+--------+------------+-------------+------------------+
| ID                                   | Name        | Status | Task State | Power State | Networks         |
+--------------------------------------+-------------+--------+------------+-------------+------------------+
| 66129319-1f1d-420d-a226-bf9fc5ea0138 | my_instance | ACTIVE | None       | Running     | private=10.0.0.2 |
+--------------------------------------+-------------+--------+------------+-------------+------------------+

To view details for a specified server, use the nova show command. Include the ID of the server:

$ nova show 66129319-1f1d-420d-a226-bf9fc5ea0138
+-------------------------------------+----------------------------------------------------------------+
| Property                            | Value                                                          |
+-------------------------------------+----------------------------------------------------------------+
| OS-DCF:diskConfig                   | MANUAL                                                         |
| OS-EXT-AZ:availability_zone         | nova                                                           |
| OS-EXT-SRV-ATTR:host                | devstack-grizzly                                               |
| OS-EXT-SRV-ATTR:hypervisor_hostname | devstack-grizzly                                               |
| OS-EXT-SRV-ATTR:instance_name       | instance-00000001                                              |
| OS-EXT-STS:power_state              | 1                                                              |
| OS-EXT-STS:task_state               | None                                                           |
| OS-EXT-STS:vm_state                 | active                                                         |
| accessIPv4                          |                                                                |
| accessIPv6                          |                                                                |
| config_drive                        |                                                                |
| created                             | 2013-11-07T17:34:16Z                                           |
| flavor                              | m1.small (2)                                                   |
| hostId                              | d57e6f9f7885c615794b4d5a87103509620b6a7f567f7e7bd57e97a2       |
| id                                  | 66129319-1f1d-420d-a226-bf9fc5ea0138                           |
| image                               | cirros-0.3.1-x86_64-uec (949c80c8-b4ac-4315-844e-69f9bef39ed1) |
| key_name                            | None                                                           |
| metadata                            | {}                                                             |
| name                                | my_instance                                                    |
| private network                     | 10.0.0.2                                                       |
| progress                            | 0                                                              |
| security_groups                     | [{u'name': u'default'}]                                        |
| status                              | ACTIVE                                                         |
| tenant_id                           | 604bbe45ac7143a79e14f3158df67091                               |
| updated                             | 2013-11-07T17:34:32Z                                           |
| user_id                             | 3273a50d6cfb4a2ebc75e83cb86e1554                               |
+-------------------------------------+----------------------------------------------------------------+
Questions? Discuss on ask.openstack.org
Found an error? Report a bug against this page