spiceweasel 1.2.0 → 2.0.0

data/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+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.

data/README.md

@@ -1,176 +1,51 @@
-Description
-===========
-Spiceweasel is a command-line tool for batch loading Chef infrastructure from a file. It provides a simple syntax in either JSON or YAML for describing and deploying infrastructure in order with the Chef command-line tool `knife`. This manifest may be bundled with a Chef repository to deploy the infrastructure contained within the repository and validate that the components listed are all present.
+# Description #
 
-The `examples` directory provides example manifests based on the Quick Starts provided at [http://help.opscode.com/kb/otherhelp](http://help.opscode.com/kb/otherhelp).
+Spiceweasel is a command-line tool for batch loading Chef infrastructure from a file. It provides a simple syntax in either JSON or YAML for describing and deploying infrastructure in order with the Chef command-line tool `knife`. This manifest may be bundled with a Chef repository to deploy the infrastructure contained within the repository and validate that the components listed are all present.
 
-The [https://github.com/mattray/vbacd-repo](https://github.com/mattray/vbacd-repo) provides a working example for bootstrapping a Chef repository with Spiceweasel.
+The `examples` directory provides example manifests based on the Quick Starts provided at http://help.opscode.com/kb/otherhelp. The https://github.com/mattray/vbacd-repo provides a working example for bootstrapping a Chef repository with Spiceweasel.
 
 The [CHANGELOG.md](https://github.com/mattray/spiceweasel/blob/master/CHANGELOG.md) covers current, previous and future development milestones and contains the features backlog.
 
-Requirements
-============
-Spiceweasel currently depends on `knife` to run commands for it, but does not explicitly depend on the `chef` gem yet. Infrastructure files must either end in .json or .yml to be processed.
+# Requirements #
 
-Written and tested initially with Chef 0.9.12 (should still work) and continuing development with the 10. series. It is tested with Ruby 1.8.7 and 1.9.2.
+Spiceweasel currently depends on `knife` to run commands for it, and requires the `chef` gem for validating cookbook metadata. Infrastructure files must either end in `.json` or `.yml` to be processed.
 
-File Syntax
-===========
-The syntax for the spiceweasel file may be either JSON or YAML format of Chef primitives describing what is to be instantiated. Below or 2 examples describing the same infrastructure.
+Written and tested initially with Chef 0.9.12 (may still work) and continuing development with the 10.x series. It is tested with Ruby 1.8.7 and 1.9.2.
 
-YAML
-----
-From the `example.yml`:
+# File Syntax #
 
-``` yaml
-cookbooks:
-- apache2:
-- apt:
-    - 1.2.0
-- mysql:
-environments:
-- development:
-- qa:
-- production:
-roles:
-- base:
-- iisserver:
-- monitoring:
-- webserver:
-data bags:
-- users:
-  - alice
-  - bob
-  - chuck
-- data:
-  - "*"
-- passwords:
-  - secret secret_key
-  - mysql
-  - rabbitmq
-nodes:
-- serverA:
-  - role[base]
-  - -i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems
-- serverB serverC:
-  - role[base]
-  - -i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems -E production
-- ec2 3:
-  - role[webserver] recipe[mysql::client]
-  - -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small
-- rackspace 3:
-  - recipe[mysql],role[monitoring]
-  - --image 49 --flavor 2 --node-name rs{{n}}.example.com
-- windows_winrm winboxA:
-  - role[base],role[iisserver]
-  - -x Administrator -P 'super_secret_password'
-- windows_ssh winboxB winboxC:
-  - role[base],role[iisserver]
-  - -x Administrator -P 'super_secret_password'
-```
-
-JSON
-----
-From the `example.json`:
-
-``` json
-{
-    "cookbooks":
-    [
-        {"apache2":[]},
-        {"apt":
-         [
-             "1.2.0"
-         ]
-        },
-        {"mysql":[]}
-    ],
-    "environments":
-    [
-        {"development":[]},
-        {"qa":[]},
-        {"production":[]}
-    ],
-    "roles":
-    [
-        {"base":[]},
-        {"iisserver":[]},
-        {"monitoring":[]},
-        {"webserver":[]}
-    ],
-    "data bags":
-    [
-        {"users":
-         [
-             "alice",
-             "bob",
-             "chuck"
-         ]
-        },
-        {"data":
-         [
-             "*"
-         ]
-        },
-        {"passwords":
-         [
-             "secret secret_key",
-             "mysql",
-             "rabbitmq"
-         ]
-        }
-    ],
-    "nodes":
-    [
-        {"serverA":
-         [
-             "role[base]",
-             "-i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems"
-         ]
-        },
-        {"serverB serverC":
-         [
-             "role[base]",
-             "-i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems -E production"
-         ]
-        },
-        {"ec2 3":
-         [
-             "role[webserver] recipe[mysql::client]",
-             "-S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small"
-         ]
-        },
-        {"rackspace 3":
-         [
-             "recipe[mysql],role[monitoring]",
-             "--image 49 --flavor 2 --node-name rs{{n}}.example.com"
-         ]
-        },
-        {"windows_winrm winboxA":
-         [
-             "role[base],role[iisserver]",
-             "-x Administrator -P 'super_secret_password'"
-         ]
-        },
-        {"windows_ssh winboxB winboxC":
-         [
-             "role[base],role[iisserver]",
-             "-x Administrator -P 'super_secret_password'"
-         ]
-        }
-    ]
-}
-```
-
-Cookbooks
----------
-The `cookbooks` section of the manifest currently supports `knife cookbook upload FOO` where `FOO` is the name of the cookbook in the `cookbooks` directory. The default behavior is to download the cookbook as a tarball, untar it and remove the tarball. The `--siteinstall` option will allow for use of `knife cookbook site install` with the cookbook and the creation of a vendor branch if git is the underlying version control. If a version is passed, it is validated against the existing cookbook `metadata.rb` and it must match the `metadata.rb` string exactly. You may pass any additional arguments if necessary. Assuming the apt cookbook was not present, the example YAML snippet
+The syntax for the Spiceweasel file may be either JSON or YAML format of Chef primitives describing what is to be instantiated. Please refer to the [examples/example.json](https://github.com/mattray/spiceweasel/blob/master/examples/example.json) or [examples/example.yml](https://github.com/mattray/spiceweasel/blob/master/examples/example.yml) for examples of the same infrastructure. Each subsection below shows the YAML syntax converted to knife commands.
+
+## Manifest syntax changes in Spiceweasel 2.0 ##
+
+In order to be more explicit and enable a richer set of options, the syntax for the manifests was updated. Rather than depend on the order of arrays for the attributes of cookbooks, data bags and nodes; the attributes are now hashes with keys identifying the features.
+
+### New Cookbooks Syntax ###
+
+The currently supported keys are `version` and `options` and their values are strings.
+
+### New Data Bags Syntax ###
+
+The supported keys are `items` (an array of the data bag items) and `secret` for passing a secret key string.
+
+### New Nodes Syntax ###
+
+The supported keys are `run_list` and `options` and their values are strings.
+
+### New Clusters Syntax ###
+
+Clusters support is completely new, please refer to the Cluster section for documentation.
+
+## Cookbooks ##
+
+The `cookbooks` section of the manifest currently supports `knife cookbook upload FOO` where `FOO` is the name of the cookbook in the `cookbooks` directory. The default behavior is to download the cookbook as a tarball, untar it and remove the tarball. The `--siteinstall` option will allow for use of `knife cookbook site install` with the cookbook and the creation of a vendor branch if git is the underlying version control. Validation is done to ensure the cookbook matches the name (and version if given) in the metadata and that any cookbook dependencies are listed in the manifest. You may pass any additional options if necessary. Assuming the apt cookbook was not present, the example YAML snippet
 
 ``` yaml
 cookbooks:
 - apache2:
 - apt:
-  - 1.2.0
+    version: 1.2.0
+    options: --freeze
 - mysql:
 ```
 
@@ -181,12 +56,12 @@ knife cookbook upload apache2
 knife cookbook site download apt 1.2.0 --file cookbooks/apt.tgz
 tar -C cookbooks/ -xf cookbooks/apt.tgz
 rm -f cookbooks/apt.tgz
-knife cookbook upload apt
+knife cookbook upload apt --freeze
 knife cookbook upload mysql
 ```
 
-Environments
-------------
+## Environments ##
+
 The `environments` section of the manifest currently supports `knife environment from file FOO` where `FOO` is the name of the environment file ending in `.rb` or `.json` in the `environments` directory. Validation is done to ensure the filename matches the environment and that any cookbooks referenced are listed in the manifest. The example YAML snippet
 
 ``` yaml
@@ -204,13 +79,14 @@ knife environment from file qa.rb
 knife environment from file production.rb
 ```
 
-Roles
------
+## Roles ##
+
 The `roles` section of the manifest currently supports `knife role from file FOO` where `FOO` is the name of the role file ending in `.rb` or `.json` in the `roles` directory. Validation is done to ensure the filename matches the role name and that any cookbooks or roles referenced are listed in the manifest. The example YAML snippet
 
 ``` yaml
 roles:
 - base:
+- iisserver:
 - monitoring:
 - webserver:
 ```
@@ -219,26 +95,30 @@ produces the knife commands
 
 ```
 knife role from file base.rb
+knife role from file iisserver.rb
 knife role from file monitoring.rb
 knife role from file webserver.rb
 ```
 
-Data Bags
----------
-The `data bags` section of the manifest currently creates the data bags listed with `knife data bag create FOO` where `FOO` is the name of the data bag. Individual items may be added to the data bag as part of a JSON or YAML sequence, the assumption is made that they `.json` files and in the proper `data_bags/FOO` directory. You may also pass a wildcard as an entry to load all matching data bags (ie. `"*"`). Encrypted data bags are supported by listing `secret filename` as the first item (where `filename` is the secret key to be used). Validation is done to ensure the JSON is properly formatted, the id matches and any secret keys are in the correct locations. Assuming the presence of `dataA.json` and `dataB.json` in the `data_bags/data` directory, the YAML snippet
+n## Data Bags ##
+
+The `data bags` section of the manifest currently creates the data bags listed with `knife data bag create FOO` where `FOO` is the name of the data bag. Individual items may be added to the data bag as part of a JSON or YAML sequence, the assumption is made that they `.json` files and in the proper `data_bags/FOO` directory. You may also pass a wildcard as an entry to load all matching data bags (ie. `"*"`). Encrypted data bags are supported by using the `secret: secret_key_filename` attribute. Validation is done to ensure the JSON is properly formatted, the id matches and any secret key files are in the correct locations. Assuming the presence of `dataA.json` and `dataB.json` in the `data_bags/data` directory, the YAML snippet
 
 ``` yaml
 data bags:
 - users:
-  - alice
-  - bob
-  - chuck
+    items:
+    - alice
+    - bob
+    - chuck
 - data:
-  - "*"
+    items:
+    - "*"
 - passwords:
-  - secret secret_key
-  - mysql
-  - rabbitmq
+    secret: secret_key_filename
+    items:
+    - mysql
+    - rabbitmq
 ```
 
 produces the knife commands
@@ -252,48 +132,39 @@ knife data bag create data
 knife data bag from file data dataA.json
 knife data bag from file data dataB.json
 knife data bag create passwords
-knife data bag from file passwords mysql.json --secret-file secret_key
-knife data bag from file passwords rabbitmq.json --secret-file secret_key
+knife data bag from file passwords mysql.json --secret-file secret_key_filename
+knife data bag from file passwords rabbitmq.json --secret-file secret_key_filename
 ```
 
-Nodes
------
-The `nodes` section of the manifest bootstraps a node for each entry where the entry is a hostname or provider and count. A shortcut syntax for bulk-creating nodes with various providers where the line starts with the provider and ends with the number of nodes to be provisioned. Windows nodes need to specify either `windows_winrm` or `windows_ssh` depending on the protocol used, followed by the name of the node(s). Each node requires 2 items after it in a sequence. You may also use the `--parallel` flag from the command line, allowing provider commands to run simultaneously for faster deployment. If you want to give your nodes names, simply pass `-N NAME{{n}}` or `--node-name NAME{{n}}` and the `{{n}}` will be substituted by a number (works with or without --parallel).
+## Nodes ##
 
-The first item after the node is the run_list and the second are the CLI options used. The run_list may be space or comma-delimited. Validation is performed on the run_list components to ensure that only cookbooks and roles listed in the manifest are used. Validation on the options ensures that any Environments referenced are also listed. You may specify multiple nodes to have the same configuration by listing them separated by a space. The example YAML snippet
+The `nodes` section of the manifest bootstraps a node for each entry given a hostname or a provider with a count. Windows nodes need to specify either `windows_winrm` or `windows_ssh` depending on the protocol used, followed by the name of the node(s). Each node may have a `run_list` and `options`. The `run_list` may be space or comma-delimited. Validation is performed on the `run_list` components to ensure that only `cookbooks` and `roles` listed in the manifest are used. Validation on the options ensures that any `environments` referenced are also listed. You may specify multiple nodes to have the same configuration by listing them separated by a space. If you want to give your nodes names, simply pass `-N NAME{{n}}` or `--node-name NAME{{n}}` and the `{{n}}` will be substituted by a number. The example YAML snippet
 
 ``` yaml
 nodes:
 - serverA:
-  - role[base]
-  - -i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems
+    run_list: role[base]
+    options: -i ~/.ssh/mray.pem -x user --sudo
 - serverB serverC:
-  - role[base]
-  - -i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems -E production
-- ec2 3:
-  - role[webserver] recipe[mysql::client]
-  - -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small
+    run_list: role[base]
+    options: -i ~/.ssh/mray.pem -x user --sudo -E production
 - rackspace 3:
-  - recipe[mysql],role[monitoring]
-  - --image 49 --flavor 2 --node-name rs{{n}}.example.com
+    run_list: recipe[mysql],role[monitoring]
+    options: --image 49 --flavor 2 -N db{{n}}
 - windows_winrm winboxA:
-  - role[base],role[iisserver]
-  - -x Administrator -P 'super_secret_password'
+    run_list: role[base],role[iisserver]
+    options: -x Administrator -P 'super_secret_password'
 - windows_ssh winboxB winboxC:
-  - role[base],role[iisserver]
-  - -x Administrator -P 'super_secret_password'
+    run_list: role[base],role[iisserver]
+    options: -x Administrator -P 'super_secret_password'
 ```
 
 produces the knife commands
 
 ```
-knife bootstrap serverA -i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems -r 'role[base]'
-knife bootstrap serverB -i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems -E production -r 'role[base]'
-knife bootstrap serverC -i ~/.ssh/mray.pem -x user --sudo -d ubuntu10.04-gems -E production -r 'role[base]'
-knife ec2 server create -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small -r 'role[webserver],recipe[mysql::client]'
-knife ec2 server create -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small -r 'role[webserver],recipe[mysql::client]'
-knife ec2 server create -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small -r 'role[webserver],recipe[mysql::client]'
-knife ec2 server create -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small -r 'role[webserver],recipe[mysql::client]'
+knife bootstrap serverA -i ~/.ssh/mray.pem -x user --sudo -r 'role[base]'
+knife bootstrap serverB -i ~/.ssh/mray.pem -x user --sudo -E production -r 'role[base]'
+knife bootstrap serverC -i ~/.ssh/mray.pem -x user --sudo -E production -r 'role[base]'
 knife rackspace server create --image 49 --flavor 2 --node-name rs1.example.com -r 'recipe[mysql],role[monitoring]'
 knife rackspace server create --image 49 --flavor 2 --node-name rs2.example.com -r 'recipe[mysql],role[monitoring]'
 knife rackspace server create --image 49 --flavor 2 --node-name rs3.example.com -r 'recipe[mysql],role[monitoring]'
@@ -302,7 +173,7 @@ knife bootstrap windows ssh winboxB -x Administrator -P 'super_secret_password'
 knife bootstrap windows ssh winboxC -x Administrator -P 'super_secret_password' -r 'role[base],role[iisserver]'
 ```
 
-Using `--parallel` with the following block and the `-N webserver{{n}}`
+You may also use the `--parallel` flag from the command line, allowing provider commands to run simultaneously for faster deployment. Using `--parallel` with the following block and the `-N webserver{{n}}`:
 
 ``` yaml
 nodes:
@@ -319,8 +190,34 @@ seq 3 | parallel -j 0 -v "knife ec2 server create -S mray -i ~/.ssh/mray.pem -x
 
 which generates nodes named "webserver1", "webserver2" and "webserver3".
 
-Extract
-=======
+## Clusters ##
+
+Clusters are not a type supported by Chef, this is a logical construct added by Spiceweasel to enable managing sets of infrastructure together. The `clusters` section is a special case of `nodes`, where each member of the named cluster in the manifest will be tagged to ensure that the entire cluster may be created in sync (refresh and delete coming soon). The node syntax is the same as that under `nodes`, the only addition is the cluster name.
+
+```
+clusters:
+- amazon:
+  - ec2 1:
+      run_list: role[mysql]
+      options: -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-8af0f326 -f m1.medium
+  - ec2 3:
+      run_list: role[webserver] recipe[mysql::client]
+      options: -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small
+```
+
+produces the knife commands
+
+```
+knife ec2 server create -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-8af0f326 -f m1.medium -j '{"tags":["amazon+rolemysql"]}' -r 'role[mysql]'
+knife ec2 server create -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small -j '{"tags":["amazon+rolewebserverrecipemysqlclient"]}' -r 'role[webserver],recipe[mysql::client]'
+knife ec2 server create -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small -j '{"tags":["amazon+rolewebserverrecipemysqlclient"]}' -r 'role[webserver],recipe[mysql::client]'
+knife ec2 server create -S mray -i ~/.ssh/mray.pem -x ubuntu -G default -I ami-7000f019 -f m1.small -j '{"tags":["amazon+rolewebserverrecipemysqlclient"]}' -r 'role[webserver],recipe[mysql::client]'
+```
+
+Another use of `clusters` is with the `--cluster-file` option, which will allow the use of a different file to define the members of the cluster. If there are any `nodes` or `clusters` defined in the primary manifest file, they will be removed and the content of the `--cluster-file` will be used instead. This allows you to switch the target destination of infrastructure by picking different `--cluster-file` endpoints.
+
+# Extract #
+
 Spiceweasel may also be used to generate knife commands or Spiceweasel manifests in JSON or YAML.
 
 ```
@@ -338,9 +235,9 @@ spiceweasel --extractyaml
 ```
 When run in your Chef repository generates YAML-formatted output that may be captured and used as your Spiceweasel manifest file.
 
-Usage
-=====
-To parse a spiceweasel manifest, run the following from your Chef repository directory:
+# Usage #
+
+To parse a Spiceweasel manifest, run the following from your Chef repository directory:
 
 ```
 spiceweasel path/to/infrastructure.json
@@ -354,63 +251,66 @@ spiceweasel path/to/infrastructure.yml
 
 This will generate the knife commands to build the described infrastructure. Infrastructure manifest files must end in either `.json` or `.yml`.
 
-OPTIONS
-=======
+# OPTIONS #
+
+## -c/--knifeconfig ##
 
--c/--knifeconfig
-----------------
 Specify a knife.rb configuration file to use with the knife commands.
 
---debug
--------
+## --cluster-file ##
+
+Specify the file to use to override the `nodes` and `clusters` from the primary manifest file. This allows you to switch the target destination of infrastructure by picking different `--cluster-file` endpoints.
+
+## --debug ##
+
 This provides verbose debugging messages.
 
--d/--delete
------------
-The delete command will generate the knife commands to delete the infrastructure described in the manifest. This includes each cookbook, environment, role, data bag and node listed. Node deletion will specify individual nodes, attempt to pass the list of nodes to the cloud provider for deletion, and finish with `knife node bulk delete`. If you are mixing individual nodes with cloud provider nodes it is possible that nodes may be missed from cloud provider deletion and you should double-check (ie. `knife ec2 server list`).
+## -d/--delete ##
+
+The `delete` option will generate the knife commands to delete the infrastructure described in the manifest. This includes each cookbook, environment, role, data bag and node listed. Node deletion will specify individual nodes and their clients, and attempt to pass the list of nodes to the cloud provider for deletion, and finish with `knife node bulk delete`. If you are mixing individual nodes with cloud provider nodes it is possible that nodes may be missed from cloud provider deletion and you should double-check (ie. `knife ec2 server list`).
+
+## -e/--execute ##
+
+The `execute` option will directly execute the knife commands, creating (or deleting or rebuilding) the infrastructure described in the manifest.
 
---dryrun
---------
-This is the default action, printing the knife commands to be run without executing them.
+## --extractlocal ##
 
---extractlocal
---------------
 When run in a chef repository, this will print the knife commands to be run.
 
---extractjson
---------------
-When run in a chef repository, this will print a new JSON manifest that may be used as input to Spiceweasel.
+## --extractjson ##
 
---extractyaml
---------------
-When run in a chef repository, this will print a new YAML manifest that may be used as input to Spiceweasel.
+When run in a chef repository, this will print a new JSON manifest that may be used as input to spiceweasel.
+
+## --extractyaml ##
+
+When run in a chef repository, this will print a new YAML manifest that may be used as input to spiceweasel.
+
+## -h/--help ##
 
--h/--help
----------
 Print the currently-supported usage options for spiceweasel.
 
---novalidation
---------------
+## --novalidation ##
+
 Disable validation ensuring existence of the cookbooks, environments, roles, data bags and nodes in infrastructure file.
 
---parallel
-----------
+## --parallel ##
+
 Use the GNU 'parallel' command to execute 'knife VENDOR server create' commands that may be run simultaneously.
 
--r/--rebuild
-------------
-The rebuild command will generate the knife commands to delete and recreate the infrastructure described in the manifest. This includes each cookbook, environment, role, data bag and node listed.
+## -r/--rebuild ##
+
+The rebuild option will generate the knife commands to delete and recreate the infrastructure described in the manifest. This includes each cookbook, environment, role, data bag and node listed.
+
+## --siteinstall ##
 
---siteinstall
--------------
 Use the 'install' command with 'knife cookbook site' instead of the default 'download'.
 
--v/--version
-------------
+## -v/--version ##
+
 Print the version of spiceweasel currently installed.
 
-License and Author
-==================
+# License and Author #
+
 Author: Matt Ray <matt@opscode.com>
 
 Copyright: 2011-2012 Opscode, Inc