diff --git a/website/source/docs/disks/configuration.html.md b/website/source/docs/disks/configuration.html.md index afbea13b3..015cd5950 100644 --- a/website/source/docs/disks/configuration.html.md +++ b/website/source/docs/disks/configuration.html.md @@ -21,8 +21,7 @@ description: |- 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, triggers with the `:type` option - will be ignored. + for more info. Without this flag enabled, any disks defined will not be configured. Vagrant Disks has several options that allow users to define and attach disks to guests. @@ -43,7 +42,7 @@ the specific provider being used. - 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. -* `type` (symbol) - The type of disk to manage. This option defaults to `:disk`. Please read the provider specific documentation for supported types. +* `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. @@ -72,8 +71,22 @@ If you are a vagrant plugin author who maintains a provider for Vagrant, this sh feature is more fully developed in Vagrant. -- Entry level builtin action `disk` and how to use it as a provider author -- `id` is unique to each disk config object +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 -More information should be coming once the disk feature is more functional. +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. diff --git a/website/source/docs/disks/index.html.md b/website/source/docs/disks/index.html.md index 6c4f6b3f5..ebc4c8faf 100644 --- a/website/source/docs/disks/index.html.md +++ b/website/source/docs/disks/index.html.md @@ -21,8 +21,7 @@ description: |- 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, triggers with the `:type` option - will be ignored. + for more info. Without this flag enabled, any disks defined will not be configured. NOTE: Vagrant disks is currently a future feature for Vagrant that is not yet supported. Some documentation exists here for future reference, however the Disk feature is diff --git a/website/source/docs/disks/usage.html.md b/website/source/docs/disks/usage.html.md index a5e001cdb..123825d2c 100644 --- a/website/source/docs/disks/usage.html.md +++ b/website/source/docs/disks/usage.html.md @@ -21,14 +21,74 @@ description: |- 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, triggers with the `:type` option - will be ignored. + for more info. Without this flag enabled, any disks defined will not be configured. -Below are some very simple examples of how to use Vagrant Disks. +Below are some very simple examples of how to use Vagrant Disks with the VirtualBox provider. -## Examples +## Basic disk examples -- Resizing a disk (primary) -- Attaching a new disk -- Using provider specific options +### Resizing your primary disk + +Sometimes, the primary disk for a guest is not large enough and you will need to +add more space. To resize a disk, you can simply add a config like this below +to expand the size of your guests drive: + +```ruby +config.vm.disk :disk, size: "100GB", primary: true +``` + +Note: the `primary: true` is what tells Vagrant to expand the guests main drive. +Without this option, Vagrant will instead attach a _new_ disk to the guest. + +For example, this Ubuntu guest will now come with 100GB of space, rather than the default: + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + h.vm.disk :disk, size: "100GB", primary: true + end +end +``` + +It should be noted that due to how VirtualBox functions, it is not possible to shrink +the size of a disk. + +### Attaching new disks + +Vagrant can attach multiple disks to a guest using the VirtualBox provider. An example +of attaching a single disk to a guest with 10 GB of storage can be found below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + h.vm.disk :disk, size: "10GB", name: "extra_storage" + end +end +``` + +Optionally, if you need to attach many disks, you can use Ruby to generate multiple +disks for Vagrant to create and attach to your guest: + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + (0..3).each do |i| + h.vm.disk :disk, size: "5GB", name: "disk-#{i}" + end + end +end +``` + +Note: Virtualbox only allows for up to 30 disks to be attached to a given SATA Controller, +and this number includes the primary disk! Attempting to configure more than 30 will +result in a Vagrant error. diff --git a/website/source/docs/disks/virtualbox/usage.html.md b/website/source/docs/disks/virtualbox/usage.html.md index f984dc740..9c30df11b 100644 --- a/website/source/docs/disks/virtualbox/usage.html.md +++ b/website/source/docs/disks/virtualbox/usage.html.md @@ -8,3 +8,19 @@ description: |- --- # Usage + +
+ Warning! 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="virtualbox_disk_hdd" + ``` + + 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. +