philc/terraform

Terraform

Terraform is a small goal-oriented Ruby DSL for setting up a machine, similar in purpose to Chef and Puppet, but without the complexity. It's tailored for the kinds of tasks needed for deploying web apps and is designed to be refreshingly easy to understand and debug. You can read through the entire Terraform library in two minutes and know precisely what it will and won't do for you. Its design is inspired by Babushka.

Usage

This is the basic structure of a system provisioning script written using Terraform:

require "terraform_dsl"
include Terraform::DSL

dep "pygments" do
  met? { in_path? "pygmentize" }         # Check if your dependency is met.
  meet { shell "pip install pygments" }  # Install your dependency.
end

...

satisfy_dependencies()

The Terraform DSL provides these functions which are commonly used when provisioning systems to run web services:

For further details, see the source. It's a short, well-documented file and there's no magic.

Installation

1. Install the Terraform gem on your local machine (the machine you're deploying from): gem install terraform

2. Write your system provisioning script using the Terraform DSL.

3. Copy your system provisioning script and the Terraform library (which is a single file) to your remote machine and run it. Do this as part of your deploy script.

You can use the Terraform gem to write the Terraform library out to a single file as part of your deploy script, prior to copying it over to your remote machine:

require "terraform"
Terraform.write_dsl_file("/tmp/staging/my_app/terraform_dsl.rb")

Terraform is designed to be run on a barebones machine with little preinstalled software. The only requirement is that some version (any version) of Ruby is installed on the machine you're provisioning.

Examples

See the Terraform library itself, which makes use of the DSL quite a bit.

Barkeep is a code review system which uses Terraform for provisioning the machines it gets deployed to. You can see its system provisioning script written using Terraform here, and its Fezzik deploy script here.

Plugins

Terraform can be easily extended with custom deps distributed as gems or scripts. A library that defines new Terraform deps should call Terraform.add_plugin(__FILE__) in any file that adds to the Terraform DSL. For example, if you wanted to package a dep as a gem, the contents of your project might look like this:

terraform-yourgem/
`-lib/
  `-terraform/
    `-yourgem.rb

yourgem.rb
----------
require "terraform"

module Terraform
  module DSL
    # Define your deps
  end
end

Terraform.add_plugin(__FILE__)

Then in your application setup script you would write:

require "terraform"
require "terraform/yourgem"

Terraform.write_terraform_files("./terraform")

This will write out the core Terraform DSL plus all required plugins, ready to be required by your bootstrap code on the server.

For more complete example see terraform-rbenv, which reimplements Terraform's existing rbenv deps as a plugin.

Contribute

When developing this gem you can quickly preview and test your changes by loading your local copy of the gem in your project's Gemfile:

gem "terraform", :path => "~/path/to/terraform_checkout"

Credits

• Daniel MacDougall (dmacdougall) -- thanks for the name.
• Caleb Spare (cespare)