x/tuskar
Code Issues Proposed changes

doc updates

Browse Source 
* created docs version of wiki pages
   * old wiki pages still remain on the wiki
   * 'Home' wiki now provides a link to docs/index.rst
* updated links to go to docs/ documents
* changed 'openstack-m' references to 'tuskar'
This commit is contained in:
Tzu-Mainn Chen 2013-08-01 23:56:35 -04:00
parent e91b2e75c7
commit f98cf95b6c
9 changed files with 754 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.rst
View File

@ -24,7 +24,7 @@ the following checklist:
2. Update the API docs (if needed)
3. Update the tests (if needed)
4. Update
`cURL commands <https://github.com/tuskar/tuskar/wiki/cURL-commands>`_
`cURL commands <https://github.com/tuskar/tuskar/blob/master/docs/api/curl.md>`_
page (if needed)
Getting Started

4
docs/api/api.md
View File

@ -1,4 +1,4 @@
# OpenStack Management API Draft
# Tuskar API Draft
## ERD diagram:
@ -9,7 +9,7 @@
## Introduction and Concepts
The main resources in the Openstack-M API are:
The main resources in the Tuskar API are:
<a name="index"></a>
* [ResourceClass](#resource_class)

341
docs/api/curl.rst Normal file
View File

@ -0,0 +1,341 @@
=============
cURL Commands
=============
Resources
---------
- `Rack <#rack>`_
- `Flavor <#flavor>`_
- `ResourceClass <#resource_class>`_
- `DataCenter <#data_center>`_
Rack
----
create
~~~~~~
::
curl -vX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '
{
"subnet": "192.168.1.0/255",
"name": "my_rack",
"capacities": [{
"name": "total_cpu",
"value": "64"
}, {
"name": "total_memory",
"value": "1024"
}],
"nodes": [{
"id": "123"
}, {
"id": "345"
}],
"slots": 1
}
' http://0.0.0.0:6385/v1/racks
create with ResourceClass
~~~~~~~~~~~~~~~~~~~~~~~~~
::
curl -vX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '
{
"subnet": "192.168.1.0/255",
"name": "my_rack",
"capacities": [{
"name": "total_cpu",
"value": "64"
}, {
"name": "total_memory",
"value": "1024"
}],
"nodes": [{
"id": "123"
}, {
"id": "345"
}],
"slots": 1,
"resource_class":{
"id":1,
"links":[
{
"href":"http://0.0.0.0:6385/v1/resource_clases/1",
"rel":"self"
}
]
}
}
' http://0.0.0.0:6385/v1/racks
delete
~~~~~~
::
curl -vX DELETE http://localhost:6385/v1/racks/1
update
~~~~~~
::
curl -v -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '{ "name": "new_name" }' http://0.0.0.0:6385/v1/racks/1
update (change nodes to Rack 1)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
curl -v -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '{ "nodes": [ { "id": "1" }, { "id": "2"}] }' http://0.0.0.0:6385/v1/racks/1
`back to top <#index>`_
Flavor
------
This resource only exists as part of a ResourceClass.
create a new Flavor for a specific ResourceClass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
curl -v -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '
{
"max_vms": 10,
"name": "tiny",
"capacities":
[
{
"value": "1",
"name": "cpu",
"unit": "count"
},
{
"value": "512",
"name": "memory",
"unit": "MiB"
},
{
"value": "512",
"name": "storage",
"unit": "GiB"
}
]
}'
http://0.0.0.0:6385/v1/resource_classes/1/flavors``
Flavors can also be created as part of `ResourceClass create <#rc_with_flavors>`_ operation:
get Flavor(s) for a particular ResourceClass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
curl -H "Accept: application/xml" http://0.0.0.0:6385/v1/resource_classes/1/flavors(/2)
delete a specific Flavor from a given ResourceClass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
curl -X DELETE -H "Accept: application/xml" http://0.0.0.0:6385/v1/resource_classes/1/flavors/1
update an existing Flavor in a specified ResourceClass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
curl -v -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '
{
"capacities":
[
{
"value": "5000",
"name": "cpu",
"unit": "count"
},
{
"value": "1111",
"name": "memory",
"unit": "MiB"
},
{
"value": "2222",
"name": "storage",
"unit": "GiB"
}
],
"max_vms": 9999,
"name": "tiny_update" }'
http://0.0.0.0:6385/v1/resource_classes/1/flavors/3``
**NOTE:** The above operation can be performed to change only part of a
given flavor - such as updating the name or max\_vms, or even a specific
capacity. The body of the PUT request will determine what is updated.
For example, to update the 'cpu' capacity and 'max\_vms':
::
curl -v -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '
{
"max_vms": 1234,
"capacities" : [
{ "name": "cpu",
"value" : "1",
"unit" : "count" }
]
}'
http://0.0.0.0:6385/v1/resource_classes/1/flavors/3``
`back to top <#index>`_
ResourceClass
-------------
get a specific ResourceClass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
curl -H 'Accept: application/json' http://0.0.0.0:6385/v1/resource_classes/1
response
^^^^^^^^
::
{
"id":11,
"name":"test-chassis",
"service_type":"compute",
"racks":[
{
"id":1,
"links":[
{
"href":"http://0.0.0.0:6385/v1/rack/1",
"rel":"self"
}
]
}
],
"links":[
{
"href":"http://0.0.0.0:6385/v1/resource_classes/11",
"rel":"self"
}
]
}
get collection
~~~~~~~~~~~~~~
::
curl -H 'Accept: application/json' http://0.0.0.0:6385/v1/resource_classes
create without Racks
~~~~~~~~~~~~~~~~~~~~
::
curl -iX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '
{
"service_type": "compute",
"name": "test-chassis"
}
' http://0.0.0.0:6385/v1/resource_classes
create with Rack and Flavor definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
curl -iX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '
{
"name": "test-chassis",
"service_type":"compute",
"racks": [
{ "id":1,
"links":[{"href":"http://0.0.0.0:6385/v1/racks/1","rel":"self"}]
}
],
"flavors": [
{ "name" : "x-large",
"capacities" : [
{ "name": "cpu",
"value" : "4",
"unit" : "count" },
{ "name": "memory",
"value" : "8192",
"unit" : "MiB" },
{ "name": "storage",
"value" : "1024",
"unit" : "GiB" }
]
}
]
}
' http://0.0.0.0:6385/v1/resource_classes
**as a one-liner (copy/paste)**
::
curl -iX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"service_type": "compute_1","name": "test-chassis", "service_type":"compute","racks":[{"id":1,"links":[{"href":"http://0.0.0.0:6385/v1/racks/1","rel":"self"}]}], "flavors": [{"name" : "x-large", "capacities" : [ { "name": "cpu", "value" : "4", "unit" : "count" }, { "name": "memory", "value" : "8192", "unit" : "MiB" }, { "name": "storage", "value" : "1024", "unit" : "GiB" }]}]}' http://0.0.0.0:6385/v1/resource_classes
update
~~~~~~
To add or remove Racks on a ResourceClass, simply do an update and alter
the racks array attribute accordingly.
::
curl -iX PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -d '
{
"service_type": "compute",
"name": "test-chassis",
"racks":[
{
"id": 1,
"links": [
{
"href":"http://0.0.0.0:6385/v1/racks/1",
"rel":"self"
}
]
}
]
}
' http://0.0.0.0:6385/v1/resource_classes/13``
delete
~~~~~~
::
curl -X DELETE http://0.0.0.0:6385/v1/resource_classes/1`` `back to
top <#index>`_
DataCenter
----------
provision all
~~~~~~~~~~~~~
This will provision the data center according to its description in
Tuskar.
::
curl -XPOST -H 'Content-Type:application/json' -H 'Accept: application/json' http://0.0.0.0:6385/v1/data_centers/
`back to top <#index>`_

35
docs/debugging-with-ipython.rst Normal file
View File

@ -0,0 +1,35 @@
======================
Debugging with iPython
======================
Requirements
------------
::
$ yum install python-ipython
$ cd tuskar
$ find . | grep no-global-site-packages.txt | xargs rm
The 'find' will allow you to import 'global' packages in Tox.
Debugging
---------
Place these two lines in the place you want to debug/drop to shell:
::
import IPython
IPython.embed()
Then start Tuskar as usual and do a GET/POST/etc. Once the code
execution hits these two lines, you will be dropped into the iPython shell
and you will have access to all local variables and the env defined in the
context of where you placed that two lines.
Tweaks
------
`ipythonrc <https://github.com/queezythegreat/settings/tree/master/ipython>`_
-> Colors on console, tab completetion for methods and more ;-)

166
docs/demo-data-script.rst Normal file
View File

@ -0,0 +1,166 @@
================
Demo Data Script
================
This document details the beginning of the walkthrough script for the
Tuskar demo
To use this, clear your database and run the commands below. The result
should be a HEAT template with 6 compute Nodes and 1 non-compute Node.
N.B. The HEAT template does not define availability zones for the nodes.
Therefore the nodes could be deployed onto any rack. This will be fixed
in a subsequent patch.
**Note:** The commands below are useful for experimenting with different
creation scenarios, but the exact data center described therein can also
be created by running:
::
python tools/sample_data/py
from your development environment.
Create Racks
------------
This command creates three Racks. Two Racks are assigned to the
compute Resource Class and contain three Baremetal Nodes each. One Rack
is designated to the non-compute Resource Class and contains 1 Baremetal
Node only.
::
curl -vX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '
{
"subnet": "192.168.1.0/255",
"name": "compute_1",
"capacities": [{
"name": "total_cpu",
"value": "64"
}, {
"name": "total_memory",
"value": "1024"
}],
"nodes": [
{
"id": "nova_bare_metal_1"
},
{
"id": "nova_bare_metal_2"
},
{
"id": "nova_bare_metal_3"
}
],
"slots": 3
}
' http://0.0.0.0:6385/v1/racks
curl -vX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '
{
"subnet": "192.168.2.0/255",
"name": "compute_2",
"capacities": [{
"name": "total_cpu",
"value": "64"
}, {
"name": "total_memory",
"value": "1024"
}],
"nodes": [
{
"id": "nova_bare_metal_4"
},
{
"id": "nova_bare_metal_5"
},
{
"id": "nova_bare_metal_6"
}
],
"slots": 3
}
' http://0.0.0.0:6385/v1/racks
curl -vX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -v -d '
{
"subnet": "192.168.2.0/255",
"name": "non_compute",
"capacities": [{
"name": "total_cpu",
"value": "64"
}, {
"name": "total_memory",
"value": "1024"
}],
"nodes": [
{
"id": "nova_bare_metal_7"
}],
"slots": 3
}
' http://0.0.0.0:6385/v1/racks
Create Resource Classes
-----------------------
This command creates two Resource Classes. The compute Resource Class contains two Racks
and a total of six Nodes. The non-compute Resoure Class contains one Rack and one Node.
::
curl -iX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '
{
"name": "compute-rc",
"service_type":"compute",
"racks": [
{
"id":1,
"links":[{"href":"http://0.0.0.0:6385/v1/racks/1","rel":"self"}]
},
{
"id":2,
"links":[{"href":"http://0.0.0.0:6385/v1/racks/2","rel":"self"}]
}
],
"flavors": [
{ "name" : "x-large",
"capacities" : [
{ "name": "cpu",
"value" : "4",
"unit" : "count" },
{ "name": "memory",
"value" : "8192",
"unit" : "MiB" },
{ "name": "storage",
"value" : "1024",
"unit" : "GiB" }
]
}
]
}
' http://0.0.0.0:6385/v1/resource_classes
curl -iX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '
{
"name": "non-compute-rc",
"service_type":"not_compute",
"racks": [
{
"id":3,
"links":[{"href":"http://0.0.0.0:6385/v1/racks/3","rel":"self"}]
}
]
}
' http://0.0.0.0:6385/v1/resource_classes
Generate HEAT Template
----------------------
This command generates the HEAT template based on the Tuskar description.
::
curl http://0.0.0.0:6385/v1/data_centers

83
docs/heat/using-heat-api-with-boto.rst Normal file
View File

@ -0,0 +1,83 @@
============================
Using the Heat API with Boto
============================
What is Boto?
-------------
Boto is a Python package that provides interfaces to Amazon Web
Services. It supports all the services (including the CloudFormations
API) that are needed by the Heat API.
https://github.com/boto/boto
http://docs.pythonboto.org/en/latest/ref/cloudformation.html
Prerequires
-----------
The latest version of 'boto' will not work(!) because they now use
a newer AWS signature (v2) that is not (yet) supported by Heat. The
2.4.x version of 'boto' will not work as well, because it lacks support
for setting the 'host' for the CloudFormations server. However, you can use
``pip`` to install the right version (and we can add the version to the tox
environment):
``$ pip install "boto==2.5.2"``
Configuration
-------------
Boto use the ``~/.boto`` config file to store settings. I'm pretty much
sure we can override this location and store the file in
``tuskar/etc/boto.conf``. But for testing, just use ``~/.boto``:
::
[Boto]
cfn_region_name = heat
cfn_region_endpoint = HEAT_SERVER_HOSTNAME
debug = True
is_secure = False
[Credentials]
aws_access_key_id = EC2_KEY
aws_secret_access_key = EC2_SECRET
The 'HEAT\_SERVER\_HOSTNAME' is the domain name or IP address of the
Heat API server (without 'http' !). The credentials must be generated on
the Heat server:
::
$ source /root/keystonerc_admin
$ keystone ec2-credentials-create
+-----------+----------------------------------+
| Property | Value |
+-----------+----------------------------------+
| access | EC_KEY |
| secret | EC2_SECRET |
| tenant_id | 3661d05ad41e493fbcdec6826b9a7ba3 |
| user_id | 4b7f47864e4948aaa16fdbcf774f8358 |
+-----------+----------------------------------+
Note the ``ec2-credentials-create`` command will use the current
keystone user\_id (OS\_USERNAME=admin in keystonerc\_admin), if you want
to create credentials for other user, you need to change the
``keystonerc_admin`` file.
Usage
-----
Listing Stacks
~~~~~~~~~~~~~~
::
from boto.cloudformation import CloudFormationConnection
# FIXME: The 'port' and 'path' should be stored in config file...
conn = CloudFormationConnection(port=8000, path='/v1')
print conn.list\_stacks()

12
docs/index.rst
View File

@ -27,7 +27,7 @@ demo! <https://www.youtube.com/watch?v=VEY035-Lyzo>`_
- *TODO* feature examples
- *TODO* link to high-level portion of FAQ
- `Recommended
reading <https://github.com/tuskar/tuskar/wiki/Recommended-reading>`_
reading <https://github.com/tuskar/tuskar/blob/master/docs/recommended-reading.rst>`_
Related Projects
----------------
@ -50,9 +50,9 @@ Install and Contribute
- `Contributing
Guide <https://github.com/tuskar/tuskar/blob/master/CONTRIBUTING.rst>`_
- `Debugging with
iPython <https://github.com/tuskar/tuskar/wiki/Debugging-with-iPython>`_
iPython <https://github.com/tuskar/tuskar/blob/master/docs/debugging-with-ipython.rst>`_
- `Demo Data
Script <https://github.com/tuskar/tuskar/wiki/Demo-Data-Script>`_
Script <https://github.com/tuskar/tuskar/blob/master/docs/demo-data-script.rst>`_
API
---
@ -60,16 +60,16 @@ API
- `API
Information <https://github.com/tuskar/tuskar/blob/master/docs/api/api.md>`_
- `cURL
commands <https://github.com/tuskar/tuskar/wiki/cURL-commands>`_
Commands <https://github.com/tuskar/tuskar/blob/master/docs/api/curl.rst>`_
- `Resource Class Demo
Script <https://github.com/tuskar/tuskar/wiki/Resource-Class-Demo-Script>`_
Script <https://github.com/tuskar/tuskar/blob/master/docs/resource-class-demo-script.rst>`_
(uses cURL)
HEAT Integration
----------------
- `Using Heat API with
Boto <https://github.com/tuskar/tuskar/wiki/Using-Heat-API-with-Boto>`_
Boto <https://github.com/tuskar/tuskar/blob/master/docs/heat/using-heat-api-with-boto.rst>`_
- *TODO* How HEAT update works
- *TODO* Generation of the HEAT template

26
docs/recommended-reading.rst Normal file
View File

@ -0,0 +1,26 @@
===================
Recommended Reading
===================
Relevant OpenStack Projects
---------------------------
- `nova <https://github.com/openstack/nova>`_
- `ceilometer <https://github.com/openstack/ceilometer>`_
- `oslo-incubator <https://github.com/openstack/oslo-incubator>`_
- `oslo.config <https://github.com/openstack/oslo.config>`_ This is a
library for parsing configuration files and command line arguments.
It is maintained by Mark McLoughlin.
- `hacking <https://github.com/openstack-dev/hacking>`_ This enforces
openstack community standards, described
`here <https://github.com/openstack-dev/hacking/blob/master/HACKING.rst>`_.
General Python/Frameworks
-------------------------
- `dive into python <http://www.diveintopython.net>`_
- `pecan <http://pecan.readthedocs.org/en/latest/>`_
- `sqlalchemy <http://docs.sqlalchemy.org/en/rel_0_8/>`_
- `style guide <http://www.python.org/dev/peps/pep-0008/>`_ This guide
is the baseline for 'hacking' above.

94
docs/resource-class-demo-script.rst Normal file
View File

@ -0,0 +1,94 @@
==========================
Resource Class Demo Script
==========================
Get a Resource Class
--------------------
::
curl -H 'Accept: application/json' http://0.0.0.0:6385/v1/resource\_classes/1
{
"service\_type": "compute",
"racks": [],
"id": 1,
"links": [{
"href": "http://0.0.0.0:6385/v1/resource\_classes/1",
"rel": "self"
}],
"name": "test-chassis"
}
Get the Resource Class Collection
---------------------------------
::
curl -H 'Accept: application/json' http://0.0.0.0:6385/v1/resource\_classes/
Create a Resource Class with a Rack
-----------------------------------
::
curl -iX POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '
{
"service_type": "compute",
"name": "test-chassis",
"racks":[
{
"id": 1,
"links": [
{
"href":"http://0.0.0.0:6385/v1/racks/1",
"rel":"self"
}
]
}
]
}
' http://0.0.0.0:6385/v1/resource_classes``
Update the Racks on a Resource Class (Remove Racks)
---------------------------------------------------
::
curl -iX PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -d '
{
"service_type": "compute",
"name": "test-chassis",
"racks":[]
}
' http://0.0.0.0:6385/v1/resource_classes/13``
Update the Racks on a Resource Class (Add a Rack)
-------------------------------------------------
::
curl -iX PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -d '
{
"service_type": "compute",
"name": "test-chassis",
"racks":[
{
"id": 2,
"links": [
{
"href":"http://0.0.0.0:6385/v1/racks/2",
"rel":"self"
}
]
}
]
}
' http://0.0.0.0:6385/v1/resource_classes/13``
Delete a Resource Class
-----------------------
::
curl -iX DELETE -H 'Accept: application/json' http://0.0.0.0:6385/v1/resource_classes/13