Bug 641409

For info's sake:

- I opened BZ 671250 for the documentation of SNMP traps in the Cluster Admin Guide in RHEL 6.1. That's point 7 here -- I put it in the Cluster Administration Guide but perhaps it could be moved to the new RHEL HA Guide?  It's a self-contained chapter.

- I cloned this bug as BZ 659753 to break off the documentation of the new CLI into its own bug.

- Regarding documenting VMs -- Michael Solberg has put together a document for Home Depot specifically documenting setting up VMs as resources (and all the network configuration that is required in advance). I will be adapting that document for public release, as a separate "Configuration Example". It's pretty much ready to go as is.

In reply to comment #5:

As noted in comment #4, I am currently in the process of putting together an independent example document on "Highly Available Virtualization" that is based almost entirely on Michael Solberg's customer document on configuring the High Availability Add-On to manage KVM Virtual Machines on RHEL 6. It does not specifically cover many of the issues noted in comment #4, but we need to coordinate this information and I wanted to keep that in this general bug.

The document should be ready for first review sometime next week (Feb 7-12).

To keep a record of this info, I am adding a copy of an email I just sent to John Ha about the documentatation set overhaul:

John,

Partly in response to Lon's review comments, and partly because we are far enough along in the process that I think we can now look at this issue more specifically than we could earlier, I've been looking over your new Cluster Suite Overview with an eye towards coordinating it with the Cluster Administration Guide. I am copying Lon and Perry and Sayan mostly to keep them in the loop, although of course I'd welcome any feedback they have to what I note here.

I will also add this email to BZ#641409.

The Purpose of the Two Books
----------------------------

In general, the Overview provides all the background to what is involved in configuring and managing the High Availability Add-On and the Administration document provides the procedures you use to configure and manage the High Availability Add-On.

For background, let me summarize the content and purpose of the Cluster Administration document:

The Cluster Administration document sort of grew (and shrank) as features and need required, but as it stands now it is basically a procedural overview of cluster configuration, divided out by configuration tools/methods. The book does not specify "Parts" but I note that here for clarity.

Part 1
- General installation and setup that applies no matter what configuration tool you use.

Part 2
- Procedural overview for using Conga to configure and manage your system
- Procedural overview for using the (new for 6.1) ccs command to configure and manage your system (although there's not much management that the ccs command performs)
- Procedural overview for using command lines tools to configure and
manage your system

These three chapters are not entirely parallel, because the three configuration tools/toolsets do not have entirely parallel functionality, but they are basically structured the same. There is a small of amount of overlap. Interestingly, the overlap is mostly in the areas that also overlap with the new section on rgmanager in the Cluster Overview, but I'll get to that later since I think we can remove those overlapping sections from the Admin Guide and slightly beef up the corresponding sections in the Cluster Overview.

Part 3
- Configuring SNMP traps (new for 6.1)

The door is open to adding other self-contained configuration-procedure chapters in what I call "Part 3" as needed, but for now this stands alone in terms of purpose.

Part 4 -- Appendixes
There are are series of appendixes that are (in general) intended as reference material that applies no matter which configuration tool you use. In some cases moving this material to appendixes was intended to avoid repeating the information in each of the configuration chapters: The summary of the fence device parameters for each fencing method and the summary of the HA resource parameters we support.

But there is one problematic appendix, as regards the documentation overhaul:  HA resource behavior. This is both general background to resources and services (and currently overlaps with the Overview) and what you might describe as procedural, since it shows how to configure a cluster.conf file for various purposes and how to debug and test.

Looking at the Cluster Suite Overview
-------------------------------------

Chapter 1: High Availability Add-0n Overview

No coordination issues with the Cluster Administration document

Chapter 2: Cluster Management with CMAN

The only section with a coordination issue is 2.1.1 Quorum Disks. This section refers to the qdisk man page for further information, but actually there is a lot of information about configuring quorum disks in the Conga and ccs chapters of the Cluster Administration document -- that came about at first because Conga does not display the specific flag/attribute names that you use in the configuration file, so the explanation of the screen names seemed useful. And then I just re-used that information when I wrote the ccs chapter (using the actual configuration file names). Also the annotated cluster schema provides boatloads of information.

So in general I think what's there is fine, but instead of just "For more information about configuring a quorum disk, refer to the qdisk man page" maybe we could add:

Further information about configuring quorum disk parameters is provided in the chapters on Conga and ccs administration in the Cluster Administration document.

(The reference to the cluster schema is there, so I don't think we need to reference it here as well.)

Chapter 3: RGmanager

Failover domains:

This chapter describes the various configuration options of failover domains. That material is also covered in all three of the configuration chapters. I think we can address the issue of repeating this information 4 times (not a good thing) by leaving it here in the Cluster Overview and referring to the Cluster Overview in the Cluster Administration.

Here's an example of the repeated information in the Cluster Administration Guide:

http://documentation-stage.bne.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Cluster_Administration/s1-config-failover-domain-conga-CA.html

Here is some info that's in the Cluster Administration document that we could probably add to overview (and remove from Cluster Administration):

- Failover domains are not required for operation.

- By default, failover domains are unrestricted and unordered.

- In a cluster with several members, using a restricted failover
  domain can minimize the work to set up the cluster to run a
  cluster service (such as httpd), which
  requires you to set up the configuration identically on all
  members that run the cluster service). Instead of setting up the
  entire cluster to run the cluster service, you must set up only
  the members in the restricted failover domain that you associate
  with the cluster service.

Also, I think the cluster overview should describe the characteristics of failover domains, but not necessarily the actual flags. What this means is that the I think the last bullet should not say "nofailback" but -- as it currently does in the Cluster Administration book -- note "Failback" as the characteristic of the ordered failover domain and slightly rephrase the description accordingly.

(I think it's ok, though, to leave in the note that "ordering, restriction, and nofailback are flags...", although I'd say something like "Whether a domain is ordered, restricted, or uses failback is determined by flags and these characteristics may be combined in almost any way...")

The behavior examples add a lot of info that isn't currently in the Cluster Admin book, and that's good.


Services and Resources:

Sections 3.2 through 3.6 get a little confusing to me, specifically regarding how they coordinate with the Cluster Administration document.

Also, it seems as if the discussion of services and resources should begin with an explanation of what they are.

This appendix of the Cluster Administration Guide (which I was not too familiar with -- it was Paul's) provides these background definitions:

http://documentation-stage.bne.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Cluster_Administration/ap-ha-resource-behavior-CA.html

It also covers some of the material in sections 3.2 and 3.3.

I think maybe both you and I need to look at the sections on services and resources in the Overview, and the appendix on resource behavior in the Administration Guide, and try to figure out how these chapters work together. We can probably better divide out what I'm calling "background" (what is a service, what is a resource, trees, relationships) from configuration (for configuration information, see...), and management (service operations and states, resource actions.) I'll leave that for now and maybe we can communicate about this over the next couple of weeks.

Section 3.5 -- Virtual Machine behaviors -- has no parallel in the Administration Guide (which doesn't cover this, and the plans are for this to be a separate book), so there are no coordination issues per se, but this chapter also mixes background info with service management issues. Just a point for now. Oh, also I think you are already working on the issue of how to coordinate this section with chapter 7 (Virtualization and High Availability), so I leave that to you.


Chapter 4: Fencing

Nice background, but it should have a specific reference to the Cluster Admin Guide (which provides a series of examples for each configuration method, showing how to configure backup fencing and storage-based fencing and fencing a system with dual power). If you find yourself with all the time in the world, you might want to add an illustration for backup fencing. You can find a variety of fence illustrations and examples here (for RHEL 5, but the concepts are the same):

http://documentation-stage.bne.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html/Configuration_Example_-_Fence_Devices/index.html

Maybe all it needs is "for further information on configuring fence devices, see the Cluster Administration document".

Chapter 5: Lock Management: No overlap with the Admin. Guide

Chapter 6: Configuration and Administration Tools

This looks like a chapter to think about for the long run, but for now the main and necessary thing is to add the ccs command to the bullets in section 6.1.

* As of the Red Hat Enterprise Linux 6.1 release and later, the Red Hat High Availability Add-On provides support for the ccs cluster configuration command, which allows an administrator to create, modify and view the cluster.conf cluster configuration file. Refer to
Cluster Administration for information about configuring and managing the High Availability Add-On with the ccs comand.

Also, the references in 6.1 should be to Cluster Administration, right?

Ok, that's it for now. I think the work we have to do next is looking again at the material on services and resources.

Good job and good luck.

-Steven