tnargav 1.2.3 → 1.3.3

data/website/docs/source/v2/plugins/providers.html.md

@@ -0,0 +1,234 @@
+---
+page_title: "Custom Providers - Plugin Development"
+sidebar_current: "plugins-providers"
+---
+
+# Plugin Development: Providers
+
+This page documents how to add support for new [providers](/v2/providers/index.html)
+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](/v2/plugins/development-basics.html).
+
+Prior to developing a provider you should also be familiar with how
+[providers work](/v2/providers/index.html) from
+a user standpoint.
+
+<div class="alert alert-warn">
+	<p>
+		<strong>Warning: Advanced Topic!</strong> Developing plugins is an
+		advanced topic that only experienced Vagrant users who are reasonably
+		comfortable with Ruby should approach.
+	</p>
+</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/v2/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](/v2/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 doesn't 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 doesn't implement a certain action, then Vagrant core will show
+a friendly error, so don't worry if you miss any, things won't 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](/v2/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](/v2/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](/v2/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">
+	<p>
+		<strong>Best practice:</strong> Your provider should <em>not require</em>
+		provider-specific configuration to function, if possible. Vagrant
+		practices a strong <a href="http://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.
+	</p>
+</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.

data/website/docs/source/v2/plugins/provisioners.html.md

@@ -0,0 +1,64 @@
+---
+page_title: "Custom Provisioners - Plugin Development"
+sidebar_current: "plugins-provisioners"
+---
+
+# Plugin Development: Provisioners
+
+This page documents how to add new [provisioners](/v2/provisioning/index.html) to Vagrant,
+allowing Vagrant to automatically install software and configure software
+using a custom provisioner. Prior to reading this, you should be familiar
+with the [plugin development basics](/v2/plugins/development-basics.html).
+
+<div class="alert alert-warn">
+	<p>
+		<strong>Warning: Advanced Topic!</strong> Developing plugins is an
+		advanced topic that only experienced Vagrant users who are reasonably
+		comfortable with Ruby should approach.
+	</p>
+</div>
+
+## Definition Component
+
+Within the context of a plugin definition, new provisioners can be defined
+like so:
+
+```ruby
+provisioner "custom" do
+  require_relative "provisioner"
+  Provisioner
+end
+```
+
+Provisioners are defined with the `provisioner` method, which takes a
+single argument specifying the name of the provisioner. This is the
+name that used with `config.vm.provision` when configuring and enabling
+the provisioner. So in the case above, the provisioner would be enabled
+using `config.vm.provision :custom`.
+
+The block argument then lazily loads and returns a class that implements
+the `Vagrant.plugin(2, :provisioner)` interface, which is covered next.
+
+## Provisioner Class
+
+The provisioner class should subclass and implement
+`Vagrant.plugin(2, :provisioner)` which is an upgrade-safe way to let
+Vagrant return the proper parent class for provisioners.
+
+This class and the methods that need to be implemented are
+[very well documented](https://github.com/mitchellh/vagrant/blob/master/lib/vagrant/plugin/v2/provisioner.rb).
+The documentation on the class in the comments should be enough
+to understand what needs to be done.
+
+There are two main methods that need to be implemented: the
+`configure` method and the `provision` method.
+
+The `configure` method is called early in the machine booting process
+to allow the provisioner to define new configuration on the machine, such
+as sharing folders, defining networks, etc. As an example, the
+[Chef solo provisioner](https://github.com/mitchellh/vagrant/blob/master/plugins/provisioners/chef/provisioner/chef_solo.rb#L24)
+uses this to define shared folders.
+
+The `provision` method is called when the machine is booted and ready
+for SSH connections. In this method, the provisioner should execute
+any commands that need to be executed.

data/website/docs/source/v2/plugins/usage.html.md

@@ -0,0 +1,58 @@
+---
+page_title: "Plugin Usage - Plugins"
+sidebar_current: "plugins-usage"
+---
+
+# Plugin Usage
+
+Installing a plugin is easy, and shouldn't take more than a few seconds.
+
+Please refer to the documentation of any plugin you plan on using for
+more information on how to use it, but there is one common method for
+installation and plugin activation.
+
+<div class="alert alert-warn">
+	<p>
+		<strong>Warning!</strong> 3rd party plugins can introduce instabilities
+		into Vagrant due to the nature of them being written by non-core users.
+	</p>
+</div>
+
+## Installation
+
+Plugins are installed using `vagrant plugin install`:
+
+```
+$ vagrant plugin install vagrant-example-plugin
+...
+```
+
+Once a plugin is installed, it will automatically be loaded by Vagrant.
+Plugins which cannot be loaded shouldn't crash Vagrant. Instead,
+Vagrant will show an error message that a plugin failed to load.
+
+## Usage
+
+Once a plugin is installed, you should refer to the plugin's documentation
+to see exactly how to use it. Plugins which add commands should be instantly
+available via `vagrant`, provisioners should be available via
+`config.vm.provision`, etc.
+
+**Note:** In the future, the `vagrant plugin` command will include a
+subcommand that will document the components that each plugin installs.
+
+## Uninstallation
+
+Uninstalling a plugin is as easy as installing it. Just use the
+`vagrant plugin uninstall` command and the plugin will be removed. Example:
+
+```
+$ vagrant plugin uninstall vagrant-example-plugin
+...
+```
+
+## Listing Plugins
+
+To view what plugins are installed into your Vagrant environment at
+any time, use the `vagrant plugin list` command. This will list the plugins
+that are installed along with their version.

data/website/docs/source/v2/providers/basic_usage.html.md

@@ -0,0 +1,67 @@
+---
+page_title: "Basic Usage - Providers"
+sidebar_current: "providers-basic-usage"
+---
+
+# Basic Provider Usage
+
+## Boxes
+
+Boxes are all provider-specific. A box for VirtualBox is incompatible with
+the VMware Fusion provider, or any other provider. A box must be installed
+for each provider, and can share the same name as other boxes as long
+as the providers differ. So you can have both a VirtualBox and VMware Fusion
+"precise64" box.
+
+Installing boxes hasn't changed at all:
+
+```
+$ vagrant box add \
+  precise64 http://files.vagrantup.com/precise64.box
+```
+
+Vagrant now automatically detects what provider a box is for. This is
+visible when listing boxes. Vagrant puts the provider in parentheses next
+to the name, as can be seen below.
+
+```
+$ vagrant box list
+precise64 (virtualbox)
+precise64 (vmware_fusion)
+```
+
+## Vagrant Up
+
+Once a provider is installed, it is used by calling `vagrant up` with the `--provider` flag,
+specifying the provider you want to back the machine. No other configuration
+is necessary! What this looks like:
+
+```
+$ vagrant up --provider=vmware_fusion
+```
+
+If the provider is well-behaved then everything should just work. Of course,
+each provider typically exposes custom configuration options to fine tune
+and control that provider, but defaults should work great to get started.
+
+From this point forward, you can use all the other commands without
+specifying a `--provider`; Vagrant is able to figure it out on its own.
+Specifically, once you run `vagrant up --provider`, Vagrant is able to see
+what provider is backing an existing machine, so commands such as `destroy`,
+`suspend`, etc. do not need to be told what provider to use.
+
+<div class="alert alert-info">
+	<h3>Limitations</h3>
+	<p>
+		Vagrant currently restricts you to bringing up one provider per machine.
+		If you have a multi-machine environment, you can bring up one machine
+		backed by VirtualBox and another backed by VMware Fusion, for example, but you
+		can't back the <em>same machine</em> with both VirtualBox and
+		VMware Fusion.
+	</p>
+
+	<p>
+		This is a limitation that will be removed in a future version of
+		Vagrant.
+	</p>
+</div>

data/website/docs/source/v2/providers/configuration.html.md

@@ -0,0 +1,89 @@
+---
+page_title: "Configuration - Providers"
+sidebar_current: "providers-configuration"
+---
+
+# Configuration
+
+While well-behaved providers should work with any Vagrantfile with sane
+defaults, providers generally expose unique configuration
+options so that you can get the most out of each provider.
+
+This provider-specific configuration is done within the Vagrantfile
+in a way that is portable, easy to use, and easy to understand.
+
+## Portability
+
+An important fact is that even if you configure other providers within
+a Vagrantfile, the Vagrantfile remains portable even to individuals who
+don't necessarilly have that provider installed.
+
+For example, if you configure VMware Fusion and send it to an individual
+who doesn't have the VMware Fusion provider, Vagrant will silently ignore
+that part of the configuration.
+
+## Provider Configuration
+
+Configuring a specific provider looks like this:
+
+```
+Vagrant.configure("2") do |config|
+  # ... (other config)
+
+  config.vm.provider "virtualbox" do |vb|
+    vb.customize ["modifyvm", :id, "--cpuexecutioncap", "50"]
+  end
+end
+```
+
+Multiple `config.vm.provider` blocks can exist to configure multiple
+providers.
+
+The configuration format should look very similar to how provisioners
+are configured. The `config.vm.provider` takes a single parameter: the
+name of the provider being configured. Then, an inner block with custom
+configuration options is exposed that can be used to configure that
+provider.
+
+This inner configuration differs among providers, so please read the
+documentation for your provider of choice to see available configuration
+options.
+
+Remember, some providers don't require any provider-specific configuration
+and work directly out of the box. Provider-specific configuration is meant
+as a way to expose more options to get the most of the provider of your
+choice. It is not meant as a roadblock to running against a specific provider.
+
+## Overriding Configuration
+
+Providers can also override non-provider specific configuration, such
+as `config.vm.box` and any other Vagrant configuration. This is done by
+specifying a second argument to `config.vm.provider`. This argument is
+just like the normal `config`, so set any settings you want, and they will
+be overriden only for that provider.
+
+Example:
+
+```
+Vagrant.configure("2") do |config|
+  config.vm.box = "precise64"
+
+  config.vm.provider "vmware_fusion" do |v, override|
+    override.vm.box = "precise64_fusion"
+  end
+end
+```
+
+In the above case, Vagrant will use the "precise64" box by default, but
+will use "precise64_fusion" if the VMware Fusion provider is used.
+
+<div class="alert alert-info">
+	<p>
+		<strong>The Vagrant Way:</strong> The proper "Vagrant way" is to
+		avoid any provider-specific overrides if possible by making boxes
+		for multiple providers that are as identical as possible, since box
+		names can map to multiple providers. However, this isn't always possible,
+		and in those cases, overrides are available.
+	</p>
+</div>
+