openstack
/
openstack-manuals
Code Issues Proposed changes

Fixes for multiple doc comments plus API Quick Start work 

from http://disq.us/3qkdpj and http://disq.us/3qfc8q

Change-Id: Ie9751dbdd80bf2f3ac904cf9cfa6f1f80c98a1cc
This commit is contained in:
annegentle 2011-10-11 21:46:08 -05:00
parent 6f824a89ce
commit 5c55815f9f
7 changed files with 356 additions and 194 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
doc/src/docbkx/api-quick-start/src/docbkx/api-examples.xml
View File

@ -8,13 +8,36 @@
<title>OpenStack API Examples</title>
<para>Here are some examples of the basic API commands you can send to an OpenStack deployment
containing Compute, the Image Service, and with a running Identity Server. </para>
containing Compute, the Image Service, with a running Identity Server. In the "service
catalog" that is returned when you get a token, you can find the endpoint URLs that you use
for these API commands. For example this public URL entry in the service catalog offers the
URL for the Image Service, code-named glance: </para>
<para>
<literallayout class="monospaced">"publicURL": "http://55.51.11.198:9292/v1.1/9"}], "type": "image", "name": "glance"</literallayout>
</para>
<para>For the Compute API, you see a service of type compute, code-named "nova" such as: </para>
<para>
<literallayout class="monospaced">"publicURL": "http://55.51.11.198:8774/v1.1/9"}], "type": "compute", "name": "nova"</literallayout>
</para>
<para>With these publicURLs in hand, you can now use curl commands for these endpoints and send
API requests. The following sections offer walk-throughs of common API commands. Refer to
<link xlink:href="http://docs.openstack.org/api">docs.openstack.org/api</link> for a
full reference of all API commands for these services.</para>
<section xml:id="Compute-API-Server-Examples-a09234">
<title>Compute API Server Examples</title>
<para>GET /v1.1/servers</para>
<title>Compute API Server Information Examples</title>
<para><emphasis role="bold">GET /v1.1/servers</emphasis></para>
<para>Gives you a listing of active servers under your account and tenant authorized with a
particular token. If there are no servers running, you see just "{"servers": []}"
returned but still get a 200 OK response.</para>
<para>Curl example: </para>
<literallayout class="monospaced">curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v http://host.na.me:8774/v1.1/9/servers</literallayout>
<para>GET /v1.1/servers/details</para>
<para><emphasis role="bold">GET /v1.1/servers/detail</emphasis></para>
<para>Shows details of all the active servers currently running under your account. </para>
<para>Curl example:</para>
<para>curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v
http://demo.rcb.me:8774/v1.1/9/servers/detail </para>
<para>POST /v1.1/servers</para>
<para>GET /v1.1/servers/<emphasis role="italic">id</emphasis></para>
<para>PUT /v1.1/servers/<emphasis role="italic">id</emphasis></para>
@ -33,8 +56,54 @@
<section xml:id="Compute-API-Server-Flavor-Examples-a10234">
<title>Compute API Flavor Examples</title>
<para>GET /v1.1/flavors</para>
<para>GET /v1.1/flavors/detail</para>
<para><emphasis role="bold">GET /v1.1/flavors</emphasis></para>
<para>Gives you a listing of flavors available, which are combinations of disk space, memory
and CPU capacity bundled together as resources for virtual machines.</para>
<para>Curl example: </para>
<literallayout class="monospaced">curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v
http://demo.rcb.me:8774/v1.1/9/flavors
{"flavors": [{"id": 3, "links": [
{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/3", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/3", "rel": "bookmark"}], "name": "m1.medium"},
{"id": 4, "links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/4", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/4", "rel": "bookmark"}], "name": "m1.large"},
{"id": 1, "links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/1", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/1", "rel": "bookmark"}], "name": "m1.tiny"},
{"id": 5, "links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/5", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/5", "rel": "bookmark"}], "name": "m1.xlarge"},
{"id": 2, "links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/2", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/2", "rel": "bookmark"}], "name": "m1.small"}]}</literallayout>
<para><emphasis role="bold">GET /v1.1/flavors/&lt;id></emphasis></para>
<para>Gives you more detail about the specific flavor. </para>
<para>Curl example:</para>
<para>curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v
http://demo.rcb.me:8774/v1.1/9/flavors/5</para>
<para>{"flavor": {"rxtx_quota": 0, "name": "m1.xlarge", "links": [{"href":
"http://demo.rcb.me:8774/v1.1/9/flavors/5", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/5", "rel": "bookmark"}], "ram": 16384, "vcpus": 8,
"rxtx_cap": 0, "swap": 0, "disk": 160, "id": 5}}</para>
<para><emphasis role="bold">GET /v1.1/flavors/detail</emphasis></para>
<para>Gives you details on all the available instance types (flavors). </para>
<para>Curl example: </para>
<para>curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v
http://demo.rcb.me:8774/v1.1/9/flavors/detail</para>
<para>{"flavors": [{"rxtx_quota": 0, "name": "m1.medium", "links": [{"href":
"http://demo.rcb.me:8774/v1.1/9/flavors/3", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/3", "rel": "bookmark"}], "ram": 4096, "vcpus": 2,
"rxtx_cap": 0, "swap": 0, "disk": 40, "id": 3}, {"rxtx_quota": 0, "name": "m1.large",
"links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/4", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/4", "rel": "bookmark"}], "ram": 8192, "vcpus": 4,
"rxtx_cap": 0, "swap": 0, "disk": 80, "id": 4}, {"rxtx_quota": 0, "name": "m1.tiny",
"links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/1", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/1", "rel": "bookmark"}], "ram": 512, "vcpus": 1,
"rxtx_cap": 0, "swap": 0, "disk": 0, "id": 1}, {"rxtx_quota": 0, "name": "m1.xlarge",
"links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/5", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/5", "rel": "bookmark"}], "ram": 16384, "vcpus": 8,
"rxtx_cap": 0, "swap": 0, "disk": 160, "id": 5}, {"rxtx_quota": 0, "name": "m1.small",
"links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/2", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/2", "rel": "bookmark"}], "ram": 2048, "vcpus": 1,
"rxtx_cap": 0, "swap": 0, "disk": 20, "id": 2}]}</para>
</section>
<section xml:id="Compute-API-Server-Extensions-Examples-a09744">
@ -43,6 +112,10 @@
</section>
<section xml:id="Image-API-Examples"><title>Image API Examples</title>
<para>GET /images</para>
<para>Example</para>
<para>
<literallayout class="monospaced">curl -D - -H GET http://host.na.me:9292/v1/images</literallayout>
</para>
<para>GET /images/details</para>
<para>GET /images/<emphasis role="italic">id</emphasis></para>
<para>POST /images</para>

43
doc/src/docbkx/api-quick-start/src/docbkx/api-quick-start-book.xml Normal file
View File

@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml"
version="5.0"
xml:id="openstack-api-quick-start">
<title>OpenStack API Quick Start</title>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
<affiliation>
<orgname>OpenStack</orgname>
</affiliation>
</author>
<copyright>
<year>2010</year>
<year>2011</year>
<holder>OpenStack LLC</holder>
</copyright>
<releaseinfo>Diablo</releaseinfo>
<productname>OpenStack Compute, Identity, and Image Services</productname>
<pubdate>2011-10-11</pubdate>
<legalnotice role="cc-by-sa">
<annotation>
<remark>Remaining licensing details are filled in by the template.</remark>
</annotation>
</legalnotice>
<abstract>
<para>OpenStack™ projects offer RESTful APIs for manipulating and retrieving objects in the cloud. This manual provides examples for sending REST requests using the Compute API v1.1, Identity API v2.0, and the Image API v1.1. </para>
</abstract>
</info>
<!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. -->
<xi:include href="api-quick-start.xml"/>
<xi:include href="cli-uses.xml"/>
<xi:include href="api-examples.xml"/>
</book>

200
doc/src/docbkx/api-quick-start/src/docbkx/api-quick-start.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook"
<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"
@ -9,9 +9,8 @@
<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 such as the Rackspace Rapid Deployment Program, the OpenStack Compute,
OpenStack Identity, and OpenStack Image Store projects are all working together in the
background of your installation. </para>
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>
@ -33,7 +32,7 @@
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://hostname:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'
$ 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>
@ -53,7 +52,20 @@ $ curl -X 'POST' -v http://hostname:5000/v2.0/tokens -d '{"auth":{"passwordCrede
&gt;
* 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"}}}
{"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
@ -73,7 +85,7 @@ $ curl -X 'POST' -v http://hostname:5000/v2.0/tokens -d '{"auth":{"passwordCrede
<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://hostname:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'
$ 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>
@ -95,7 +107,22 @@ $ curl -X 'POST' -v http://hostname:5000/v2.0/tokens -d '{"auth":{"passwordCrede
&gt;
* 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"}}}
{"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>
@ -111,162 +138,7 @@ $ curl -X 'POST' -v http://hostname:5000/v2.0/tokens -d '{"auth":{"passwordCrede
<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>
<para>For more serious scripting work, you can use a client like the python-novaclient or
openstack-compute clients. The python-novaclient implements the Compute 1.1 API while
the openstack-compute client works against the Rackspace Cloud Servers public cloud
which is the OpenStack Compute 1.0 API. You only need a username and password to use the
python-novaclient tool. </para>
</section>
<section xml:id="Setting-Up-python-novaclient-a03867"><title>Setting Up python-novaclient</title><para>Installing the python-novaclient gives you a <code>nova</code> shell command that enables
Compute API interactions from the command line. You install the client, and then provide
your username and password, set as environment variables for convenience, and then you
can have the ability to send commands to your cloud on the command-line.</para>
<para>To install python-novaclient, download the tarball from
<link xlink:href="http://pypi.python.org/pypi/python-novaclient/2.6.3#downloads">http://pypi.python.org/pypi/python-novaclient/2.6.3#downloads</link> and then install it in your favorite python environment. </para>
<programlisting>
$ curl -O http://pypi.python.org/packages/source/p/python-novaclient/python-novaclient-2.6.3.tar.gz
$ tar -zxvf python-novaclient-2.6.3.tar.gz
$ cd python-novaclient-2.6.3
$ sudo python setup.py install
</programlisting>
<para>Now that you have installed the python-novaclient, confirm the installation by entering:</para><programlisting>
$ nova help
usage: nova [--username USERNAME] [--apikey APIKEY] [--projectid PROJECTID]
[--url URL] [--version VERSION]
&lt;subcommand&gt; ...
</programlisting>
<para>In return, you will get a listing of all the commands and parameters for the nova command line client. By setting up the required parameters as environment variables, you can fly through these commands on the command line. You can add --username on the nova command, or set them as environment variables: </para>
<para><programlisting>
export NOVA_USERNAME=joecool
export NOVA_API_KEY=coolword
export NOVA_PROJECT_ID=coolu
</programlisting>
</para><para>Using the Identity Service, you are supplied with an authentication endpoint, which nova recognizes as the NOVA_URL. </para>
<para>
<programlisting>
export NOVA_URL=http://hostname:5000/v2.0
export NOVA_VERSION=1.1
</programlisting>
</para></section>
<section xml:id="Launching-Images-a09140"><title>Listing Images</title><para>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:
<programlisting>
$ nova image-list
+----+-------------------------------------------------------+--------+
| ID | Name | Status |
+----+-------------------------------------------------------+--------+
| 1 | aki-tty | ACTIVE |
| 2 | ari-tty | ACTIVE |
| 3 | ami-tty | ACTIVE |
| 6 | CentOS_5.4_x64 | ACTIVE |
| 14 | maverick-kernel | ACTIVE |
| 15 | maverick | ACTIVE |
| 20 | ubuntu-kernel | ACTIVE |
| 21 | ubuntu-ramdisk | ACTIVE |
| 22 | ubuntu | ACTIVE |
| 24 | CentOS_5.6_x64_v5.7.14_Dev1 | ACTIVE |
+----+-------------------------------------------------------+--------+
</programlisting></para>
<para>Next you need to know the relative sizes of each of these. </para>
<para><programlisting>
$ nova flavor-list
+----+-----------+-----------+------+----------+-------+------------+----------+
| ID | Name | Memory_MB | Swap | Local_GB | VCPUs | RXTX_Quota | RXTX_Cap |
+----+-----------+-----------+------+----------+-------+------------+----------+
| 1 | m1.tiny | 512 | | 0 | | | |
| 2 | m1.small | 2048 | | 20 | | | |
| 3 | m1.medium | 4096 | | 40 | | | |
| 4 | m1.large | 8192 | | 80 | | | |
| 5 | m1.xlarge | 16384 | | 160 | | | |
| 89 | Boom | 2 | | 20 | | | |
+----+-----------+-----------+------+----------+-------+------------+----------+
</programlisting></para>
<para>You can also narrow down the list by using grep to find only the CentOS images with a command like this: </para>
<para>
<programlisting>
$ nova image-list | grep 'CentOS'
| 6 | CentOS_5.4_x64 | ACTIVE |
| 24 | CentOS_5.6_x64_v5.7.14_Dev1 | ACTIVE |
</programlisting>
</para>
<para>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. </para></section>
<section xml:id="Listing-Images-a01518"><title>Launching Instances </title>
<para>
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 Maverick image has an ID of 15, 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. Put those parameters in with the "boot" command and you can create a new virtual server.
</para>
<para>
<programlisting>
$ nova boot --flavor=2 --image=15 testserver
+-----------+--------------------------------------+
| Property | Value |
+-----------+--------------------------------------+
| adminPass | **************** |
| created | 2011-09-01T21:40:41Z |
| flavor | m1.small |
| hostId | |
| id | 1805 |
| image | maverick |
| metadata | {} |
| name | testserver |
| progress | 0 |
| status | BUILD |
| updated | 2011-09-01T21:40:41Z |
| uuid | ce044452-f22e-4ea4-a3ec-d1cde80cf996 |
+-----------+--------------------------------------+
</programlisting>
</para>
<para>Now, you can view this server in your new cloud by using the nova list
command:<programlisting>
$ nova list
+------+------------+--------+--------------------------------+
| ID | Name | Status | Networks |
+------+------------+--------+--------------------------------+
| 1805 | testserver | ACTIVE | private=10.4.96.81 |
+------+------------+--------+--------------------------------+
</programlisting></para>
<para>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 <code>nova list</code> again until it goes away.</para>
<para>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.</para>
<programlisting>
$ nova show 1805
+-----------------+----------------------------------------------------------+
| Property | Value |
+-----------------+----------------------------------------------------------+
| created | 2011-09-01T21:40:41Z |
| flavor | m1.small |
| hostId | 58a7430169aa42cde5ce2456b0cb5bb5ac1ab0703bab6420e8a49e6e |
| id | 1805 |
| image | maverick |
| 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 |
+-----------------+----------------------------------------------------------+
</programlisting>
<para>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.
<programlisting>$ nova boot testserver --meta description='Use for testing purposes' --meta creator=joecool</programlisting></para>
</section>
</article>
</chapter>

160
doc/src/docbkx/api-quick-start/src/docbkx/cli-uses.xml Normal file
View File

@ -0,0 +1,160 @@
<?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="Setting-Up-Python-novaclient"
version="5.0">
<title>Setting Up python-novaclient</title>
<para>For more serious scripting work, you can use a client like the python-novaclient or openstack-compute clients. The python-novaclient implements the Compute 1.1 API while the openstack-compute client works against the Rackspace Cloud Servers public cloud which is the OpenStack Compute 1.0 API. You only need a username and password to use the python-novaclient tool. </para>
<para>Installing the python-novaclient gives you a <code>nova</code> shell command that enables
Compute API interactions from the command line. You install the client, and then provide
your username and password, set as environment variables for convenience, and then you
can have the ability to send commands to your cloud on the command-line.</para>
<para>To install python-novaclient, download the tarball from
<link xlink:href="http://pypi.python.org/pypi/python-novaclient/2.6.3#downloads">http://pypi.python.org/pypi/python-novaclient/2.6.3#downloads</link> and then install it in your favorite python environment. </para>
<programlisting>
$ curl -O http://pypi.python.org/packages/source/p/python-novaclient/python-novaclient-2.6.3.tar.gz
$ tar -zxvf python-novaclient-2.6.3.tar.gz
$ cd python-novaclient-2.6.3
$ sudo python setup.py install
</programlisting>
<para>Now that you have installed the python-novaclient, confirm the installation by entering:</para><programlisting>
$ nova help
usage: nova [--username USERNAME] [--apikey APIKEY] [--projectid PROJECTID]
[--url URL] [--version VERSION]
&lt;subcommand&gt; ...
</programlisting>
<para>In return, you will get a listing of all the commands and parameters for the nova command line client. By setting up the required parameters as environment variables, you can fly through these commands on the command line. You can add --username on the nova command, or set them as environment variables: </para>
<para><programlisting>
export NOVA_USERNAME=joecool
export NOVA_API_KEY=coolword
export NOVA_PROJECT_ID=coolu
</programlisting>
</para><para>Using the Identity Service, you are supplied with an authentication endpoint, which nova recognizes as the NOVA_URL. </para>
<para>
<programlisting>
export NOVA_URL=http://hostname:5000/v2.0
export NOVA_VERSION=1.1
</programlisting>
</para>
<section xml:id="Launching-Images-a09140"><title>Listing Images</title><para>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:
<programlisting>
$ nova image-list
+----+-------------------------------------------------------+--------+
| ID | Name | Status |
+----+-------------------------------------------------------+--------+
| 1 | aki-tty | ACTIVE |
| 2 | ari-tty | ACTIVE |
| 3 | ami-tty | ACTIVE |
| 6 | CentOS_5.4_x64 | ACTIVE |
| 14 | maverick-kernel | ACTIVE |
| 15 | maverick | ACTIVE |
| 20 | ubuntu-kernel | ACTIVE |
| 21 | ubuntu-ramdisk | ACTIVE |
| 22 | ubuntu | ACTIVE |
| 24 | CentOS_5.6_x64_v5.7.14_Dev1 | ACTIVE |
+----+-------------------------------------------------------+--------+
</programlisting></para>
<para>Next you need to know the relative sizes of each of these. </para>
<para><programlisting>
$ nova flavor-list
+----+-----------+-----------+------+----------+-------+------------+----------+
| ID | Name | Memory_MB | Swap | Local_GB | VCPUs | RXTX_Quota | RXTX_Cap |
+----+-----------+-----------+------+----------+-------+------------+----------+
| 1 | m1.tiny | 512 | | 0 | | | |
| 2 | m1.small | 2048 | | 20 | | | |
| 3 | m1.medium | 4096 | | 40 | | | |
| 4 | m1.large | 8192 | | 80 | | | |
| 5 | m1.xlarge | 16384 | | 160 | | | |
| 89 | Boom | 2 | | 20 | | | |
+----+-----------+-----------+------+----------+-------+------------+----------+
</programlisting></para>
<para>You can also narrow down the list by using grep to find only the CentOS images with a command like this: </para>
<para>
<programlisting>
$ nova image-list | grep 'CentOS'
| 6 | CentOS_5.4_x64 | ACTIVE |
| 24 | CentOS_5.6_x64_v5.7.14_Dev1 | ACTIVE |
</programlisting>
</para>
<para>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. </para></section>
<section xml:id="Listing-Images-a01518"><title>Launching Instances </title>
<para>
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 Maverick image has an ID of 15, 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. Put those parameters in with the "boot" command and you can create a new virtual server.
</para>
<para>
<programlisting>
$ nova boot --flavor=2 --image=15 testserver
+-----------+--------------------------------------+
| Property | Value |
+-----------+--------------------------------------+
| adminPass | **************** |
| created | 2011-09-01T21:40:41Z |
| flavor | m1.small |
| hostId | |
| id | 1805 |
| image | maverick |
| metadata | {} |
| name | testserver |
| progress | 0 |
| status | BUILD |
| updated | 2011-09-01T21:40:41Z |
| uuid | ce044452-f22e-4ea4-a3ec-d1cde80cf996 |
+-----------+--------------------------------------+
</programlisting>
</para>
<para>Now, you can view this server in your new cloud by using the nova list
command:<programlisting>
$ nova list
+------+------------+--------+--------------------------------+
| ID | Name | Status | Networks |
+------+------------+--------+--------------------------------+
| 1805 | testserver | ACTIVE | private=10.4.96.81 |
+------+------------+--------+--------------------------------+
</programlisting></para>
<para>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 <code>nova list</code> again until it goes away.</para>
<para>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.</para>
<programlisting>
$ nova show 1805
+-----------------+----------------------------------------------------------+
| Property | Value |
+-----------------+----------------------------------------------------------+
| created | 2011-09-01T21:40:41Z |
| flavor | m1.small |
| hostId | 58a7430169aa42cde5ce2456b0cb5bb5ac1ab0703bab6420e8a49e6e |
| id | 1805 |
| image | maverick |
| 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 |
+-----------------+----------------------------------------------------------+
</programlisting>
<para>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.
<programlisting>$ nova boot testserver --meta description='Use for testing purposes' --meta creator=joecool</programlisting></para>
</section></chapter>

45
doc/src/docbkx/openstack-compute-admin/computeinstall.xml
View File

@ -276,7 +276,7 @@ sudo service mysql restart</literallayout></para>
PASSWORD('$NOVA_PASS');"</literallayout>
</para>
</section>
<section xml:id="setting-up-sql-database-postgresql"><title>Setting Up PostgreSQL as the Database</title>
<section xml:id="setting-up-sql-database-postgresql"><title>Setting Up PostgreSQL as the Database on the Cloud Controller</title>
<para>OpenStack can use PostgreSQL as an alternative database. This is a matter of substituting the MySQL steps with PostgreSQL equivalents, as outlined here.</para>
@ -473,7 +473,7 @@ $ for n in node1 node2 node3; do ssh $n sudo service openstack-nova-compute star
follows:</para>
<literallayout class="monospaced">--daemonize=1
--dhcpbridge_flagfile=/etc/nova/nova.conf
--dhcpbridge=/usr/bin/nova-dhcpbridge
--dhcpbridge=/bin/nova-dhcpbridge
--logdir=/var/log/nova
--state_path=/var/lib/nova </literallayout>
<para>Starting with the default file, you must define the following required items in
@ -491,7 +491,8 @@ $ for n in node1 node2 node3; do ssh $n sudo service openstack-nova-compute star
<tbody>
<tr>
<td>--sql_connection</td>
<td>IP address; Location of OpenStack Compute SQL database</td>
<td>SQL Alchemy connect string (reference); Location of OpenStack Compute
SQL database</td>
</tr>
<tr>
<td>--s3_host</td>
@ -500,21 +501,14 @@ $ for n in node1 node2 node3; do ssh $n sudo service openstack-nova-compute star
</tr>
<tr>
<td>--rabbit_host</td>
<td>IP address; Location of OpenStack Compute SQL database</td>
</tr>
<tr>
<td>--ec2_api</td>
<td>IP address; Location where the nova-api service runs</td>
<td>IP address; Location of RabbitMQ server</td>
</tr>
<tr>
<td>--verbose</td>
<td>Set to 1 to turn on; Optional but helpful during initial setup</td>
</tr>
<tr>
<td>--ec2_url</td>
<td>HTTP URL; Location to interface nova-api. Example:
http://184.106.239.134:8773/services/Cloud</td>
</tr>
<tr>
<td>--network_manager</td>
<td>
@ -542,6 +536,14 @@ $ for n in node1 node2 node3; do ssh $n sudo service openstack-nova-compute star
<td>IP address/range; Network prefix for the IP network that all the
projects for future VM guests reside on. Example: 192.168.0.0/12</td>
</tr>
<tr>
<td>--ec2_host</td>
<td>IP address; Indicates where the nova-api service is installed.</td>
</tr>
<tr>
<td>--osapi_host</td>
<td>IP address; Indicates where the nova-api service is installed.</td>
</tr>
<tr>
<td>--network_size</td>
<td>Number value; Number of addresses in each private subnet.</td>
@ -550,6 +552,10 @@ $ for n in node1 node2 node3; do ssh $n sudo service openstack-nova-compute star
<td>--glance_api_servers </td>
<td>IP and port; Address for Image Service.</td>
</tr>
<tr>
<td>--use_deprecated_auth </td>
<td>If this flag is present, the Cactus method of authentication is used with the novarc file containing credentials.</td>
</tr>
</tbody>
</table>
@ -557,14 +563,15 @@ $ for n in node1 node2 node3; do ssh $n sudo service openstack-nova-compute star
cloud controller services, database server, and messaging server on the same
server.</para>
<literallayout class="monospaced">--dhcpbridge_flagfile=/etc/nova/nova.conf
--dhcpbridge=/usr/bin/nova-dhcpbridge
--dhcpbridge=/bin/nova-dhcpbridge
--logdir=/var/log/nova
--state_path=/var/lib/nova
--verbose
--use_deprecated_auth
--ec2_host=http://184.106.239.134
--osapi_host=http://184.106.239.134
--s3_host=184.106.239.134
--rabbit_host=184.106.239.134
--ec2_api=184.106.239.134
--ec2_url=http://184.106.239.134:8773/services/Cloud
--fixed_range=192.168.0.0/16
--network_size=8
--glance_api_servers=184.106.239.134:9292
@ -573,8 +580,10 @@ $ for n in node1 node2 node3; do ssh $n sudo service openstack-nova-compute star
<para>Create a “nova” group, so you can set permissions on the configuration file: </para>
<literallayout class="monospaced">sudo addgroup nova</literallayout>
<para>The nova.config file should have its owner set to root:nova, and mode set to 0640,
since the file contains your MySQL server’s username and password. </para>
<literallayout class="monospaced">chown -R root:nova /etc/nova
since the file contains your MySQL server’s username and password. You also want to
ensure that the nova user belongs to the nova group.</para>
<literallayout class="monospaced">sudo usermod -g nova nova
chown -R root:nova /etc/nova
chmod 640 /etc/nova/nova.conf</literallayout>
</section><section xml:id="setting-up-openstack-compute-environment-on-the-compute-node">
<title>Setting Up OpenStack Compute Environment on the Compute Node</title>

15
doc/src/docbkx/openstack-compute-admin/interfaces.xml
View File

@ -74,10 +74,10 @@ git clone https://github.com/4P/openstack-dashboard
</para>
<para>
<literallayout class="monospaced">
cd openstack-dashboard/openstack-dashboard
cp local_settings.py.example local/local_settings.py
vi local_settings.py
</literallayout>
cd openstack-dashboard/openstack-dashboard/local
cp local_settings.py.example local_settings.py
vi local_settings.py
</literallayout>
</para>
<para>In the new copy of the local_settings.py file, change these important options:</para>
<itemizedlist>
@ -132,7 +132,12 @@ QUANTUM_CLIENT_VERSION='0.1'
</section>
<section xml:id="run-the-server">
<title>Run the Server</title>
<para>Dashboard is run using the standard Django manage.py script from the context of the virtual environment. Run the server on a high port value so that you can validate the installation.</para><para><literallayout class="monospaced">tools/with_venv.sh dashboard/manage.py runserver 0.0.0.0:8000</literallayout></para><para>Make sure that your firewall isn't blocking TCP/8000 and just point your browser at this server on port 8000. If you are running the server on the same machine as your browser, this would be "http://localhost:8000". </para>
<para>Dashboard is run using the standard Django manage.py script from the context
of the virtual environment. Be sure you synchronize the database with this
command: </para>
<literallayout class="monospaced">tools/with_venv.sh dashboard/manage.py syncdb</literallayout>
<para>Run the server on a high port value so that you can validate the
installation.</para><para><literallayout class="monospaced">tools/with_venv.sh dashboard/manage.py runserver 0.0.0.0:8000</literallayout></para><para>Make sure that your firewall isn't blocking TCP/8000 and just point your browser at this server on port 8000. If you are running the server on the same machine as your browser, this would be "http://localhost:8000". </para>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/dashboard-overview.png"

2
doc/src/docbkx/openstack-compute-admin/os-compute-adminguide.xml
View File

@ -24,7 +24,7 @@
</copyright>
<releaseinfo>Diablo</releaseinfo>
<productname>OpenStack Compute</productname>
<pubdate>2011-10-07</pubdate>
<pubdate>2011-10-11</pubdate>
<legalnotice role="apache2">
<annotation>
<remark>Copyright details are filled in by the template.</remark>