145 lines
8.3 KiB
XML
145 lines
8.3 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xml:id="Compute_API_Quick_Start"
|
|
version="5.0">
|
|
|
|
<title>OpenStack API Quick Start</title>
|
|
<para>The OpenStack system has several key projects that are separate installations but can work
|
|
together depending on your cloud needs: OpenStack Compute, OpenStack Object Storage,
|
|
OpenStack Identity Service, and OpenStack Image Store. With a standalone OpenStack
|
|
installation, the OpenStack Compute, OpenStack Identity, and OpenStack Image Store projects
|
|
are all working together in the background of your installation. </para>
|
|
<section xml:id="Openstack-API-Concepts-a09234">
|
|
|
|
<title>OpenStack API Introduction</title>
|
|
<para>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 1.1 specification and the
|
|
Identity Service 2.0 Developer Guide published at <link xlink:href="http://docs.openstack.org">docs.openstack.org</link>. </para></section>
|
|
<section xml:id="Getting-Credentials-a00665"><title>Getting Credentials</title><para>Credentials are a combination of your username, 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 username and a password as well as your tenant
|
|
identifier so you can generate authorization tokens. 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 workflow goes something like
|
|
this: </para>
|
|
<orderedlist>
|
|
<listitem><para>Begin API requests by asking for an authorization token from the endpoint your cloud
|
|
administrator gave you, typically http://hostname:5000/v2.0/tokens. You send your
|
|
username, password, and what group you are with (the "tenant" in auth-speak). </para>
|
|
<para><programlisting>
|
|
$ curl -X 'POST' -v http://host.na.me:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'
|
|
</programlisting></para></listitem>
|
|
<listitem><para>The server returns a response in which the 24-hours token is contained :
|
|
<programlisting>
|
|
* About to connect() to host.na.me port 5000 (#0)
|
|
* Trying 55.51.11.198... connected
|
|
* Connected to host.na.me (55.51.11.198) port 5000 (#0)
|
|
> POST /v2.0/tokens HTTP/1.1
|
|
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7 OpenSSL/0.9.8r zlib/1.2.3
|
|
> Host: host.na.me:5000v> Accept: */*
|
|
> Content-type: application/json
|
|
> Content-Length: 95
|
|
>
|
|
> HTTP/1.1 200 OK
|
|
> Content-Type: application/json; charset=UTF-8
|
|
> Content-Length: 935
|
|
> Date: Thu, 06 Oct 2011 19:59:49 GMT
|
|
>
|
|
* Connection #0 to host host.na.me left intact
|
|
* Closing connection #0
|
|
{"access": {"token": {"expires": "2011-10-07T14:59:49.644963",
|
|
"id": "e83abbdc-a8c8-4f81-897b-541cbcd1dbb5",
|
|
"tenant": {"id": "5", "name": "coolu"}}, "serviceCatalog":
|
|
[{"endpoints": [{"adminURL": "http://55.51.11.198:8774/v1.1/5",
|
|
"region": "RegionOne", "internalURL": "http://55.51.11.198:8774/v1.1/5",
|
|
"publicURL": "http://55.51.11.198:8774/v1.1/5"}], "type": "compute", "name": "nova"},
|
|
{"endpoints": [{"adminURL": "http://55.51.11.198:9292/v1.1/5",
|
|
"region": "RegionOne", "internalURL": "http://55.51.11.198:9292/v1.1/5",
|
|
"publicURL": "http://55.51.11.198:9292/v1.1/5"}], "type": "image", "name": "glance"},
|
|
{"endpoints": [{"adminURL": "http://55.51.11.198:35357/v2.0",
|
|
"region": "RegionOne", "internalURL": "http://55.51.11.198:5000/v2.0",
|
|
"publicURL": "http://55.51.11.198:5000/v2.0"}],
|
|
"type": "identity", "name": "keystone"}], "user": {"id": "4", "roles":
|
|
[{"tenantId": "5", "id": "2", "name": "Member"}], "name": "joecool"}}}
|
|
|
|
</programlisting>
|
|
Use that token to send API requests with the X-Auth-Token included as an header
|
|
field.</para></listitem>
|
|
|
|
<listitem>
|
|
<para>Repeatedly send API requests with that token in the x-auth-token header until
|
|
either: 1) the job's done or 2) you get a 401 (Unauthorized) code in return.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Request a token again when you get a 401 response until the script's job is
|
|
done.</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
<para>For a typical OpenStack deployment running the Identity Service you can request a token
|
|
with this command in
|
|
cURL:<programlisting>
|
|
$ curl -X 'POST' -v http://host.na.me:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'
|
|
</programlisting></para>
|
|
<para>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:</para>
|
|
<para>
|
|
<programlisting>
|
|
* About to connect() to host.na.me port 5000 (#0)
|
|
* Trying hostname... connected
|
|
* Connected to host.na.me (hostname) port 5000 (#0)
|
|
> POST /v2.0/tokens HTTP/1.1
|
|
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7 OpenSSL/0.9.8r zlib/1.2.3
|
|
> Host: host.na.me:5000
|
|
> Accept: */*
|
|
> Content-type: application/json
|
|
> Content-Length: 85
|
|
>
|
|
> HTTP/1.1 200 OK
|
|
> Content-Type: application/json; charset=UTF-8
|
|
> Content-Length: 1213
|
|
> Date: Thu, 01 Sep 2011 19:27:30 GMT
|
|
>
|
|
* Connection #0 to host host.na.me left intact
|
|
* Closing connection #0
|
|
{"access": {"token": {"expires": "2011-10-07T14:59:49.644963",
|
|
"id": "e83abbdc-a8c8-4f81-897b-541cbcd1dbb5",
|
|
"tenant": {"id": "5", "name": "coolu"}},
|
|
"serviceCatalog":
|
|
[{"endpoints": [{"adminURL": "http://55.51.11.198:8774/v1.1/5",
|
|
"region": "RegionOne", "internalURL": "http://55.51.11.198:8774/v1.1/5",
|
|
"publicURL": "http://55.51.11.198:8774/v1.1/5"}],
|
|
"type": "compute", "name": "nova"},
|
|
{"endpoints": [{"adminURL": "http://55.51.11.198:9292/v1.1/5",
|
|
"region": "RegionOne", "internalURL": "http://55.51.11.198:9292/v1.1/5",
|
|
"publicURL": "http://55.51.11.198:9292/v1.1/5"}], "type": "image", "name": "glance"},
|
|
{"endpoints": [{"adminURL": "http://55.51.11.198:35357/v2.0",
|
|
"region": "RegionOne", "internalURL": "http://55.51.11.198:5000/v2.0",
|
|
"publicURL": "http://55.51.11.198:5000/v2.0"}],
|
|
"type": "identity", "name": "keystone"}],
|
|
"user": {"id": "4", "roles": [{"tenantId": "5", "id": "2", "name": "Member"}], "name": "joecool"}}}
|
|
</programlisting></para></section>
|
|
<section xml:id="Sending-Requests-to-API-a09879">
|
|
<title>Sending Requests to the API</title>
|
|
<para>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 <link
|
|
xlink:href="http://curl.haxx.se/">http://curl.haxx.se/</link>. With cURL you can
|
|
send HTTP requests and receive responses back from the command line. </para>
|
|
<para>If you like to use a more graphical interface, the REST client for Firefox also works
|
|
well for testing and trying out commands, see <link
|
|
xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/"
|
|
>https://addons.mozilla.org/en-US/firefox/addon/restclient/</link>. You can also
|
|
download and install rest-client, a Java application to test RESTful web services, from
|
|
<link xlink:href="http://code.google.com/p/rest-client/"
|
|
>http://code.google.com/p/rest-client/</link>. </para>
|
|
<para>You need to generate a token as shown above if you use cURL or a REST client. </para>
|
|
</section>
|
|
|
|
|
|
</chapter>
|