[Gluster-users] Meta-discussion

[Brian Candler]

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.