diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index edf9fa5b..992d7576 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -24,7 +24,7 @@ the following checklist: 2. Update the API docs (if needed) 3. Update the tests (if needed) 4. Update - `cURL commands `_ + `cURL commands `_ page (if needed) Getting Started diff --git a/docs/api/api.md b/docs/api/api.md index 822f27ca..01c8dc19 100644 --- a/docs/api/api.md +++ b/docs/api/api.md @@ -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: * [ResourceClass](#resource_class) diff --git a/docs/api/curl.rst b/docs/api/curl.rst new file mode 100644 index 00000000..7334bd52 --- /dev/null +++ b/docs/api/curl.rst @@ -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>`_ diff --git a/docs/debugging-with-ipython.rst b/docs/debugging-with-ipython.rst new file mode 100644 index 00000000..e9b417e4 --- /dev/null +++ b/docs/debugging-with-ipython.rst @@ -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 `_ +-> Colors on console, tab completetion for methods and more ;-) diff --git a/docs/demo-data-script.rst b/docs/demo-data-script.rst new file mode 100644 index 00000000..6893d8fd --- /dev/null +++ b/docs/demo-data-script.rst @@ -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 diff --git a/docs/heat/using-heat-api-with-boto.rst b/docs/heat/using-heat-api-with-boto.rst new file mode 100644 index 00000000..331e5c37 --- /dev/null +++ b/docs/heat/using-heat-api-with-boto.rst @@ -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() diff --git a/docs/index.rst b/docs/index.rst index 75a55bc2..0b2e78fb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,7 +27,7 @@ demo! `_ - *TODO* feature examples - *TODO* link to high-level portion of FAQ - `Recommended - reading `_ + reading `_ Related Projects ---------------- @@ -50,9 +50,9 @@ Install and Contribute - `Contributing Guide `_ - `Debugging with - iPython `_ + iPython `_ - `Demo Data - Script `_ + Script `_ API --- @@ -60,16 +60,16 @@ API - `API Information `_ - `cURL - commands `_ + Commands `_ - `Resource Class Demo - Script `_ + Script `_ (uses cURL) HEAT Integration ---------------- - `Using Heat API with - Boto `_ + Boto `_ - *TODO* How HEAT update works - *TODO* Generation of the HEAT template diff --git a/docs/recommended-reading.rst b/docs/recommended-reading.rst new file mode 100644 index 00000000..9e686b2c --- /dev/null +++ b/docs/recommended-reading.rst @@ -0,0 +1,26 @@ +=================== +Recommended Reading +=================== + +Relevant OpenStack Projects +--------------------------- + +- `nova `_ +- `ceilometer `_ +- `oslo-incubator `_ +- `oslo.config `_ This is a + library for parsing configuration files and command line arguments. + It is maintained by Mark McLoughlin. +- `hacking `_ This enforces + openstack community standards, described + `here `_. + +General Python/Frameworks +------------------------- + +- `dive into python `_ +- `pecan `_ +- `sqlalchemy `_ +- `style guide `_ This guide + is the baseline for 'hacking' above. + diff --git a/docs/resource-class-demo-script.rst b/docs/resource-class-demo-script.rst new file mode 100644 index 00000000..f2523401 --- /dev/null +++ b/docs/resource-class-demo-script.rst @@ -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