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.
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.
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.
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.
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.
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:
virtualbox box format is just a flat directory of the contents of a
VBoxManage export command.
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.
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.
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.
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.
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.
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
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_providerand have it just work.
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.
© 2010–2017 Mitchell Hashimoto
Licensed under the MPL 2.0 License.