Adding developer howtos

doc/source/devref/addmethod.openstackapi.rst

@@ -0,0 +1,56 @@
+..
+      Copyright 2010 OpenStack LLC 
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Adding a Method to the OpenStack API
+====================================
+
+The interface is a mostly RESTful API. REST stands for Representational State Transfer and provides an architecture "style" for distributed systems using HTTP for transport. Figure out a way to express your request and response in terms of resources that are being created, modified, read, or destroyed.
+
+Routing
+-------
+
+To map URLs to controllers+actions, OpenStack uses the Routes package, a clone of Rails routes for Python implementations. See http://routes.groovie.org/ fore more information.
+
+URLs are mapped to "action" methods on "controller" classes in nova/api/openstack/__init__/ApiRouter.__init__ .
+
+See http://routes.groovie.org/manual.html for all syntax, but you'll probably just need these two:
+   - mapper.connect() lets you map a single URL to a single action on a controller.
+   - mapper.resource() connects many standard URLs to actions on a controller.
+
+Controllers and actions
+-----------------------
+
+Controllers live in nova/api/openstack, and inherit from nova.wsgi.Controller.
+
+See nova/api/openstack/servers.py for an example.
+
+Action methods take parameters that are sucked out of the URL by mapper.connect() or .resource().  The first two parameters are self and the WebOb request, from which you can get the req.environ, req.body, req.headers, etc.
+
+Serialization
+-------------
+
+Actions return a dictionary, and wsgi.Controller serializes that to JSON or XML based on the request's content-type.
+
+If you define a new controller, you'll need to define a _serialization_metadata attribute on the class, to tell wsgi.Controller how to convert your dictionary to XML.  It needs to know the singular form of any list tag (e.g. <servers> list contains <server> tags) and which dictionary keys are to be XML attributes as opposed to subtags (e.g. <server id="4"/> instead of <server><id>4</id></server>).  
+
+See nova/api/openstack/servers.py for an example.
+
+Faults
+------
+
+If you need to return a non-200, you should
+return faults.Fault(webob.exc.HTTPNotFound())
+replacing the exception as appropriate.

doc/source/devref/development.environment.rst

@@ -15,7 +15,86 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-Setting up a development environment
+Setting Up a Development Environment
 ====================================
 
-.. todo:: write this
+This page describes how to setup a working Python development environment that can be used in developing on OpenStack on Ubuntu or Mac OSX. These instructions assume you're already familiar with bzr and can pull down the code with an existing Launchpad account. Refer to http://wiki.openstack.org/LifeWithBzrAndLaunchpad for additional information.
+
+Linux Systems
+-------------
+
+ '' At present, this section is tested for Nova on Ubuntu 10.10-64. Feel free to add notes and change according to your experiences or operating system.''
+
+Bring down the Nova source with bzr, then:
+::
+  cd <your_src_dir>/nova
+  sudo apt-get install python-dev swig libssl-dev python-pip
+  sudo easy_install nose
+  pip install virtualenv
+  python tools/install_venv.py
+
+If all goes well, you should get a message something like this:
+
+ ::
+ Nova development environment setup is complete.
+
+Nova development uses virtualenv to track and manage Python dependencies while in development and testing.
+
+To activate the Nova virtualenv for the extent of your current shell session
+ you can run:
+
+ ::
+ $ source .nova-venv/bin/activate 
+
+ Or, if you prefer, you can run commands in the virtualenv on a case by case
+ basis by running:
+ ::
+ $ tools/with_venv.sh <your command>
+
+ Also, make test will automatically use the virtualenv.
+
+If you don't want to create a virtualenv every time you branch (which takes a while as long as we have the large Twisted project as a dependency) you can reuse a single virtualenv for all branches.
+
+   1. If you don't have a nova/ directory containing trunk/ and other branches, do so now.
+   2. Go into nova/trunk and install a virtualenv.
+   3. Move it up a level: mv nova/trunk/.nova-venv nova/.nova-venv
+   4. Symlink the ../nova/.nova-venv directory from your branch 
+  :: 
+  ~/openstack/nova/my_branch$ ln -s ../.nova-venv .nova-venv
+
+This works with run_tests.sh and nosetests -w nova/tests/api
+
+MacOSX Systems
+--------------
+
+First, install Virtual Env, which creates an isolated "standalone" Python environment.
+
+  ::
+  sudo easy_install virtualenv
+
+
+Initial Code Setup:
+  ::
+  bzr branch lp:nova
+  cd nova
+  python tools/install_venv.py
+  source .nova_venv/bin/activate
+  pip install pep8 # submitting patch so that Nova has pep8 and pylint in PIP requirements file
+  pip install pylint
+
+If you have installed OpenSSL 1.0.0a on MacOS, which can happen when installing a MacPorts package for OpenSSL, you will see an error when running nova.tests.auth_unittest.AuthTestCase.test_209_can_generate_x509. The version that functions correctly is OpenSSL 0.9.8l 5, installed with MacOS 10.6 as a base element. 
+
+  :: 
+  cd nova
+  bzr pull # get the latest stuff...
+  source .nova_venv/bin/activate
+  ./run_tests.sh
+
+#... do cleaning work or hack hack hack with a branched named cleaning
+
+bzr push lp:~launchpaduserid/nova/cleaning
+
+
+To submit the merge/patch:
+ * navigate to https://code.launchpad.net/~launchpaduserid/nova/cleaning
+ * click on the link "Propose for merging"

doc/source/devref/index.rst

@@ -23,8 +23,12 @@ In this section you will find information on Nova's lower level programming APIs
 
 Programming HowTos and Tutorials
 --------------------------------
+.. toctree::
+    :maxdepth: 3
+    
+    development.environment
+    addmethod.openstackapi
 
-.. todo:: Add some programming howtos and tuts
 
 Programming Concepts
 --------------------

doc/source/devref/rabbit.rst

@@ -32,7 +32,7 @@ Nova (Austin release) uses both direct and topic-based exchanges. The architectu
 Nova implements RPC (both request+response, and one-way, respectively nicknamed 'rpc.call' and 'rpc.cast') over AMQP by providing an adapter class which take cares of marshalling and unmarshalling of messages into function calls. Each Nova service (for example Compute, Volume, etc.) create two queues at the initialization time, one which accepts messages with routing keys 'NODE-TYPE.NODE-ID' (for example compute.hostname) and another, which accepts messages with routing keys as generic 'NODE-TYPE' (for example compute). The former is used specifically when Nova-API needs to redirect commands to a specific node like 'euca-terminate instance'. In this case, only the  compute node whose host's hypervisor is running the virtual machine can kill the instance. The API acts as a consumer when RPC calls are request/response, otherwise is acts as publisher only. 
 
 Nova RPC Mappings
-=================
+-----------------
 
 The figure below shows the internals of a RabbitMQ node when a single instance is deployed and shared in an OpenStack cloud. Every Nova component connects to the RabbitMQ instance and, depending on its personality (for example a compute node or a network node), may use the queue either as an Invoker (such as API or Scheduler) or a Worker (such as Compute, Volume or Network). Invokers and Workers do not actually exist in the Nova object model, but we are going to use them as an abstraction for sake of clarity. An Invoker is a component that sends messages in the queuing system via two operations: 1) rpc.call and ii) rpc.cast; a Worker is a component that receives messages from the queuing system and reply accordingly to rcp.call operations. 
 
@@ -52,7 +52,7 @@ Figure 2 shows the following internal elements:
 ..
 
 RPC Calls
-=========
+---------
 
 The diagram below shows the message flow during an rp.call operation: 
 
@@ -67,7 +67,7 @@ The diagram below shows the message flow during an rp.call operation:
 ..
 
 RPC Casts
-=========
+---------
 
 The diagram below the message flow during an rp.cast operation: 
 
@@ -80,7 +80,7 @@ The diagram below the message flow during an rp.cast operation:
 ..
 
 RabbitMQ Load
-=============
+-------------
 
 At any given time the load of a RabbitMQ node is function of the following parameters:
 
@@ -107,7 +107,7 @@ The figure below shows the status of the RabbitMQ node after Nova components' bo
 ..
 
 RabbitMQ Gotchas
-================
+----------------
 
 Nova uses Carrot to connect to the RabbitMQ environment. Carrot is a Python library that in turn uses AMQPLib, a library that implements the standard AMQP 0.8 at the time of writing. When using Carrot, Invokers and Workers need the following parameters in order to instantiate a Connection object that connects to the RabbitMQ server (please note that most of the following material can be also found in the Carrot documentation; it has been summarized and revised here for sake of clarity):