⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

[!IMPORTANT]
Documentation Update: Product documentation previously located in /website has moved to the hashicorp/web-unified-docs repository, where all product documentation is now centralized. Please make contributions directly to web-unified-docs, since changes to /website in this repository will not appear on developer.hashicorp.com. ⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

Basic Usage

Below are some very simple examples of how to use Vagrant Disks with the VirtualBox provider.

Basic Examples

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:

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:

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 hard 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:

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:

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 has a hard limit on the number of disks that can be attached to a given storage controller, which is defined by the controller type. Attempting to configure more disks than are supported by the primary controller will result in a Vagrant error.

Attaching optical drives

Vagrant can attach .iso files as optical drives using the VirtualBox provider. An example of attaching an optical drive to a guest can be found below:

Vagrant.configure("2") do |config|
  config.vm.define "hashicorp" do |h|
    h.vm.box = "hashicorp/bionic64"
    h.vm.provider :virtualbox

    h.vm.disk :dvd, name: "installer", file: "./installer.iso"
  end
end

As with hard disks, configuring more disks than are supported by your VM's storage controller arrangement will result in a Vagrant error.

Removing Disks

If you have removed a disk from your Vagrant config and wish for it to be detached from the guest, you will need to vagrant reload your guest to apply these changes. NOTE: Removing virtual hard disks created by Vagrant will also delete the medium from your hard drive.