Adds some documentation on using the cookbook

diff --git a/README.md b/README.md
index 892708c55f04d3dd3f839eeff1371e51aa588552..93529dc2a9992e5b8c83678ba99b40e4d7be425c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -14,13 +14,15 @@ For help, use [Gitter chat](https://gitter.im/ceph/ceph-cookbook), [mailing-list
 
 ### Chef
 
->= 11.6.0
+\>= 11.6.0
 
 ### Platform
 
 Tested as working:
 
+* Debian Wheezy (7)
 * Ubuntu Precise (12.04)
+* Ubuntu Trusty (14.04)
 
 ### Cookbooks
 
@@ -31,15 +33,6 @@ https://github.com/opscode/cookbooks
 * apt
 * apache2
 
-
-## ATTRIBUTES
-
-### Ceph Rados Gateway
-
-* node[:ceph][:radosgw][:api_fqdn]
-* node[:ceph][:radosgw][:admin_email]
-* node[:ceph][:radosgw][:rgw_addr]
-
 ## TEMPLATES
 
 ## USAGE
@@ -51,6 +44,21 @@ http://ceph.com/docs/master
 http://ceph.com/resources/mailing-list-irc/
 http://www.inktank.com/
 
+This cookbook can be used to implement a chosen cluster design. Most of the configuration is retrieved from node attributes, which can be set by an environment or by a wrapper cookbook. A basic cluster configuration will need most of the following attributes:
+
+* node['ceph']['config']['fsid'] - the cluster UUID
+* node['ceph']['config]'['global']['public network'] - a CIDR specification of the public network
+* node['ceph']['config]'['global']['cluster network'] - a CIDR specification of a separate cluster replication network
+* node['ceph']['config]'['global']['rgw dns name'] -  the main domain of the radosgw daemon
+
+Most notably, the configuration does _NOT_ need to set the `mon_initial_members`, because the cookbook does a node search to find other mons in the same environment.
+
+The other set of attributes that this recipe needs is node['ceph']['osd_devices'], which is an array of OSD definitions, similar to the following:
+
+* {'device' => '/dev/sdb'} - Use a full disk for the OSD, with a small partition for the journal
+* {'type' => 'directory', 'device' => '/src/node/sdb1/ceph'} - Use a directory, and have a small file for the journal
+* {'device' => '/dev/sde', 'dmcrypt' => true} - Store the data encrypted by passing --dmcrypt to `ceph-disk-prepare`
+* {'device' => '/dev/sdc', 'journal' => '/dev/sdd2'} - use a full disk for the OSD with a custom partition for the journal
 
 ### Ceph Monitor
 
@@ -82,6 +90,45 @@ Includes:
 
 Ceph Rados Gateway nodes should use the ceph-radosgw role
 
+## ATTRIBUTES
+
+### General
+
+* node['ceph']['search_environment'] - a custom Chef environment to search when looking for mon nodes. The cookbook defaults to searching the current environment
+* node['ceph']['branch'] - selects whether to install the stable, testing, or dev version of Ceph
+* node['ceph']['version'] - install a version of Ceph that is different than the cookbook default. If this is changed in a wrapper cookbook, some repository urls may also need to be replaced, and they are found in attributes/repo.rb. If the branch attribute is set to dev, this selects the gitbuilder branch to install
+* node['ceph']['extras_repo'] - whether to install the ceph extras repo. The tgt recipe requires this
+
+* node['ceph']['config']['fsid'] - the cluster UUID
+* node['ceph']['config']['global']['public network'] - a CIDR specification of the public network
+* node['ceph']['config']['global']['cluster network'] - a CIDR specification of a separate cluster replication network
+* node['ceph']['config']['config-sections'] - add to this hash to add extra config sections to the ceph.conf
+
+### Ceph MON
+
+* node['ceph']['config']['mon'] - a hash of settings to save in ceph.conf in the [mon] section, such as `'mon osd nearfull ratio' => '0.70'`
+
+### Ceph OSD
+
+* node['ceph']['osd_devices'] - an array of OSD definitions for the current node
+* node['ceph']['config']['osd'] - a hash of settings to save in ceph.conf in the [osd] section, such as `'osd max backfills' => 2`
+* node['ceph']['config']['osd']['osd crush location'] - this attribute can be set on a per-node basis to maintain Crush map locations
+
+### Ceph MDS
+
+* node['ceph']['config']['mds'] - a hash of settings to save in ceph.conf in the [mds] section, such as `'mds cache size' => '100000'`
+* node['ceph']['cephfs_mount'] - where the cephfs recipe should mount CephFS
+
+### Ceph Rados Gateway
+
+* node['ceph']['radosgw']['api_fqdn'] - what vhost to configure in the web server
+* node['ceph']['radosgw']['admin_email'] - the admin email address to configure in the web server
+* node['ceph']['radosgw']['rgw_addr'] - the web server's bind address, such as *:80
+* node['ceph']['radosgw']['rgw_port'] - if set, connects to the radosgw fastcgi over this port instead of a unix socket
+* node['ceph']['radosgw']['webserver_companion'] - defaults to 'apache2', but can be set to false to not configure anything
+* node['ceph']['radosgw']['path'] - where to save the s3gw.fcgi file
+* node['ceph']['config']['global']['rgw dns name'] -  the main domain of the radosgw daemon, to calculate the bucket name from a subdomain
+
 ## Resources/Providers
 
 ### ceph\_client