merge

3 files changed, 97 insertions, 7 deletions

diff --git a/doc/source/cloudpipe.rst b/doc/source/cloudpipe.rst
index f2e7cb85a..952a75351 100644
--- a/doc/source/cloudpipe.rst
+++ b/doc/source/cloudpipe.rst
@@ -1,6 +1,6 @@
 ..
       Copyright 2010 United States Government as represented by the
-      Administrator of the National Aeronautics and Space Administration. 
+      Administrator of the National Aeronautics and Space Administration.
       All Rights Reserved.
 
       Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -15,13 +15,63 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-Cloudpipe Programmer Guide
-==========================
 
-The :mod:`pipelib` Module
--------------------------
+.. _cloudpipe:
+
+Cloudpipe
+=========
+
+Cloudpipe is a method for connecting end users to their project insnances in vlan mode.
+
+Overview
+--------
+
+The support code for cloudpipe implements admin commands (via nova-manage) to automatically create a vm for a project that allows users to vpn into the private network of their project. Access to this vpn is provided through a public port on the network host for the project.  This allows users to have free access to the virtual machines in their project without exposing those machines to the public internet.
+
+Cloudpipe Image
+---------------
+
+The cloudpipe image is basically just a linux instance with openvpn installed.  It needs a simple script to grab user data from the metadata server, b64 decode it into a zip file, and run the autorun.sh script from inside the zip.  The autorun script will configure and run openvpn to run using the data from nova.
+
+It is also useful to have a cron script that will periodically redownload the metadata and copy the new crl.  This will keep revoked users from connecting and will disconnect any users that are connected with revoked certificates when their connection is renegotiated (every hour).
+
+Cloudpipe Launch
+----------------
+
+When you use nova-manage to launch a cloudpipe for a user, it goes through the following process:
+
+#. creates a keypair called <project_id>-vpn and saves it in the keys directory
+#. creates a security group <project_id>-vpn and opens up 1194 and icmp
+#. creates a cert and private key for the vpn instance and saves it in the CA/projects/<project_id>/ directory
+#. zips up the info and puts it b64 encoded as user data
+#. launches an m1.tiny instance with the above settings using the flag-specified vpn image
+
+Vpn Access
+----------
+
+In vlan networking mode, the second ip in each private network is reserved for the cloudpipe instance.  This gives a consistent ip to the instance so that nova-network can create forwarding rules for access from the outside world.  The network for each project is given a specific high-numbered port on the public ip of the network host.  This port is automatically forwarded to 1194 on the vpn instance.
+
+If specific high numbered ports do not work for your users, you can always allocate and associate a public ip to the instance, and then change the vpn_public_ip and vpn_public_port in the database.  This will be turned into a nova-manage command or a flag soon.
+
+
+Certificates and Revocation
+---------------------------
+
+If the use_project_ca flag is set (required to for cloudpipes to work securely), then each project has its own ca.  This ca is used to sign the certificate for the vpn, and is also passed to the user for bundling images.  When a certificate is revoked using nova-manage, a new Certificate Revocation List (crl) is generated.  As long as cloudpipe has an updated crl, it will block revoked users from connecting to the vpn.
+
+The :mod:`cloudpipe` Module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: nova.cloudpipe.pipelib
     :members:
     :undoc-members:
     :show-inheritance:
+
+The :mod:`crypto` Module
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: nova.crypto
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
diff --git a/doc/source/concepts.and.introduction.rst b/doc/source/concepts.and.introduction.rst
index 29b8f064a..d2ab6f14b 100644
--- a/doc/source/concepts.and.introduction.rst
+++ b/doc/source/concepts.and.introduction.rst
@@ -129,7 +129,7 @@ This is similar to the flat mode, in that all instances are attached to the same
 VLAN DHCP Mode
 ~~~~~~~~~~~~~~
 
-This is the default networking mode and supports the most features.  For multiple machine installation, it requires a switch that supports host-managed vlan tagging.  In this mode, nova will create a vlan and bridge for each project.  The project gets a range of private ips that are only accessible from inside the vlan.  In order for a user to access the instances in their project, a special vpn instance (code name cloudpipe) needs to be created.  Nova generates a certificate and key for the userto access the vpn and starts the vpn automatically.
+This is the default networking mode and supports the most features.  For multiple machine installation, it requires a switch that supports host-managed vlan tagging.  In this mode, nova will create a vlan and bridge for each project.  The project gets a range of private ips that are only accessible from inside the vlan.  In order for a user to access the instances in their project, a special vpn instance (code named :ref:`cloudpipe <cloudpipe>`) needs to be created.  Nova generates a certificate and key for the userto access the vpn and starts the vpn automatically. More information on cloudpipe can be found :ref:`here <cloudpipe>`.
 
 The following diagram illustrates how the communication that occurs between the vlan (the dashed box) and the public internet (represented by the two clouds)
 
diff --git a/doc/source/services.rst b/doc/source/services.rst
index 607f5974b..517a51901 100644
--- a/doc/source/services.rst
+++ b/doc/source/services.rst
@@ -20,13 +20,53 @@
 Services Managers and Drivers
 =============================
 
-Describe division of responsibilities for each component.
+The responsibilities of Services, Managers, and Drivers, can be a bit confusing to people that are new to nova.  This document attempts to outline the division of responsibilities to make understanding the system a little bit easier.
+
+Currently, Managers and Drivers are specified by flags and loaded using utils.load_object().  This method allows for them to be implemented as singletons, classes, modules or objects.  As long as the path specified by the flag leads to an object (or a callable that returns an object) that responds to getattr, it should work as a manager or driver.
 
 Service
 -------
 
+A service is a very thin wrapper around a Manager object.  It exposes the manager's public methods to other components of the system via rpc.  It will report state periodically to the database and is responsible for initiating any periodic tasts that need to be executed on a given host.
+
+The :mod:`service` Module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: nova.service
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 Manager
 -------
 
+Managers are responsible for a certain aspect of the sytem.  It is a logical grouping of code relating to a portion of the system.  In general other components should be using the manager to make changes to the components that it is responsible for.
+
+For example, other components that need to deal with volumes in some way, should do so by calling methods on the VolumeManager instead of directly changing fields in the database.  This allows us to keep all of the code relating to volumes in the same place.
+
+We have adopted a basic strategy of Smart managers and dumb data, which means rather than attaching methods to data objects, components should call manager methods that act on the data.
+
+Methods on managers that can be executed locally should be called directly. If a particular method must execute on a remote host, this should be done via rpc to the service that wraps the manager
+
+Managers should be responsible for most of the db access, and non-implementation specific data.  Anything implementation specific that can't be generalized should be done by the Driver.
+
+In general, we prefer to have one manager with multiple drivers for different implementations, but sometimes it makes sense to have multiple managers.  You can think of it this way: Abstract different overall strategies at the manager level(FlatNetwork vs VlanNetwork), and different implementations at the driver level(LinuxNetDriver vs CiscoNetDriver).
+
+Managers will often provide methods for initial setup of a host or periodic tasksto a wrapping service.
+
+The :mod:`manager` Module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: nova.manager
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 Driver
 ------
+
+A manager will generally load a driver for some of its tasks. The driver is responsible for specific implementation details.  Anything running shell commands on a host, or dealing with other non-python code should probably be happening in a driver.
+
+Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point.
+
+It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement.