119 lines
5.5 KiB
Plaintext
119 lines
5.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Vagrant Disks Configuration
|
|
description: Documentation of various configuration options for Vagrant Disks
|
|
---
|
|
|
|
# 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:
|
|
|
|
```ruby
|
|
config.vm.disk :disk, name: "backup", size: "10GB"
|
|
config.vm.disk :dvd, name: "installer", file: "./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.
|
|
|
|
~> **Warning!** This guide is still being written as we develop this
|
|
new feature for Vagrant. Is something missing, or could this be improved? Please
|
|
let us know on GitHub by opening an issue or open a pull request directly.
|
|
|
|
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.
|