Infrastructure orchestration engine
Ruby CoffeeScript JavaScript
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


We need more than "ssh-in-a-for-loop". Our infrastructure get more complex every day and we need a tool that can choreograph an intricate dance of services, servers and commands in a manageable way.

Mastermind is an infrastructure orchestration engine. Its purpose is to provide the ability to compose and automate complex tasks with predefined and reproducible outcomes.

Mastermind uses a special domain-specific language for its process definitions, but if you're familiar with Ruby, it should feel right at home.

Using Mastermind

Here's an example of a basic sysadmin workflow, as implemented by Mastermind. Here, we create and destroy an EC2 instance, while notifying a Campfire room of each action performed.

defn = Definition.create({
  name: "create_and_destroy_ec2_server",
    content: %q{
    create_ec2_server image_id: '${image_id}',
      flavor_id: '${flavor_id}',
      key_name: '${key_name}',
      region: '${region}',
      availability_zone: '${availability_zone}',
      groups: '$f:groups', 
      tags: '$f:tags'

    # ${instance_id} is a field added by the `create_ec2_server` action
    notify_campfire message: "${instance_id} created!"

    destroy_ec2_server instance_id: '${instance_id}', region: '${region}'

    notify_campfire message: "${instance_id} destroyed!"

job ={
  name: "new ec2 instance workflow",
  definition: defn,
  fields: {
    flavor_id: "t1.micro",
    image_id: "ami-fe5bd4ce",
    region: "us-west-2",
    availability_zone: "us-west-2a",
    key_name: "storm",
    groups: [ "default" ],
    tags: { 'Name' => "" }


Mastermind has four basic pieces: a job; a definition; a participant; and a target.


See Jobs in the wiki


See providers in the wiki


See resources in the wiki


Mastermind uses PostgreSQL to store jobs and process definitions, Redis as a queue for workflow processes, and Ruote as the underlying "operating system" for workflow execution.


Mastermind uses the following environment variables for configuration:

Mastermind settings

  • MASTERMIND_NOISY - Whether workflow debug info should be emitted to the logs. Default is false.
  • MASTERMIND_LOG_LEVEL="info" - The Mastermind log level. Default is info.

AWS providers

  • AWS_ACCESS_KEY_ID - AWS access key id
  • AWS_SECRET_ACCESS_KEY - AWS secret access key

Campfire participant

  • CAMPFIRE_ROOM - Campfire room ID
  • CAMPFIRE_ACCOUNT - Campfire account name
  • CAMPFIRE_TOKEN - Campfire API token

Chef providers

  • CHEF_SERVER_URL - Chef server URL. Remember to include the port if applicable.
  • CHEF_CLIENT_NAME - Chef client name
  • CHEF_CLIENT_KEY - Chef client key (the key itself, not the path). Example: cat /Users/admin/.chef/admin.pem



heroku create -s cedar
heroku addons:add heroku-postgresql:dev
heroku addons:add redistogo
heroku config:set MASTERMIND_NOISY=[...]
heroku config:set MASTERMIND_LOG_LEVEL=[...]
heroku config:set AWS_ACCESS_KEY_ID=[...]
heroku config:set AWS_SECRET_ACCESS_KEY=[...]
heroku config:set CAMPFIRE_ACCOUNT=[...]
heroku config:set CAMPFIRE_ROOM=[...]
heroku config:set CAMPFIRE_TOKEN=[...]
heroku config:set CHEF_SERVER_URL=[...]
heroku config:set CHEF_CLIENT_NAME=[...]
heroku config:set CHEF_CLIENT_KEY=[...]
git push heroku master
heroku run rake db:migrate
heroku scale web=1
heroku scale worker=1


Mastermind provides a REST-ish JSON API for job and definition management. Please see the API wiki for details.

API Client

raise NotImplementedError, "Documentation coming soon!"

Custom providers/resources

raise NotImplementedError, "Documentation coming soon!"