Contents
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.
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
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 tenantIdandtenantNameare 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 tenantIdandtenantNameare 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.
Send API requests and include the token in the
X-Auth-Tokenheader. Continue to send API requests with that token until the job completes or a 401 Unauthorized error occurs.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.
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":"
and an expiration date and time in the form
token""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]](../common/images/admon/note.png) | 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"}}}' |
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"
}
]
}
}
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.
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.
You must install each client separately.
Run this command to install or update a client package:
$ sudo pip install [--upgrade] python-PROJECTclientWhere PROJECT is the project
name.
For example, to install the nova client, run this command:
$ sudo pip install python-novaclient
To update the nova client, run this command:
$ sudo pip install --upgrade python-novaclient
To remove the nova client, run this command:
$ sudo pip uninstall python-novaclient
Before you can issue client commands, you must download
and source the openrc file to set
environment variables.
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.
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 this 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 |
+-------------------------------------+----------------------------------------------------------------+ | Note |
|---|---|
For information about the default ports that the OpenStack components use, see Appendix A. Firewalls and default ports in the OpenStack Configuration Reference. |
