Vagrant::DSL

Tools for programmatically driving vagrant in rake and in ruby scripts.

Installation

Add this line to your application's Gemfile:

gem 'vagrant-dsl'

And then execute:

$ bundle

Or install it yourself as:

$ gem install vagrant-dsl

Usage

vagrant-dsl provides several top-level primitives for use in normal scripts and in Rakefiles. This provides a few advantages from an application speed perspective over shelling out, and also provides us with a little more flexibility configuring metadata about each VM.

Here's an example:

#!ruby

# These two are equivalent, see below
vagrant_box 'list'
vagrant "box", "list"

#
# This brings up a box, executes ls on a ssh into that box, and destroys a box.
# All the vagrant chatter is presented as strings to stdout and stderr
# respectively (which is nice if you have, say, a test suite associated with
# this function)

status = nil
stdout, stderr = vagrant_capture do
                   if vagrant_up
                     status = vagrant_ssh %w[-c ls]
                     vagrant_destroy '-f'
                   end
                 end

# we only care about seeing output if we have a problem
unless status == 0
  puts "There was an error! Here's the output from vagrant:"
  puts "--- stdout ---"
  puts stdout
  puts "--- stderr ---"
  puts stderr
end

In case it needs re-iterating, you can supply any one-level command as vagrant_$command, which is just sugar for vagrant($command, *args). These are generated at require-time and will include any integrated Vagrant command plugins you have installed.

Integration

Vagrant::DSL also integrates with a few external dependencies:

If Rake is already required (for example, through launching a Rakefile), Vagrant::DSL will be available to task, namespace, etc.
Vagrant::Prison is a way to sandbox vagrant runs. You can use it with the vagrant_prison keyword like so:

#!ruby
vagrant_prison do
  configure do |config|
    config.vm.box = "ubuntu"

    config.vm.define :test, :primary => true do |test_config|
      test_config.vm.network :hostonly, "192.168.33.10"
    end
  end
  stdout, stderr = vagrant_capture do
    vagrant_up
    vagrant_destroy '-f'
  end
end

Note that you can use all the base DSL methods inside vagrant_prison. vagrant_prison takes three arguments supplied as key/value arguments:

:dir is a directory name that will be created, populated, and destroyed if :auto_destroy is set.
If :auto_destroy is set to true (the default), as soon as the prison expires (either through termination of the script or garbage collection) vagrant will be asked to destroy the VMs and the directory will be removed.
If :ui_class is supplied, you can drive the Vagrant user interface with custom UI classes.

The configure method is basically what you would normally put in your Vagrantfile. If you don't like the block form or would rather use a corpus of pre-generated content, it also accepts a string.

vagrant_prison will return a Vagrant::Prison object, which you can manipulate further. See the docs for Vagrant::Prison for more information.

If you wish to use Vagrant::DSL in your own classes/modules, just include it.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request