ClusterLabs/pacemaker — pull request #619 by kgaillot (2014-12-22 19:41:40+00:00)
Title: update Clusters From Scratch for Fedora 21

This revision is an extensive overhaul of the Clusters From Scratch documentation. Diff is possible but you'll probably want to compare the generated HTML side-by-side instead or in addition. For convenience I've generated the full branded docs and made them available at http://www.boogieonline.com/ha/ for comparison.

== The changes fall into these areas:

* Update for Fedora 21 (OS installation instructions, some systemd/firewalld-related stuff and pcs syntax/output).

* Fix: http://bugs.clusterlabs.org/show_bug.cgi?id=5227 - typos in Pacemaker-1.1-Clusters_from_Scratch-en-US.pdf. Only one of the recommended changes was needed; the others related to differences in pcs in F20 vs F21, and the syntax is now correct for F21.

* Strip out the ifdef's for generating a crmsh version (internal markup changes only, no visible impact on generated output). I had mixed feelings about this, but the crmsh info would no longer have been valid as-is for Fedora 21, so I thought it was better to remove it altogether. (Version control makes me brave.)

* Make the styling more consistent with what the "Typographic Conventions" section says it is. This includes getting rid of the [source,C] highlighting for command-line blocks, since it's not really correct and the conventions do not indicate any highlighting in command-line output blocks.

* I added one stylistic convention, commands are displayed with '#' if they need to be done on both nodes, or '[root@pcmk-1 ~]#' if they need to be done on one specific node. I felt this was more consistent with what the reader would see if they were following exactly, but if you feel it clutters too much, we can go back to '#' everywhere.

* Make most headings imperative (e.g. "Adding a Resource" becomes "Add a Resource"). Psychological engineering to make the reader feel more active and confident.

* Move the STONITH chapter before Active/Active, because DLM now refuses to run if STONITH is disabled. Within Active/Active, I moved configuring a DLM resource before configuring GFS2, for clarity; before, the DLM configuration was in the middle of the GFS2 configuration.

* Misc. corrections. For example, the previous version had no colocation or ordering constraints for DLM and GFS2, so trying to stop cluster services on a node could lead to ordering problems and the node being fenced; those constraints were added.

* Misc. rewordings for clarity.

== Issues remaining:

* While I took out the crmsh ifdef's from the documentation, the Makefile.am in doc still distinguishes between crmsh and pcs versions. No harm done, but crmsh could be removed here, too -- but that would likely involve path changes (and thus .gitignore changes) etc. It would also be nice to redo some of the targets, e.g. allowing the full set of documentation to be built without also trying to upload it to clusterlabs.org.

* "2.6.2. Configure Corosync" has an ugly workaround for a bug in the currently shipped version of pcs in Fedora 21. Chris Feist is working on a fix, but in the meantime the only workarounds are disabling IPv6 on the node entirely or the one-line source change described in this section. I'm not sure whether we should hold CFS until the fix is available, or release it with the workaround and update it when the fix comes out.

* The whole process might not actually work if followed exactly; I encountered many issues and fixed or worked around them as I went, and I may have missed updating the documentation accordingly in some cases. It would be worthwhile for someone else to try to follow it to get a fresh perspective.

* I didn't want to go down the rabbit hole of even bigger changes, but I think it would make sense to stop Chapter 2 at "Configure SSH" so that it was just the OS install/configuration, and put the remainder of chapter 2 with the current chapter 3 so that chapter 3 becomes cluster install/configuration.

* Finally and trivially, there are three places where this document is versioned. Book_Info.xml has an and ; appears on the title page, and seems not be user-visible, so it's probably just for internal bookkeeping. Then Revision_History.xml has its own numbering system (and is visible as the final appendix). It looks weird that the title page has one version number and the revision history has another. I'd recommend keeping the Revision_History.xml X-Y versioning in sync with the EDITION-PUBSNUMBER of Book_info.xml (which would mean jumping EDITION ahead a few numbers). To put some logic behind it, we could increment EDITION whenever the version/syntax of the documented software changes (Fedora, pacemaker, corosync, pcs), and PUBSNUMBER for other changes (corrections, translations, etc.). But that's incredibly unimportant.