Skip to content

Provider Notes

Jump to bottom
Volker Hilsheimer edited this page Feb 22, 2022 · 11 revisions

Vagrant communicates with different virtualization backends using providers. The default provider is VirtualBox, since it's free and ships out of the box with vagrant.

Other providers that minicoin is tested with are:

The provider can be specified explicitly when bringing up a machine:

$ vagrant up windows10 --provider azure

or in the declaration of the machine in the minicoin.yml file:

- name: windows10
  provider: azure

In the provider setting of the machine declaration you can also make provider specific configurations, which will only apply when the machine is brought up with the respective provider. If you declare settings for multiple providers, the the first provider will be the default provider.

- name: windows10
  provider:
    vmware_desktop:
      # vmware_desktop specific settings
    virtualbox:
      # vbox specific settings

This box will be brought up with VMware Desktop if no provider is explicitly set via the --provider command line option.

You can also set the VAGRANT_DEFAULT_PROVIDER environment to change the default provider for all minicoin runs. If you don't have VirtualBox installed, you should set the default provider to what you want to use instead.

Other providers that vagrant supports might work with just a few adjustments - contributions welcome!

Providers running local VMs

These providers run virtual machines on the local computer, sharing limited resources like CPU and memory with the host OS.

VirtualBox

VirtualBox is the default choice for vagrant; it's free and cross platform, and good enough for most use cases. The minicoin setup script installs VirtualBox version 6.1.26; users have reported issues with later versions, such as errors when trying to create the private network.

When using VirtualBox, you will also need the Oracle VM VirtualBox Extension Pack.

Since it's the default, it's the easiest provider to get started, and it's also the one that minicoin is most actively tested with.

The main disadvantage with VirtualBox is that spinning up machines is slow and requires a lot of disk space, since the entire basebox image is copied. VirtualBox doesn't support nested virtualization, hardware acceleration is not great, and there are no guest additions for macOS virtual machines (so clipboard sharing doesn't work).

VirtualBox specific provisioning

Provide a list of keys and values under the virtualbox provider that should be passed on to the specified command of the VBoxManage tool.

- name: linux
  box: generic/ubuntu1804
  provider:
    virtualbox:
      modifyvm: # command of VBoxManage - see help for details
        - description: "My test machine"

VMware Fusion

VMware Fusion requires the "Vagrant VMware Utility" package. After that utility package has been installed, you can install the Vagrant VMware Desktop provider plugin using the standard plugin installation procedure:

$ vagrant plugin install vagrant-vmware-desktop

Note that this plugin requires a license, which you need to install as well.

To make minicoin use VMware Fusion, specify it explicitly as the provider when bringing a box up:

$ minicoin up windows10 --provider vmware_desktop

Alternatively, specify vmware_desktop as the provider in your box definition:

- name: windows10
  box: tqtc/windows10
  provider: vmware_desktop

Starting a new machine with VMware Fusion is very fast, is it doesn't require a full copy of the basebox image. VMware also supports nested virtualization, which allows running e.g an Android emulator inside a Ubuntu virtual machine. Lastly, macOS is a fully supported guest OS on VMware Fusion, so clipboard sharing with the host works.

However, there are some of hiccups in both VMware Fusion and the vagrant plugin. You might experience frequent issues with the network configuration and port forwarding when frequently creating and destroying machines. Often, re-running the minicoin command works, but sometimes it's necessary to restart the vagrant-vmware-utility services (using launchctl or systemctl), to wipe out configuration files (in /opt/vagrant-vmware-desktop), or even to reboot the host computer to reset the network services.

The following script, plus restarting the Fusion application, often works when running into problems:

if [[ $EUID -ne 0 ]]
then
    >&2 echo "Remember to run as sudo"
    exit 1
fi

/Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --stop
/Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --start
launchctl stop com.vagrant.vagrant-vmware-utility 
launchctl start com.vagrant.vagrant-vmware-utility

VMware specific provisioning

Provide a list of keys and values that should be used as VMX settings under the vmware_desktop provider:

  provider:
    vmware_desktop:
      key: value

Cloud providers

minicoin boxes that are specifically designed for cloud providers are available publicly from the Vagrant Cloud.

Boxes for cloud providers are typically special box files that make cloud specific settings, such as the instance type. The operating systems for the cloud are typically server OSes, and might need some extra provisioning. Making cloud instances accessible over the internet, and at the same time reasonably secure, requires further configuration.

When using a box specifically packaged to be used with the cloud provider, then set the provider attribute in the machine definition:

  - name: ubuntu-on-aws
    box: minicoin/linux-cloud
    provider: aws

Alternatively, pass the --provider option to minicoin up.

With cloud providers, minicoin will disable all folder sharing, as it is either not possible or anyway not desired to share an entire home directory with a remote server. Instead, use the mutagen role to set up folder syncing.

Amazon Web Services

Using AWS with minicoin requires the vagrant-aws plugin to be installed.

$ vagrant plugin install vagrant-aws

In addition, the AWS CLI needs to be installed, and you need to have AWS credentials:

$ aws configure

minicoin checks the setup of the AWS account when validating or starting a machine that uses the AWS provider, testing and if possible correcting the following resources:

  • the account exists
  • a default VPC exists in the account
  • a security group minicoin exists within the default VPC
  • the security group has ingress rules for common ports, allowing connections from the public IP of the current host

Instead of using a minicoin box prepared for AWS, you can install the aws dummy box via

$ vagrant box add aws/dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box

and then use aws/dummy as the box in your machine definition. Finally, apply AWS specific provisioning to specify the image from which the box should be deployed, e.g

  - name: ubuntu-on-aws
    box: aws/dummy
    provider:
      aws:
        ami: ami-0a8e758f5e873d1c1
        instance_type: t2.2xlarge
    roles:
      - role: mutagen
        paths:
        - ~/qt/dev/qtbase

AWS specific provisioning

Use the aws role to provide a list of keys and values that should be used by the provider. The most important ones are:

  • region - the region in which to launch the VM; defaults to eu-west-1, e.g. Ireland
  • ami - the AMI from which the instance should be created
  • instance_type - the instance type, which defines amount of vCPUs and memory available; check the instance catalogue on the AWS console for details and prices.
  • storage - a list of EBS volumes, which can be either a size or snapshot, or a volume ID

See the AWS plugin documentation for a complete list of available settings.

Other AWS settings

Account information and credentials are read from the user's AWS profile, and you can use environment variables to override specific settings:

  • AWS_VM_ADMIN_PASSWORD - the password for the admin user account on the VM

Microsoft Azure

Using Azure with minicoin requires the vagrant-azure plugin to be installed.

$ vagrant plugin install vagrant-azure

In addition, the Azure CLI needs to be installed, and you need to have valid Azure credentials:

$ az login

To confirm that everything is working and that you have access, run

$ az account show
$ az account list-locations --output tsv

Instead of using a minicoin box prepared for Azure, you can install the "dummy" box via

$ vagrant box add azure/dummy https://github.com/azure/vagrant-azure/raw/v2.0/dummy.box --provider azure

and then use azure/dummy as the box in your machine definition. Finally, apply azure specific provisioning to specify the image from which the box should be deployed, e.g

  - name: ubuntu-on-azure
    box: azure/dummy
    provider:
      azure:
        vm_image_urn: canonical:ubuntuserver:18.04-LTS:latest
        vm_size: Standard_D5_v2 # 16 vCPU, 56GB RAM
        data_disks:
          - name: "disk2"
            size_gb: 30
    roles:
      - role: mutagen
        paths:
          - ~/qt/dev/qtbase

Azure specific provisioning

Use the azure role to provide a list of keys and values that should be used by the provider:

  • location - the location in which to launch the VM; defaults to northeurope
  • vm_name - the name the VM should have; generated to be unique by default
  • vm_size - a size as per the Azure documentation
  • vm_image_urn - the name of the image on the Azure marketplace that the VM should use
  • resource_group_name - the name of the Azure resource group; generated to be unique by default

See the Azure plugin documentation for a complete list of available settings.

Other Azure settings

Account information and credentials are read and generated using the Azure CLI, and you can use environment variables to override specific settings:

  • AZURE_VM_ADMIN_PASSWORD - the password for the admin user account on the VM

Welcome to Minicoin

Getting Started

Using Minicoin

Customizing Minicoin

Tutorials

These tutorials assume that you have installed minicoin.

Clone this wiki locally