On Wed, Jan 02, 2013 at 09:03:59AM -0500, Jeff Darcy wrote: > * A general "principles of operation" guide - not a whole book, but more than > bits scattered among slide presentations and wiki pages. Let's say something > that would be on the order of 15-50 pages printed out. Personally I'd like to see the details as well as principles. Take replication as an example: I'd want to know exactly what xattrs are written and when, what the values mean, what values are seen in intermediate states, on successful completion and when replication failed. Ditto for distribution (DHT). Since these details may change with the code, I wouldn't mind if they sat in the git repo alongside the code itself. > * Many "cookbook" examples detailing initial configurations for common use > cases (e.g. media servers, VM storage) and higher-level sequences of steps for > common operations (e.g. adding servers). Not just "common" operations; I believe what's really important is the uncommon operations in failure scenarios. e.g. replacing a failed server; replacing a failed brick filesystem within a server; how to diagnose and fix problems with stuck replication and stuck rebalancing, or when the volume config is out of sync between peers (which bit me badly). I think Red Hat's documentation of LVM is a good example of how this can be done well: https://access.redhat.com/knowledge/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/ Not only does it give how-to examples of pretty much everything you might want to do with LVM, it also has a whole section on troubleshooting tools and recovery procedures, and an appendix on low-level configuration of dm (analogous to the volfiles in gluster) Finally, although I realise that RH is aiming towards a storage appliance, I still think it would be useful to document how (safely) to manipulate the volfiles by hand and keep them in sync between peers - the custom translators are all still there and it would be good to be able to use them, and this is likely to encourage third-party feature development. Regards, Brian.
