= Scaling a Pacemaker Cluster =

== Overview ==

In a basic Pacemaker high-availability
cluster,footnote:[See the http://www.clusterlabs.org/doc/[Pacemaker
documentation], especially 'Clusters From Scratch' and 'Pacemaker Explained',
for basic information about high-availability using Pacemaker]
each node runs the full cluster stack of corosync and all Pacemaker components.
This allows great flexibility but limits scalability to around 16 nodes.

To allow for scalability to dozens or even hundreds of nodes, Pacemaker
allows nodes not running the full cluster stack to integrate into the cluster
and have the cluster manage their resources as if they were a cluster node.

== Terms ==

cluster node::
    A node running the full high-availability stack of corosync and all
    Pacemaker components. Cluster nodes may run cluster resources, run
    all Pacemaker command-line tools (`crm_mon`, `crm_resource` and so on),
    execute fencing actions, count toward cluster quorum, and serve as the
    cluster's Designated Controller (DC).
(((cluster node)))
(((node,cluster node)))

pacemaker_remote::
    A small service daemon that allows a host to be used as a Pacemaker node
    without running the full cluster stack. Nodes running pacemaker_remote
    may run cluster resources and most command-line tools, but cannot perform
    other functions of full cluster nodes such as fencing execution, quorum
    voting or DC eligibility. The pacemaker_remote daemon is an enhanced
    version of Pacemaker's local resource management daemon (LRMD).
(((pacemaker_remote)))

remote node::
    A physical host running pacemaker_remote. Remote nodes have a special
    resource that manages communication with the cluster. This is sometimes
    referred to as the 'baremetal' case.
(((remote node)))
(((node,remote node)))

guest node::
    A virtual host running pacemaker_remote. Guest nodes differ from remote
    nodes mainly in that the guest node is itself a resource that the cluster
    manages.
(((guest node)))
(((node,guest node)))

[NOTE]
======
'Remote' in this document refers to the node not being a part of the underlying
corosync cluster. It has nothing to do with physical proximity. Remote nodes
and guest nodes are subject to the same latency requirements as cluster nodes,
which means they are typically in the same data center.
======

[NOTE]
======
It is important to distinguish the various roles a virtual machine can serve
in Pacemaker clusters:

* A virtual machine can run the full cluster stack, in which case it is a
  cluster node and is not itself managed by the cluster.
* A virtual machine can be managed by the cluster as a resource, without the
  cluster having any awareness of the services running inside the virtual
  machine. The virtual machine is 'opaque' to the cluster.
* A virtual machine can be a cluster resource, and run pacemaker_remote
  to make it a guest node, allowing the cluster to manage services
  inside it. The virtual machine is 'transparent' to the cluster.
======

== Support in Pacemaker Versions ==

It is recommended to run Pacemaker 1.1.12 or later when using pacemaker_remote
due to important bug fixes. An overview of changes in pacemaker_remote
capability by version:

.1.1.14
* Resources that create guest nodes can be included in groups
* reconnect_interval option for remote nodes
* Bug fixes, including a memory leak

.1.1.13
* Support for maintenance mode
* Remote nodes can recover without being fenced when the cluster node
  hosting their connection fails
* Running pacemaker_remote within LXC environments is deprecated due to
  newly added Pacemaker support for isolated resources
* Bug fixes

.1.1.12
* Support for permanent node attributes
* Support for migration
* Bug fixes

.1.1.11
* Support for IPv6
* Support for remote nodes
* Support for transient node attributes
* Support for clusters with mixed endian architectures
* Bug fixes

.1.1.10
* Bug fixes

.1.1.9
* Initial version to include pacemaker_remote
* Limited to guest nodes in KVM/LXC environments using only IPv4;
  all nodes' architectures must have same endianness

== Guest Nodes ==
(((guest node)))
(((node,guest node)))

*"I want a Pacemaker cluster to manage virtual machine resources, but I also
want Pacemaker to be able to manage the resources that live within those
virtual machines."*

Without pacemaker_remote, the possibilities for implementing the above use case
have significant limitations:

* The cluster stack could be run on the physical hosts only, which loses the
  ability to monitor resources within the guests.
* A separate cluster could be on the virtual guests, which quickly hits
  scalability issues.
* The cluster stack could be run on the guests using the same cluster as the
  physical hosts, which also hits scalability issues and complicates fencing.

With pacemaker_remote:

* The physical hosts are cluster nodes (running the full cluster stack).
* The virtual machines are guest nodes (running the pacemaker_remote service).
  Nearly zero configuration is required on the virtual machine.
* The cluster stack on the cluster nodes launches the virtual machines and
  immediately connects to the pacemaker_remote service on them, allowing the
  virtual machines to integrate into the cluster.

The key difference here between the guest nodes and the cluster nodes is that
the guest nodes do not run the cluster stack. This means they will never become
the DC, initiate fencing actions or participate in quorum voting.

On the other hand, this also means that they are not bound to the scalability
limits associated with the cluster stack (no 16-node corosync member limits to
deal with). That isn't to say that guest nodes can scale indefinitely, but it
is known that guest nodes scale horizontally much further than cluster nodes.

Other than the quorum limitation, these guest nodes behave just like cluster
nodes with respect to resource management. The cluster is fully capable of
managing and monitoring resources on each guest node. You can build constraints
against guest nodes, put them in standby, or do whatever else you'd expect to
be able to do with cluster nodes. They even show up in `crm_mon` output as
nodes.

To solidify the concept, below is an example that is very similar to an actual
deployment we test in our developer environment to verify guest node scalability:

* 16 cluster nodes running the full corosync + pacemaker stack
* 64 Pacemaker-managed virtual machine resources running pacemaker_remote configured as guest nodes
* 64 Pacemaker-managed webserver and database resources configured to run on the 64 guest nodes

With this deployment, you would have 64 webservers and databases running on 64
virtual machines on 16 hardware nodes, all of which are managed and monitored by
the same Pacemaker deployment. It is known that pacemaker_remote can scale to
these lengths and possibly much further depending on the specific scenario.


== Remote Nodes ==
(((remote node)))
(((node,remote node)))

*"I want my traditional high-availability cluster to scale beyond the limits
imposed by the corosync messaging layer."*

Ultimately, the primary advantage of remote nodes over cluster nodes is
scalability. There are likely some other use cases related to geographically
distributed HA clusters that remote nodes may serve a purpose in, but those use
cases are not well understood at this point.

Like guest nodes, remote nodes will never become the DC, initiate
fencing actions or participate in quorum voting.

That is not to say, however, that fencing of a remote node works any
differently than that of a cluster node. The Pacemaker policy engine
understands how to fence remote nodes. As long as a fencing device exists, the
cluster is capable of ensuring remote nodes are fenced in the exact same way as
cluster nodes.

== Expanding the Cluster Stack ==

With pacemaker_remote, the traditional view of the high-availability stack can
be expanded to include a new layer:

.Traditional HA Stack
image::images/pcmk-ha-cluster-stack.png["Traditional Pacemaker+Corosync Stack",width="17cm",height="9cm",align="center"]

.HA Stack With Guest Nodes
image::images/pcmk-ha-remote-stack.png["Pacemaker+Corosync Stack With pacemaker_remote",width="20cm",height="10cm",align="center"]
