Clustr

Coverage Status Build Status Code Climate Dependency Status Gem Version

Clustr provides the means to cluster servers together, by storing unique identifiers (and any additional information) for each node in a store, which in-turn is managed by an adapter that is configured by the user.

A server can belong to many different clusters (enables the use of Docker containers), and is able to interrogate other clusters, aslong as they are correctly configured inside the configuration directory, ~/.clustr/.

Available Adapters

  • AWS SimpleDB - Uses a pre-existing domain, or creates one to store unique information about each node within the cluster.

Installation

Add this line to your application's Gemfile:

gem 'clustr'

And then execute:

$ bundle

Or install it yourself as:

$ gem install clustr

Configuring Clusters

If cluster files are defined inside the folder ~/.cluster, where ~ represents your user home directory, they will be automatically detected and initialized.

Cluster files describe clusters that a node is able to join and/or retrieve information from, such as the clusters members.

Adapter

The adapter key identifies how this cluster is formed, in the future I plan to implement DynamoDB as well as Memcached and MySQL. The adapter controls how information is extracted and inserted into the cluster at the lowest level.

Key

Every cluster must contain a unique key, this helps to namespace individual clusters incase they are using the same underlying adapter. In most cases, the key can simply be a unique domain or even a database table.

Example

Given the following Cluster file ~/.clustr/rabbitmq, with the content:

adapter=SimpleDB
key=my-simple-db-domain-daw9249ad

Clustr will automatically initialize a cluster named "rabbitmq" with a SimpleDB adapter pointing at the shared domain identified by the key value.

Clustr configuration files enable the gem to join the server to a cluster, as well as interrogate clusters that the server may not necessarily be a part of. Nodes are not joined to the cluster automatically, this must be done manually via the command line.

Usage

Depending upon the adapter that you use, you may need to setup your AWS Credentials, follow the instructions here to set them up.

The command line arguments --access-key-id, --secret-access-key and --region also enable you to pass AWS credentials in with each individual command.

Joining a Cluster

Given the previous example where we setup a configuration file for a RabbitMQ cluster, we can join the node to the cluster using the command:

$ clustr join --clusters rabbitmq --id rabbit@`echo hostname` --access-key-id 0123456 --secret-access-key a0b1c2d3e4 --region eu-west-1

Retrieving Members of a Cluster

Given the same previous example where a RabbitMQ cluster was defined, we can retrieve the list of members by their unique ID's (their hostname in this case) in a space delimited list, with the following command:

$ clustr list --cluster rabbitmq #=> rabbit@192-168-0-1 rabbit@192-168-0-5

Given this command, we could in practise combine this into the rabbitmqctl clustering command:

$ sudo rabbitmqctl cluster `clustr list --cluster rabbitmq`

Contributing

  1. Fork it ( http://github.com//clustr/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request