vaguerent/website/source/docs/plugins/providers.html.md

---
layout: "docs"
page_title: "Custom Providers - Plugin Development"
sidebar_current: "plugins-providers"
description: |-
	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.
---

# Plugin Development: Providers

This page documents how to add support for new [providers](/docs/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](/docs/plugins/development-basics.html).

Prior to developing a provider you should also be familiar with how
[providers work](/docs/providers/) from
a user standpoint.

<div class="alert alert-warning">
	<strong>Warning: Advanced Topic!</strong> Developing plugins is an
	advanced topic that only experienced Vagrant users who are reasonably
	comfortable with Ruby should approach.
</div>

## 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](https://github.com/mitchellh/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:

```ruby
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](https://github.com/mitchellh/vagrant/blob/master/lib/vagrant/plugin/docs/provider.rb). The documentation done on the class in the comments should be
enough to understand what needs to be done.

Viewing the [AWS provider class](https://github.com/mitchellh/vagrant-aws/blob/master/lib/vagrant-aws/provider.rb) as well as the
[overall structure of the plugin](https://github.com/mitchellh/vagrant-aws) 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](/docs/boxes/format.html).

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](https://github.com/mitchellh/vagrant-aws/tree/master/example_box).

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.

<a name="actions"></a>
## 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](https://github.com/mitchellh/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](https://github.com/mitchellh/vagrant/blob/master/plugins/providers/virtualbox/action.rb#L287). The AWS provider [uses a similar process](https://github.com/mitchellh/vagrant-aws/blob/master/lib/vagrant-aws/action.rb).

## Built-in Middleware

To assist with common tasks, Vagrant ships with a set of
[built-in middleware](https://github.com/mitchellh/vagrant/tree/master/lib/vagrant/action/builtin). 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](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/pathname/rdoc/Pathname.html) 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](/docs/providers/configuration.html),
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](/docs/plugins/configuration.html). 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](/docs/plugins/configuration.html),
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`.

<div class="alert alert-info">
	<strong>Best practice:</strong> Your provider should <em>not require</em>
	provider-specific configuration to function, if possible. Vagrant
	practices a strong <a href="https://en.wikipedia.org/wiki/Convention_over_configuration">convention over configuration</a>
	philosophy. When a user installs your provider, they should ideally
	be able to <code>vagrant up --provider=your_provider</code> and
	have it just work.
</div>

## 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](#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:

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

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