Find the location of the Vagrant installation. On OS X for example, Vagrant is typically installed in /Applications/Vagrant/. The Vagrant installation contains a folder named embedded/ that contains the Ruby runtime used by Vagrant.

In a terminal window, execute a version command on the embedded Ruby. To do this, change directories to /Applications/Vagrant/embedded/bin and execute:

./ruby –version

This will return a value of the Ruby runtime. In this case, OS X package, Vagrant 1.6.5) of:

Set up a development version of Ruby. The simplest method can be to download, install, and configure a package from the Ruby website, but installing a tool such as rbenv (http://rbenv.org) can make Ruby development and installation of development tools much simpler. There are many ways to install rbenv; on OS X, it can be as simple as using the Homebrew package manager (http://brew.sh) to install using the brew install rbenv command.

The companion ruby-build project (https://github.com/sstephenson/ruby-build) can also be installed using a Homebrew package:

brew install ruby-build

With rbenv/ruby-build installed and configured, we can install the desired version of Ruby with the installation command. In this case, we'll install the version we determined from the Vagrant runtime in an earlier step:

rbenv install 2.0.0p353

With Ruby installed, we can then install the bundler gem that allows us to begin creating our own gems:

gem install bundler

Create a new project in a working directory with the Ruby bundler tool, which might be the simplest way to start:

bundle gem vagrant_hello

There is a naming convention that Vagrant plugins typically use where Vagrant plugins start with vagrant- , but if you are starting with the bundle, the command bundler often interprets dashes to create folders within projects. When starting with the gem command, it might be simpler to create names with an underscore character, then rename them to fit the dash naming convention of Vagrant plugins.

Once the folder structure has been renamed, we should have a file structure that looks like this:

.
├── Gemfile
├── LICENSE.txt
├── README.md
├── Rakefile
├── lib
│   ├── vagrant-hello
│   │   └── version.rb
│   └── vagrant-hello.rb
└── vagrant-hello.gemspec

With the gem dependencies in place, declare dependencies in our Gemfile and gemspec (vagrant-hello.gemspec).

The Gemfile is fairly simple; we simply declare that we wish to use a gemspec file and we will declare the Vagrant source code as well. This gem is not added as a requirement to our plugin gem because we assume that a Vagrant plugin will run within the context of Vagrant itself at runtime. What we will need for development is the code that defines the VagrantPlugin module:

source 'https://rubygems.org'

# Specify your gem's dependencies in vagrant-hello.gemspec
gemspec

gem "vagrant", :git => "git://github.com/mitchellh/vagrant.git"

With the Gemfile written, we can edit the vagrant-hello.gemspec to define some information and development dependencies:

# coding: utf-8
$:.unshift File.expand_path("../lib", __FILE__)

require 'vagrant-hello/version'

Gem::Specification.new do |spec|
  spec.name          = "vagrant-hello"
  spec.version       = VagrantPlugins::Hello::VERSION
  spec.authors       = ["Chad Thompson"]
  spec.email         = ["[email protected]"]
  spec.summary       = "Say Hello"
  spec.description   = "Say Hello"
  spec.homepage      = ""
  spec.license       = "Apache2"
  spec.add_development_dependency "bundler", "~> 1.7"
  spec.add_development_dependency "rake", "~> 10.0"
end

Most of this is gem metadata that describes the gem itself and some information that could be published to a gem repository. We've also declared a few dependencies for development, ensuring that we have the rake and bundle tasks commands available to our project.

Two items to take note of are as follows:

With these dependency files in place, we can install the dependencies (bundler, rake) as well as the Vagrant source code with the simple command:

This will download several Ruby gems as well as download the Vagrant source code from Git to our Ruby runtime.

Modify the version file to match the structure we declared in the gemspec file in the previous step:

module VagrantPlugins
  module Hello
    VERSION = "0.0.1"
  end
end

Note that our version file defines the VERSION variable to be in the VagrantPlugins parent module and the Hello submodule. This will ensure that our plugin defines an extension within the larger Vagrant plugins module that is part of the Vagrant runtime.

Define our "Hello" plugin by creating the plugin.rb file in the lib/ directory. This Ruby file contains a bit of error handling (to ensure that Vagrant is present) and includes our plugin definition:

begin
  require 'vagrant'
  rescue LoadError
  raise 'The vagrant-hello plugin must be run within Vagrant.'
end

module VagrantPlugins::Hello
  class Plugin < Vagrant.plugin('2')
    name 'vagrant-hello'
    description <<-DESC.gsub(/^ +/, '')
      A simple plugin to say hello in the host OS.
    DESC

    config(:hello, :provisioner) do
      require_relative 'config'
      Config
    end

    provisioner(:hello) do
      require_relative 'provisioner'
      Provisioner
    end
  end
end

Note here a few items of syntax:

Define the configuration in config.rb. The config file typically defines how our Vagrantfiles will interact with the plugin. In this case, the accessor :inline attribute allows us to create a configuration parameter named inline in the provisioner block of our Vagrantfile:

module VagrantPlugins::Hello
  class Config < Vagrant.plugin('2', :config)
    attr_accessor :inline

    def initialize
      @inline = UNSET_VALUE
    end

    def finalize!
      @inline = nil if @inline == UNSET_VALUE
    end

    def validate(machine)
      errors = _detected_errors

      unless inline
        errors << ':hello provisioner requires someone to say hello to!'
      end

    end
  end
end

Implement the actions of the provisioner in an additional file named provisioner.rb:

module VagrantPlugins::Hello
  class Provisioner < Vagrant.plugin('2', :provisioner)
    def provision
      result = Vagrant::Util::Subprocess.execute(
          'bash',
          '-c',
          "echo 'Hello #{config.inline}!'",
          :notify => [:stdout, :stderr]
      ) do |io_name, data|
        @machine.env.ui.info "[#{io_name}] #{data}"
      end
    end
  end
end

In this example, the provisioner is very basic; a provision method will simply execute a Bash process within the guest that echoes the "Hello string " with the value of config.inline appended to the output.

Create a simple Vagrantfile to test our new plugin. In this case, we'll also need to tell our Vagrantfile to load the local plugin (gem) file: vagrant-hello.

# -*- mode: ruby -*-
# vi: set ft=ruby :

$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
require 'vagrant-hello'

Vagrant.configure("2") do |config|
  config.vm.box = "puppetlabs/ubuntu-14.04-32-nocm"

  config.vm.provision :hello do |hello|
    hello.inline = 'Chad!'
  end
end

With everything in place, our file structure now looks like this:

.
├── Gemfile
├── Gemfile.lock
├── LICENSE.txt
├── README.md
├── Rakefile
├── Vagrantfile
├── lib
│   ├── vagrant-hello
│   │   ├── config.rb
│   │   ├── plugin.rb
│   │   ├── provisioner.rb
│   │   └── version.rb
│   └── vagrant-hello.rb
└── vagrant-hello.gemspec