Bug 504044 - Clustering Documentation
Clustering Documentation
Product: Red Hat Enterprise MRG
Classification: Red Hat
Component: Messaging_Installation_and_Configuration_Guide (Show other bugs)
All Linux
urgent Severity urgent
: 1.3
: ---
Assigned To: Jonathan Robie
: Documentation
Depends On:
  Show dependency treegraph
Reported: 2009-06-03 18:28 EDT by William Henry
Modified: 2012-11-07 09:19 EST (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2010-10-20 07:30:44 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description William Henry 2009-06-03 18:28:11 EDT
Description of problem:

(Removed customer reference) Carl has more from another customer.

Installation Guide and User Guide.

I suggest we go over the User Guide Cluster chapter and move all configuration information there into the Install Guide where it should be. I.e. by the end of the install guide one should be able to start a cluster - currently that is not so and there are steps in the User Guide that need to be performed.  

Not sure what needs to be in the user guide on cluster (see below some strong suggestions). Perhaps some information on how you can check a cluster is working correctly with qpid-tool. Add some queues and exchanges and check for replication.  (??)

Remove any claims about scalability and load-balancing - these are not true.

Make an explicit statement about what Active Active means and what Active Passive means.

Show a diagram that visually explains Active Active Qpid cluster.

Make an explicit statement about what gets replicated - queues, exchanges and bindings. Include an explicit statement regarding replication technique - i.e. messages are replicated onto replicated queues rather than sent to replicated exchanges for routing to replicated queues.

i.e. at then end of Install Guide on clustering, clustering is fully set up. At the end of User Guide on Clustering the user understands what clustering provides and has an idea of the efficiencies in place and limits. Perhaps even suggesting that in order to scale out another cluster may need to be added.

I know that there are some BZs that will also enhance the docs, jonathan is already on that.

Some other notes for docs:

Things to check:
  - Set selinux to permissive mode "setenforce permissive"
  - "ais" needs to be in passwd file
  - "ais" needs to be in group file
  - "ais" needs to be default group for user "qpid"
  - "chkconfig postgresql on" (to start the service on boot) (Cumin not cluster related)
  - "chkconfig openais on" (to start the service on boot)
  - "chkconfig qpidd on" (to start the service on boot)

Also we noticed that the default openais config does not have:

logging {
  to_syslog: yes

If this needs to be the setting for logging can we explicitly say to change logging to the above? If not can we explicitly say that we'd suggest adding the following line to the logging section:
  to_syslog: yes

Version-Release number of selected component (if applicable):

Comment 1 William Henry 2009-06-04 07:01:07 EDT
NOTE on ACTIVE ACTIVE (from Gordon):

(important to get this sort of information in there so that users understand
the overhead of replication)

The raw bytes read of a connected clients socket are replicated to all nodes
and processed by each node. In addition the cluster sends out certain commands
itself, again replicated to- and processed by- all nodes.

Each node acts essentially as a state machine, the idea being that replicating
all inputs to that will result in each replica going through the same 'states'.
Comment 2 Jonathan Robie 2009-09-09 11:24:38 EDT
This chapter has now been extensively rewritten, and I believe most of the issues you raise have now been addressed, though not always in the same way you suggest.

Perhaps you could review the current chapter and let me know what remaining concerns you have?
Comment 5 William Henry 2010-06-04 15:17:51 EDT
It seems strange to me that the Installation Guide refers to installing OpenAIS and the User Guide describes how to install OpenAIS.

Surely all install tasks should be described in the Installation Guide. One could argue that OpenAIS is really not part of MRG and therefore doesn't belong in the user guide. Well then remove OpenAIS install instructions from the MRG docs all together and just reference the OpenAIS/corosync installation guide.

Even for chronology purposes it would seem that having an Install Guide refer to the installation of OpenAIS but not describing it and the User Guide then describing it seems backward. Install Guide: "Once you have installed OpenAIS (WH:where? How?), configure MRG Messaging to run in a cluster as follows."

Furthermore the unsuspecting user might spend a lot of time just trying to find out how to install OpenAIS because the Install Guide doesn't link to or reference the section in the User Guide.  And the User Guide (after the misplaced OpenAIS installation doesn't reference/link to the Install Guide on how to setup (install) MRG Clustering!! IT just means that to do this you have to go to two different places that don't even reference each other!

So though I like a lot of the changes and more explicit descriptions I think think some of the content is either misplaced or lacks good references. (I still think misplaced.)  

I think that moving the OpenAIS install instructions to the Install Guide and referring and linking to both OpenAIS installation and Clustering installation in the User Guide is better. :)
Comment 6 Jiri Kolar 2010-06-07 04:53:17 EDT
I personally do not find this fixed. So i consulted with William and asked him to write his opinion (comment above). I agree with him that content describing Instalation and use is still mixed together.

so I am moving this bug back to ASSIGNED
Comment 7 Jonathan Robie 2010-06-14 18:28:53 EDT
You're right, this was not fixed.

I've taken the clustering and federation chapters out of the install guide entirely, added a chapter for installing openais for clustering, and added cross references between the two guides.

The information on setting up a cluster is still in the User's Guide.
Comment 8 Jiri Kolar 2010-06-22 11:29:26 EDT
fixed in rhm-docs.noarch 0:0.7.955296-1.el5, moving to VERIFIED

Note You need to log in before you can comment on or make changes to this bug.