A new platform for documentation and tutorials is launching soon.
We are migrating Vagrant documentation into HashiCorp Developer, our new developer experience.
Plugin Development Basics
Plugins are a great way to augment or change the behavior and functionality of Vagrant. Since plugins introduce additional external dependencies for users, they should be used as a last resort when attempting to do something with Vagrant.
But if you need to introduce custom behaviors into Vagrant, plugins are the best way, since they are safe against future upgrades and use a stable API.
Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.
Plugins are written using Ruby and are packaged using RubyGems. Familiarity with Ruby is required, but the packaging and distribution section should help guide you to packaging your plugin into a RubyGem.
Setup and Workflow
Because plugins are packaged as RubyGems, Vagrant plugins should be
developed as if you were developing a regular RubyGem. The easiest
way to do this is to use the
bundle gem command.
Once the directory structure for a RubyGem is setup, you will want to modify your Gemfile. Here is the basic structure of a Gemfile for Vagrant plugin development:
source "https://rubygems.org" group :development do gem "vagrant", git: "https://github.com/hashicorp/vagrant.git" end group :plugins do gem "my-vagrant-plugin", path: "." end
This Gemfile gets "vagrant" for development. This allows you to
bundle exec vagrant to run Vagrant with your plugin already loaded,
so that you can test it manually that way.
The only thing about this Gemfile that may stand out as odd is the
"plugins" group and putting your plugin in that group. Because
vagrant plugin commands do not work in development, this is how
you "install" your plugin into Vagrant. Vagrant will automatically
load any gems listed in the "plugins" group. Note that this also
allows you to add multiple plugins to Vagrant for development, if
your plugin works with another plugin.
When you want to manually test your plugin, use
bundle exec vagrant in order to run Vagrant with your plugin
loaded (as we specified in the Gemfile).
All plugins are required to have a definition. A definition contains details about the plugin such as the name of it and what components it contains.
A definition at the bare minimum looks like the following:
class MyPlugin < Vagrant.plugin("2") name "My Plugin" end
A definition is a class that inherits from
Vagrant.plugin("2"). The "2"
there is the version that the plugin is valid for. API stability is only
promised for each major version of Vagrant, so this is important. (The
1.x series is working towards 2.0, so the API version is "2")
The most critical feature of a plugin definition is that it must always load, no matter what version of Vagrant is running. Theoretically, Vagrant version 87 (does not actually exist) would be able to load a version 2 plugin definition. This is achieved through clever lazy loading of individual components of the plugin, and is covered shortly.
Within the definition, a plugin advertises what components it adds to Vagrant. An example is shown below where a command and provisioner are added:
class MyPlugin < Vagrant.plugin("2") name "My Plugin" command "run-my-plugin" do require_relative "command" Command end provisioner "my-provisioner" do require_relative "provisioner" Provisioner end end
Let us go over the major pieces of what is going on here. Note from a general Ruby language perspective the above should be familiar. The syntax should not scare you. If it does, then please familiarize with Ruby further before attempting to write a plugin.
The first thing to note is that individual components are defined by
making a method call with the component name, such as
provisioner. These in turn take some parameters. In the case of our
example it is just the name of the command and the name of the provisioner.
All component definitions then take a block argument (a callback) that
must return the actual component implementation class.
The block argument is where the "clever lazy loading" (mentioned above) comes into play. The component blocks should lazy load the actual file that contains the implementation of the component, and then return that component.
This is done because the actual dependencies and APIs used when defining components are not stable across major Vagrant versions. A command implementation written for Vagrant 2.0 will not be compatible with Vagrant 3.0 and so on. But the definition is just plain Ruby that must always be forward compatible to future Vagrant versions.
To repeat, the lazy loading aspect of plugin components is critical to the way Vagrant plugins work. All components must be lazily loaded and returned within their definition blocks.
Now, each component has a different API. Please visit the relevant section using the navigation to the left under "Plugins" to learn more about developing each type of component.
One of Vagrant's biggest strength is gracefully handling errors and reporting them in human-readable ways. Vagrant has always strongly believed that if a user sees a stack trace, it is a bug. It is expected that plugins will behave the same way, and Vagrant provides strong error handling mechanisms to assist with this.
Error handling in Vagrant is done entirely by raising Ruby exceptions.
But Vagrant treats certain errors differently than others. If an error
is raised that inherits from
Vagrant::Errors::VagrantError, then the
vagrant command will output the message of the error in nice red text
to the console and exit with an exit status of 1.
Otherwise, Vagrant reports an "unexpected error" that should be reported as a bug, and shows a full stack trace and other ugliness. Any stack traces should be considered bugs.
Therefore, to fit into Vagrant's error handling mechanisms, subclass
VagrantError and set a proper message on your exception. To see
examples of this, look at Vagrant's built-in errors.
Console Input and Output
Most plugins are likely going to want to do some sort of input/output.
Plugins should never use Ruby's built-in
gets style methods.
Instead, all input/output should go through some sort of Vagrant UI object.
The Vagrant UI object properly handles cases where there is no TTY, output
pipes are closed, there is no input pipe, etc.
A UI object is available on every
Vagrant::Environment via the
and is exposed within every middleware environment via the
:ui key. UI
objects have decent documentation
within the comments of their source.