93 lines
4.2 KiB
Markdown
93 lines
4.2 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Vagrant Disks Configuration"
|
|
sidebar_current: "disks-configuration"
|
|
description: |-
|
|
Documentation of various configuration options for Vagrant Disks
|
|
---
|
|
|
|
# Configuration
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning!</strong> This feature is experimental and may break or
|
|
change in between releases. Use at your own risk. It currently is not officially
|
|
supported or functional.
|
|
|
|
This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to:
|
|
|
|
```
|
|
VAGRANT_EXPERIMENTAL="disk_base_config"
|
|
```
|
|
|
|
Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more
|
|
information about this flag visit the [Experimental docs page](/docs/experimental/)
|
|
for more info. Without this flag enabled, any disks defined will not be configured.
|
|
</div>
|
|
|
|
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. For a list of supported disk extensions, please check
|
|
the specific provider being used.
|
|
* `file` (string) - Optional argument that defines a path on disk pointing to the location of a disk file.
|
|
* `name` (string) - Required option to give the disk a name. This name will be used as a filename when creating the 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.
|
|
* `provider_config` (hash) - Additional provider specific options for managing a given disk.
|
|
|
|
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"`.
|
|
|
|
**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)
|
|
|
|
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 :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.
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning!</strong> This guide is still being written as we develop this
|
|
new feature for Vagrant. Some points below are what we plan on covering once this
|
|
feature is more fully developed in Vagrant.
|
|
</div>
|
|
|
|
TODO: Write a bit here about what the internal disk config object looks like, and
|
|
how to use it. Add code links if possible to the virtualbox disk feature.
|
|
|
|
- `provider_config` and how to its structured and how to use/validate it
|
|
|
|
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.
|
|
|
|
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.
|