Configuration

Vagrant Disks has several options that allow users to define and attach disks to guests.

Disk Options

• disk_ext (string) - Optional argument that defines what kind of file extension a disk should have. Defaults to "vdi" if unspecified. For a list of supported disk extensions, please check the specific provider being used. Not used for type :dvd.

• file (string) - For type :dvd, this is a required argument that should point to an .iso file on the host machine. For type :disk, this is an optional argument that can point to the location of a disk file that already exists.

• name (string) - Required option to give the disk a name. This name will also be used as the filename when creating a virtual hard disk.

• primary (boolean) - Optional argument that configures a given disk to be the "primary" disk to manage on the guest. There can only be one primary disk per guest, and it must be of type :disk. Defaults to false if not specified.

• provider_config (hash) - Additional provider specific options for managing a given disk. Please refer to the provider specific documentation to see any available provider_config options.

  Generally, the disk option accepts two kinds of ways to define a provider config:

  • providername__diskoption: value
    • The provider name followed by a double underscore, and then the provider specific option for that disk
  • {providername: {diskoption: value}, otherprovidername: {diskoption: value}
    • A hash where the top level key(s) are one or more providers, and each provider keys values are a hash of options and their values.

• size (String) - The size of the disk to create. For example, "10GB". Not used for type :dvd.

  Note: More specific examples of these can be found under the provider specific disk page. The provider_config option will depend on the provider you are using. Please read the provider specific documentation for disk management to learn about what options are available to use.

Disk Types

The disk config currently accepts three kinds of disk types:

• disk (symbol)
• dvd (symbol)
• floppy (symbol)

NOTE: These types depend on the provider used, and may not yet be functional. Please refer to the provider specific implementation for more details for what is supported.

You can set a disk type with the first argument of a disk config in your Vagrantfile:

config.vm.disk :disk, name: "backup", size: "10GB"
config.vm.disk :dvd, name: "installer", path: "./installer.iso"
config.vm.disk :floppy, name: "cool_files"

Provider Author Guide

If you are a vagrant plugin author who maintains a provider for Vagrant, this short guide will hopefully give some information on how to use the internal disk config object.

All providers must implement the capability configure_disks, and cleanup_disks. These methods are responsible for the following:

• configure_disks - Reads in a Vagrant config for defined disks from a Vagrantfile, and creates and attaches the disks based on the given config
• cleanup_disks - Compares the current Vagrant config for defined disks and detaches any disks that are no longer valid for a guest.

These methods are called in the builtin Vagrant actions Disk and CleanupDisks. If the provider does not support these capabilities, they will be skipped over and no disks will be configured. It is the providers job to implement these provider capabilities and handle the methods required to support disk creation and deletion. Vagrant will handle parsing and supplying the config object based on what has been defined inside a users Vagrantfile.

For a more detailed example of how to use this disk configuration with Vagrant, please check out how it was implemented using the VirtualBox provider.

The disk_meta file

Both builtin disk actions configure_disks and cleanup_disks expect to read and write down a disk_meta file inside a machines data dir. This file is specifically for keeping track of the last configured state for disks in a given provider. Generally, this file is used as a way for Vagrant to keep track of what disks are being managed by Vagrant with the provider uses, so that it does not accidentally delete or manage disks that were configured outside of Vagrants configuration.

For the VirtualBox provider, Vagrant uses this file to see what disks were configured on the last run of Vagrant, and compares that to the current configured state for the Vagrantfile on the current run of Vagrant. It specifically stores each disks UUID and disk name for use. If it notices a disk that is no longer in the Vagrantfile, it can be assumed that the disk is no longer valid for that guest, and cleans up the disk.

This may not be required for your provider, however with the VirtualBox provider, Vagrant needs a way to keep track of the defined disks managed by Vagrant and their disk UUIDs that VirtualBox uses to keep track of these disks.

The provider_config hash

The disk config class supports an optional hash of options called provider_config. This allows the user to define some additional options for a provider to use that may be non-standard across different providers.