Plugin Development: Providers

This page documents how to add support for new providers to Vagrant, allowing Vagrant to run and manage machines powered by a system other than VirtualBox. Prior to reading this, you should be familiar with the plugin development basics.

Prior to developing a provider you should also be familiar with how providers work from a user standpoint.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

Example Provider: AWS

The best way to learn how to write a provider is to see how one is written in practice. To augment this documentation, please heavily study the vagrant-aws plugin, which implements an AWS provider. The plugin is a good example of how to structure, test, and implement your plugin.

Definition Component

Within the context of a plugin definition, new providers are defined like so:

provider "my_cloud" do
  require_relative "provider"
  Provider
end

Providers are defined with the provider method, which takes a single argument specifying the name of the provider. This is the name that is used with vagrant up to specify the provider. So in the case above, our provider would be used by calling vagrant up --provider=my_cloud.

The block argument then lazily loads and returns a class that implements the Vagrant.plugin(2, :provider) interface, which is covered next.

Provider Class

The provider class should subclass and implement Vagrant.plugin(2, :provider) which is an upgrade-safe way to let Vagrant return the proper parent class.

This class and the methods that need to be implemented are very well documented. The documentation done on the class in the comments should be enough to understand what needs to be done.

Viewing the AWS provider class as well as the overall structure of the plugin is recommended as a strong getting started point.

Instead of going in depth over each method that needs to be implemented, the documentation will cover high-level but important points to help you create your provider.

Box Format

Each provider is responsible for having its own box format. This is actually an extremely simple step due to how generic boxes are. Before explaining you should get familiar with the general box file format.

The only requirement for your box format is that the metadata.json file have a provider key which matches the name of your provider you chose above.

In addition to this, you may put any data in the metadata as well as any files in the archive. Since Vagrant core itself does not care, it is up to your provider to handle the data of the box. Vagrant core just handles unpacking and verifying the box is for the proper provider.

As an example of a couple box formats that are actually in use:

• The virtualbox box format is just a flat directory of the contents of a VBoxManage export command.

• The vmware_fusion box format is just a flat directory of the contents of a vmwarevm folder, but only including the bare essential files for VMware to function.

• The aws box format is just a Vagrantfile defaulting some configuration. You can see an example aws box unpacked here.

Before anything with your provider is even written, you can verify your box format works by doing vagrant box add with it. When you do a vagrant box list you can see what boxes for what providers are installed.

You do not need the provider plugin installed to add a box for that provider.

Actions

Probably the most important concept to understand when building a provider is the provider "action" interface. It is the secret sauce that makes providers do the magic they do.

Actions are built on top of the concept of middleware, which allow providers to execute multiple distinct steps, have error recovery mechanics, as well as before/after behaviors, and much more.

Vagrant core requests specific actions from your provider through the action method on your provider class. The full list of actions requested is listed in the comments of that method on the superclass. If your provider does not implement a certain action, then Vagrant core will show a friendly error, so do not worry if you miss any, things will not explode or crash spectacularly.

Take a look at how the VirtualBox provider uses actions to build up complicated multi-step processes. The AWS provider uses a similar process.

Built-in Middleware

To assist with common tasks, Vagrant ships with a set of built-in middleware. Each of the middleware is well commented on the behavior and options for each, and using these built-in middleware is critical to building a well-behaved provider.

These built-in middleware can be thought of as a standard library for your actions on your provider. The core VirtualBox provider uses these built-in middleware heavily.

Persisting State

In the process of creating and managing a machine, providers generally need to store some sort of state somewhere. Vagrant provides each machine with a directory to store this state.

As a use-case example for this, the VirtualBox provider stores the UUID of the VirtualBox virtual machine created. This allows the provider to track whether the machine is created, running, suspended, etc.

The VMware provider actually copies the entire virtual machine into this state directory, complete with virtual disk drives and everything.

The directory is available from the data_dir attribute of the Machine instance given to initialize your provider. Within middleware actions, the machine is always available via the :machine key on the environment. The data_dir attribute is a Ruby Pathname object.

It is important for providers to carefully manage all the contents of this directory. Vagrant core itself does little to clean up this directory. Therefore, when a machine is destroyed, be sure to clean up all the state from this directory.

Configuration

Vagrant supports provider-specific configuration, allowing for users to finely tune and control specific providers from Vagrantfiles. It is easy for your custom provider to expose custom configuration as well.

Provider-specific configuration is a special case of a normal configuration plugin. When defining the configuration component, name the configuration the same as the provider, and as a second parameter, specify :provider, like so:

config("my_cloud", :provider) do
  require_relative "config"
  Config
end

As long as the name matches your provider, and the second :provider parameter is given, Vagrant will automatically expose this as provider-specific configuration for your provider. Users can now do the following in their Vagrantfiles:

config.vm.provider :my_cloud do |config|
  # Your specific configuration!
end

The configuration class returned from the config component in the plugin is the same as any other configuration plugin, so read that page for more information. Vagrant automatically handles configuration validation and such just like any other configuration piece.

The provider-specific configuration is available on the machine object via the provider_config attribute. So within actions or your provider class, you can access the config via machine.provider_config.

Best practice: Your provider should not require provider-specific configuration to function, if possible. Vagrant practices a strong convention over configuration philosophy. When a user installs your provider, they should ideally be able to vagrant up --provider=your_provider and have it just work.

Parallelization

Vagrant supports parallelizing some actions, such as vagrant up, if the provider explicitly supports it. By default, Vagrant will not parallelize a provider.

When parallelization is enabled, multiple actions may be run in parallel. Therefore, providers must be certain that their action stacks are thread-safe. The core of Vagrant itself (such as box collections, SSH, etc.) is thread-safe.

Providers can explicitly enable parallelization by setting the parallel option on the provider component:

provider("my_cloud", parallel: true) do
  require_relative "provider"
  Provider
end

That is the only change that is needed to enable parallelization.