Ringleader NPM

ringleader

Ringleader is a simple and powerful program for wrangling clusters of EC2 spot instances, monitoring their health, and auto-scaling.

Ringleader can run as a module or commandline client. As a module, each Ringleader instance is an event emitter that manages and reports on the status of a cluster on EC2, providing an interface for programmatic modification. As a commandline client, Ringleader spawns an HTTP server which can be used to monitor and manage a cluster.

Ringleader aims to keep cluster management simple with a few assumptions and generalizations:

A cluster is a pool of EC2 spot instances sharing the same region, AMI (machine image), and instance type
Cluster instances can be deemed healthy if AWS says they are running and if they respond as expected to an HTTP request healthcheck

Given this, some stuff that Ringleader does not do on its own includes:

Handle clusters of mixed resource types (different images, different sizes, etc.)
Handle any kind of intercommunication between servers
Manage load balancing between cluster servers
Make health decisions based on internal server metrics (unless provided through a simple HTTP endpoint)
Manage clusters spanning multiple AWS regions

Getting Started

Install the module with: npm install ringleader (or npm install -g ringleader - if using from commandline)

var Ringleader = new require('ringleader')(options);

#print usage
ringleader --port=[port to run server on]

Credentials

Ringleader requires access to the AWS API, which can be provided through:

commandline variables of AMAZON_KEY and AMAZON_SECRET

a file named config.json in the project's root path which includes an object like:

{
  "aws": {
    "accessKeyId": "amazon key"
  , "secretAccessKey": "amazon secret"
  , "region": "amazon region"
  }
, "cluster": {
    "ami": "ami to use for cluster instances"
  , "max_price": 0.25 //maximum price for spot instance requests
  , "label": "label for cluster"
  , "instance_size": "size for cluster instances"
  }
, "healthcheck": { //specs for healthcheck to perform on instances
    "auth": { //optional, if you have http auth on instances
      "user": "http auth username"
    , "pass": "http auth password"
    }
    , "url_path": "url path to hit with healthchecks"
    , "regex": //stringified version of regex (optional)
    , "port": 443 //port to request from
    , "strictSSL": false //allow self-signed ssl certificates
    , "protocol": "https" //protocol to use for healthchecks
  }
}