Improve documentation

Improves README and inline docs, comments

README.markdown

@@ -1,39 +1,38 @@
 # Disclaimer #
 
-This is not ready to be used.
-
 This is pre-beta code that is actively being developed.
 
-It is currently being developed against swift trunk.
+Although the code is in a functional state, there is currently
+no guarentees about the interfaces that it provides.
 
 I am actively seeking users who understand that this code
 is in a pre-alpha state. Feel free to contact me (Dan Bode)
-at dan < at > puppetlabs <dot> com or bodepd < on > freenode.
+at dan@puppetlabs.com or bodepd<on>freenode.
 
 Any feedback greatly appreciated.
 
-# Limitations #
+# Use Cases #
 
-* Only been tested for a single node swift install
+* Tested for a single node swift install
     http://swift.openstack.org/development_saio.html
 
+* Tested for multi-node swift install
+   http://swift.openstack.org/howto_installmultinode.html
+
 * Only been tested with tempauth
 
 # Dependencies: #
 
 * Only tested on Ubuntu Natty
-* Only tested against Puppet 2.7.9
-* Only verified with Swift 1.4.6
+* Only tested against Puppet 2.7.10
+* Only verified with Swift 1.4.7
 
 # module Dependencies #
 
-* https://github.com/bodepd/puppet-ssh
-    (this should actaully depend on https://github.com/saz/puppet-ssh
-     and can when pull request https://github.com/saz/puppet-ssh/pull/1
-     is merged)
-* https://github.com/bodepd/puppet-rsync
-    (there is a pull request to merge this into the parent repo:
-    https://github.com/bodepd/puppet-rsync)
+This is known to work with master from the following github repos:
+
+* https://github.com/saz/puppet-ssh
+* https://github.com/puppetlabs/puppetlabs-rsync
 * https://github.com/saz/puppet-memcached
 * https://github.com/puppetlabs/puppetlabs-stdlib
 
@@ -63,7 +62,7 @@ proxy server
       # specifies that account should be automatically created
       # this should be set to true when tempauth is used
       account_autocreate = true,
-      #proxy_local_net_ip = '127.0.0.1',
+      proxy_local_net_ip = $ipaddress_eth1,
       #proxy_port = '11211',
       # auth type defaults to tempauth - this is the
       # only auth that has been tested
@@ -73,25 +72,28 @@ proxy server
 ## swift::storage ##
 
 class that sets up all of the configuration and dependencies
-for swift storage instances
+for swift storage server instances
 
     class { 'swift::storage':
       # address that swift should bind to
-      storage_local_net_ip => '127.0.0.1'
+      storage_local_net_ip => $ipaddress_eth1,
+      devices              => '/srv/node'
     }
 
-## swift::storage::device ##
+## swift::storage::server ##
 
-defined resource type that can be used to
-indicate a specific device to be managed
+Defined resource type that can be used to
+create a swift storage server instance. In general, you do
+not need to explicity specify your server instances (as the
+swift::storage::class will create them for you)
 
 This will configure an rsync server instance
-and swift storage instance to manage the device (which
-basically maps port to device)
+and swift storage instance to manage the all devices in
+the devices directory.
 
-    # the title for this device is the port where it
+    # the title for this server and the port where it
     # will be hosted
-    swift::storage::device { '6010':
+    swift::storage::server { '6010':
       # the type of device (account/object/container)
       type => 'object',
       # directory where device is mounted
@@ -125,26 +127,23 @@ a four digit port number :60[digit][role] (object = 0, container = 1, account =
 
 ## swift::ringbuiler ##
 
-class that knows how to build rings. This only exists as a vague idea
+class that knows how to build rings.
 
-the ring building will like be built as a combination of native types
-(for adding the drives) and defined types for rebalancing
+Creates the initial rings, collects any exported resources,
+and rebalances the ring if it is updated.
+
+      class { 'swift::ringbuilder':
+        part_power     => '18',
+        replicas       => '3',
+        min_part_hours => '1',
+      }
 
 # Example #
 
 For an example of how to use this module to build out a single node
-swift cluster, you can try running puppet apply examples/site.pp
-(feel free to look at the code to see how to use this module)
+swift cluster, you can have a look at examples/all.pp
 
-There are a few known issues with this code:
-
-* for some reason the ringbuilding script does not run
-    after the manifest fails, you still need to login
-    and run bash /etc/swift/ringbuilder.sh and start swift-proxy
-* once swift is running, you can test the swift instance with the
-    ruby script stored in files/swift_tester.rb
-
-This example can be used as follows:
+This example can be used as follows:`
 
   # set up pre-reqs
   puppet apply examples/pre.pp
@@ -152,6 +151,20 @@ This example can be used as follows:
   # install all swift components on a single node
   puppet apply examples/all.pp
 
+For an example of how to use this module to build out a multi node
+swift cluster, you can have a look at examples/multi.pp
+
+This example assumes that a puppetmaster already exists and is
+resolvable as puppetmaster.
+
+This example can be used as follows:`
+
+  # set up pre-reqs
+  puppet apply examples/pre.pp
+
+  # install all swift components on a single node
+  puppet apply examples/all.pp --certname my_role
+
 # Verifying installation #
 
 This module also comes with a simple Ruby script that validates

examples/multi.pp

@@ -140,6 +140,9 @@ class role_swift_storage inherits role_swift {
     require      => Class['swift'],
   }
 
+  # these exported resources write ring config
+  # resources into the database so that they can be
+  # consumed by the ringbuilder role
   @@ring_object_device { "${swift_local_net_ip}:6000":
     zone        => $swift_zone,
     device_name => 1,

manifests/init.pp

@@ -4,11 +4,11 @@
 # [*swift_hash_suffix*] string of text to be used
 # as a salt when hashing to determine mappings in the ring.
 # This file should be the same on every node in the cluster.
+# [*package_ensure*] The ensure state for the swift package.
+#   Optional. Defaults to present.
 #
 # [*swift_ssh_key*] NOT YET IMPLEMENTED. I am not entirely sure what
 #  this key is intended to be used for.
-# [*package_ensure*] The ensure state for the swift package.
-#   Optional. Defaults to present.
 #
 # == Dependencies
 #

manifests/ringbuilder.pp

@@ -1,14 +1,15 @@
 # Used to configure nodes that are responsible for managing swift rings.
-# Rings are used to make decitions about how to map objects in the cluster
+# Rings are used to make decicions about how to map objects in the cluster
 #
 # Specifies the following relationship:
 #  Rings shoudl be created before any devices are added to them
 #  Rings should be rebalanced if anything changes
 # == Parameters
 #  # TODO - I need to review the ringbuilder docs
-#  [*part_power*]
-#  [*replicas*]
-#  [*min_part_hours*]
+#  [*part_power*] The total number of partitions that should exist in the ring.
+#    This is expressed as a power of 2.
+#  [*replicas*] Numer of replicas that should be maintained of each stored object.
+#  [*min_part_hours*] Minimum amount of time before partitions can be moved.
 #
 # == Dependencies
 #

manifests/storage.pp

@@ -1,11 +1,19 @@
-# Performs all global configuration required
-# for creating a swift storage node.
+#
+#  Configures a swift storage node to host servers for object,
+#  container, and accounts.
+#
 #  Includes:
 #    installing an rsync server
 #    installs storeage packages (object,account,containers)
 # == Parameters
-#  [*storeage_local_net_ip*]
-#  [*package_ensure*]
+#  [*storeage_local_net_ip*] ip address that the swift servers should
+#    bind to. Optional. Defaults to 127.0.0.1 .
+#    TODO - should this default to 0.0.0.0 ?
+#  [*package_ensure*] The desired ensure state of the swift storage packages.
+#    Optional. Defaults to present.
+#  [*devices*] The path where the managed volumes can be found.
+#    This assumes that all servers use the same path.
+#    Optional. Defaults to /srv/node/
 #  [*object_port*] Port where object storage server should be hosted.
 #    Optional. Defaults to 6000.
 #  [*container_port*] Port where the container storage server should be hosted.
@@ -115,6 +123,7 @@ class swift::storage(
     provider  => 'upstart',
   }
 
+  # TODO this should be removed when the upstart packages are fixed.
   define upstart() {
     file { "/etc/init/swift-${name}.conf":
       mode   => '0644',