I've stated a migration guide for users of the old cluster module to migrate to
the new HA module. I'd appreciate any comments, esp. from folks who have worked
with both. At the moment it's very brief.
The doc is attached and also checked into qpid/qpid/cpp.
Thanks in advance!
Alan.
<!--*-markdown-*-->
Migrating to new HA
===================
Up to version 0.20, Qpid provided the `cluster` module to support active-active
clustering for Qpid C++ brokers. In version 0.20 the `ha` module was introduced
supporting active-passive HA clustering. From version 0.22 the older `cluster`
module is no longer available so users will have to migrate to the new `ha`
module.
This document summarizes the differences between the old and new HA modules and
the steps to migrate to new HA. It assumes you have read the
[HA chapter of the C++ Broker Book][chapter-ha]
Client connections and fail-over
--------------------------------
The old cluster module was active-active: clients could connect to any broker in
the cluster. The new ha module is active-passive. Exactly 1 broker acts as
*primary* the other brokers act as *backup*. Only the primary accepts client
connections. If a client attempts to connect to a *backup* broker, the
connection
will be aborted and the client will fail-over until it connects to the primary.
See
["Client Connections and Failover"][ha-failover].
The new cluster module also supports a [virtual IP address][ha-virtual-ip].
Clients can be configured with a single IP address that is automatically routed
to the primary broker. This is the recommended configuration.
Migrating configuration options for the old cluster module
----------------------------------------------------------
`cluster-name`: Not needed.
`cluster-size`: Not needed but see "Using a message store in a cluster" below
`cluster-url`: Use `ha-public-url`, which is recommended to use a [virtual IP
address][ha-virtual-ip]
`cluster-cman`: Not needed
`cluster-username, cluster-password, cluster-mechanism`: use `ha-username,
ha-password, ha-mechanism`
Configuration options for new HA module
----------------------------------------
`ha-cluster`: set to `yes` to enable clustering.
`ha-brokers-url`: set to a URL listing each node in the cluster. For example
`amqp:node1.exaple.com,node2.exaple.com,node3.exaple.com`. The set of addresses
for the cluster is fixed, you can't add new members with different addresses
while the cluster is running. You can shut-down and re-start a broker on the
same address.
`ha-public-url`: URL used by clients to connect to the cluster. It is
recommended to set this to the [Virtual IP address][ha-virtual-ip] of the
cluster.
`ha-replicate`: Set to `all` to replicate everything like the old cluster does.
New HA provides more flexibility over what is replicated, see ["Controlling
replication of queues and exchanges"][ha-replicate-values].
`ha-username, ha-password, ha-mechanism`: Same as old `cluster-username,
cluster-password, cluster-mechanism`
`ha-backup-timeout`: Maximum time that a recovering primary will wait for an
expected backup to connect and become ready.
`link-maintenance-interval`: Interval in seconds for the broker to check link
health and re-connect links if need be. If you want brokers to fail over quickly
you can set this to a fraction of a second, for example: 0.1.
`link-heartbeat-interval` Heartbeat interval for replication links. The link
will be assumed broken if there is no heartbeat for twice the interval.
Configuring rgmanager
---------------------
The new HA module requires an external cluster resource manager, `rgmanager`
provided by the `cman` package. `rgmanager` is responsible for stopping and
starting brokers and determining which broker is promoted to primary. It is also
responsible for detecting primary failures and promoting a new primary. See
["Configuring rgmanager as resource manager"][ha-rm-config]
Broker Administration Tools
---------------------------
Normally, clients are not allowed to connect to a backup broker. However
management tools are allowed to connect to a backup brokers. If you use these
tools you must not add or remove messages from replicated queues, nor create or
delete replicated queues or exchanges as this will disrupt the replication
process and may cause message loss.
qpid-ha allows you to view and change HA configuration settings.
The tools qpid-config, qpid-route and qpid-stat will connect to a backup if you
pass the flag ha-admin on the command line.
Fail-over exchange
------------------
The fail-over exchange is not supported in new HA, use a
[virtual IP address][ha-virtual-ip] instead.[]
Using a message store in a cluster
----------------------------------
If you use a persistent store for your messages then each broker in a cluster
will have its own store. If the entire cluster fails, when restarting the
*first* broker that becomes primary will recover from its store. All the other
brokers will clear their stores and get an update from the primary to ensure
consistency. See ["Using a message store in a cluster"][ha-store].
[chapter-ha]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html
[ha-failover]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-failover
[ha-failover]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-virtual-ip
[ha-replicate-values]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-replicate-values
[ha-rm-config]:
http://qpid.apache.org/books/trunk/AMQP-Messaging-Broker-CPP-Book/html/chapter-ha.html#ha-rm-config
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
