A Test Kitchen Driver for Vagrant.
This driver works by generating a single Vagrantfile for each instance in a sandboxed directory. Since the Vagrantfile is written out on disk, Vagrant needs absolutely no knowledge of Test Kitchen. So no Vagrant plugins are required.
A Vagrant version of 1.1.0 or higher is required for this driver which means that a native package must be installed on the system running Test Kitchen.
If you are creating Windows VMs over a WinRM Transport, then the vagrant-winrm Vagrant plugin must be installed. As a consequence, the minimum version of Vagrant required is 1.6 or higher.
Provider | vagrant plugin | Paid |
---|---|---|
VirtualBox | built-in | N |
VMware Fusion | vagrant-vmware-fusion | Y |
VMware Workstation | vagrant-vmware-workstation | Y |
Parallels Desktop | vagrant-parallels | Y (plugin free) |
Hyper-V | n/a | N |
If you would like to use VMware Fusion or Workstation you must purchase the software from VMware and also purchase the corresponding Vagrant VMware Plugin.
If using the ChefDK, kitchen-vagrant is already installed. If using an existing Ruby install:
gem install kitchen-vagrant
For a set of platforms and hypervisors, boxes are published under the Bento organization on Vagrant Cloud which serve as the default boxes for common platforms:
---
platforms:
- name: ubuntu-16.04
- name: centos-7
- name: freebsd-11
This will effectively generate a configuration similar to:
---
platforms:
- name: ubuntu-16.04
driver:
box: bento/ubuntu-16.04
- name: centos-7
driver:
box: bento/centos-7
- name: freebsd-11
driver:
box: bento/freebsd-11
# ...
Any other platform names will set a more reasonable default for box
and leave box_url
unset. For example:
---
platforms:
- name: slackware-14.1
- name: openbsd-5.6
- name: windows-2012r2
This will effectively generate a configuration similar to:
---
platforms:
- name: slackware-14.1
driver:
box: slackware-14.1
- name: openbsd-5.6
driver:
box: openbsd-5.6
- name: windows-2012r2
driver:
box: windows-2012r2
As Hyper-V is an exclusive hypervisor, it is recomended that the environment variable VAGRANT_DEFAULT_PROVIDER
be set to hyperv
. Vagrant currently requires user input to choose a virtual switch so we try to detect this automatically and use a workaround. If no network configuration is provided, we check:
- environment variable
KITCHEN_HYPERV_SWITCH
- If on Windows 10 Fall Creators Update, use the built-in 'Default Switch'
- the first switch returned
If VAGRANT_DEFAULT_PROVIDER
is set and the above logic has a valid virtual switch, no additional configuration is needed. This will effectively generate a configuration similar to:
driver:
name: vagrant
provider: hyperv
network:
- ["public_network", bridge: "Default Switch"]
Enable and configure scope for vagrant-cachier plugin.
Valid options are :box
or :machine
, setting to a truthy value yields :box
For example:
---
driver:
cachier: true
will generate a Vagrantfile configuration similar to:
config.cache.scope = :box
The default is nil
, indicating unset.
Required This determines which Vagrant box will be used. For more details, please read the Vagrant machine settings page.
The default will be computed from the platform name of the instance. However,
for a number of common platforms in the Bento project, the default will
prefix the name with bento/
in accordance with Vagrant Cloud naming standards.
For example, a platform with name ubuntu-16.04
will produce a
default box
value of bento/ubuntu-16.04
. Alternatively, a box called
slackware-14.1
will produce a default box
value of slackware-14.1
.
Whether to check for box updates (enabled by default).
A box_url is not required when using the Vagrant Cloud format of
bento/ubuntu-16.04
assuming the organization and box referenced
exist. If using a custom box this can be an https://
or file://
URL.
Path relative to the .kitchen.yml
file for locating the trusted CA bundle.
Useful when combined with box_url
.
The default is nil
, indicating to use the default Mozilla CA cert bundle.
See also box_download_insecure
.
If true, then SSL certificates from the server will not be verified.
The default is false
, meaning if the URL is an HTTPS URL,
then SSL certs will be verified.
The version of the configured box.
The default is nil
, indicating unset.
This option is only relevant when used with Vagrant Cloud boxes which support versioning.
Note: It should largely be the responsibility of the underlying Vagrant
base box to properly set the config.vm.communicator
value. For example, if
the base box is a Windows operating system and does not have an SSH service
installed and enabled, then Vagrant will be unable to even boot it (using
vagrant up
), without a custom Vagrantfile. If you are authoring a base box,
please take care to set your value for communicator to give your users the best
possible out-of-the-box experience.
For overriding the default communicator setting of the base box.
For example:
---
driver:
communicator: ssh
will generate a Vagrantfile configuration similar to:
config.vm.communicator = "ssh"
The default is nil
assuming ssh will be used.
A Hash of customizations to a Vagrant virtual machine. Each key/value
pair will be passed to your providers customization block. For example, with
the default virtualbox
provider:
---
driver:
customize:
memory: 1024
cpuexecutioncap: 50
will generate a Vagrantfile configuration similar to:
Vagrant.configure("2") do |config|
# ...
config.vm.provider :virtualbox do |virtualbox|
virtualbox.customize ["modifyvm", :id, "--memory", "1024"]
virtualbox.customize ["modifyvm", :id, "--cpuexecutioncap", "50"]
end
end
Please read the "Customizations" sections for VirtualBox and VMware for more details.
Adding the createhd
and storageattach
keys in customize
allows for creation
of additional disks in VirtualBox. Full paths must be used as required by VirtualBox.
Adding the storagectl
key in customize
allows for creation or customization of
disks controller in Virtualbox.
NOTE: IDE Controller based drives always show up in the boot order first, regardless of if they are bootable.
driver:
customize:
createhd:
- filename: /tmp/disk1.vmdk
size: 1024
- filename: /tmp/disk2.vmdk
size: 2048
storagectl:
- name: IDE Controller
portcount: 4
storageattach:
- storagectl: IDE Controller
port: 1
device: 0
type: hdd
medium: /tmp/disk2.vmdk
- storagectl: IDE Controller
port: 1
device: 1
type: hdd
medium: /tmp/disk2.vmdk
will generate a Vagrantfile configuration similar to:
Vagrant.configure("2") do |config|
# ...
config.vm.provider :virtualbox do |virtualbox|
virtualbox.customize ["createhd", "--filename", "./tmp/disk1.vmdk", "--size", 1024]
virtualbox.customize ["storagectl", :id, "--name", "IDE Controller", "--portcount", 4]
virtualbox.customize ["storageattach", :id, "--storagectl", "IDE Controller", "--port", "1", "--device", 0, "--type", "hdd", "--medium", "./tmp/disk1.vmdk"]
end
end
Please read createhd , storageattach and storagectl for additional information on these options.
Note: It should largely be the responsibility of the underlying Vagrant
base box to properly set the config.vm.guest
value. For example, if the base
box is a Windows operating system, then Vagrant will be unable to even boot it
(using vagrant up
), without a custom Vagrantfile. If you are authoring a base
box, please take care to set your value for communicator to give your users the
best possible out-of-the-box experience.
For overriding the default guest setting of the base box.
The default is unset, or nil
.
Allows GUI mode for each defined platform. Default is nil. Value is passed
to the config.vm.provider
but only for the VirtualBox and VMware-based
providers.
---
platforms:
- name: ubuntu-16.04
driver:
gui: true
will generate a Vagrantfile configuration similar to:
Vagrant.configure("2") do |config|
# ...
c.vm.provider :virtualbox do |p|
p.gui = true
end
end
For more info about GUI vs. Headless mode please see vagrant configuration docs
Allows to use linked clones to import boxes for VirtualBox, VMware, Parallels Desktop and Hyper-V. Default is nil.
---
platforms:
- name: ubuntu-16.04
driver:
linked_clone: true
will generate a Vagrantfile configuration similar to:
Vagrant.configure("2") do |config|
# ...
c.vm.provider :virtualbox do |p|
p.linked_clone = true
end
end
Vagrant.configure("2") do |config|
# ...
c.vm.provider :hyperv do |p|
p.differencing_disk = true
end
end
An Array of network customizations for the virtual machine. Each Array
element is itself an Array of arguments to be passed to the config.vm.network
method. For example:
---
driver:
network:
- ["forwarded_port", {guest: 80, host: 8080}]
- ["private_network", {ip: "192.168.33.33"}]
will generate a Vagrantfile configuration similar to:
Vagrant.configure("2") do |config|
# ...
config.vm.network :forwarded_port, guest: 80, host: 8080
config.vm.network :private_network, ip: "192.168.33.33"
end
Please read the Vagrant networking basic usage page for more details.
The default is an empty Array, []
.
An optional hook to run a command immediately prior to the
vagrant up --no-provisioner
command being executed.
There is an optional token, {{vagrant_root}}
that can be used in the
pre_create_command
string which will be expanded by the driver to be the full
path to the sandboxed Vagrant root directory containing the Vagrantfile. This
command will be executed from the directory containing the .kitchen.yml file,
or the kitchen_root
.
For example, if your project requires Bindler, this command could be:
---
driver
pre_create_command: cp .vagrant_plugins.json {{vagrant_root}}/ && vagrant plugin bundle
The default is unset, or nil
.
This determines which Vagrant provider to use. The value should match
the provider name in Vagrant. For example, to use VMware Fusion the provider
should be vmware_fusion
. Please see the docs on providers
for further details.
By default the value is unset, or nil
. In this case the driver will use the
Vagrant default provider which at this current time
is virtualbox
unless set by VAGRANT_DEFAULT_PROVIDER
environment variable.
Set to true if you want to do the provision of vagrant in create. Useful in case of you want to customize the OS in provision phase of vagrant
This is the path to the private key file used for SSH authentication if you would like to use your own private ssh key instead of the default vagrant insecure private key.
If this value is a relative path, then it will be expanded relative to the location of the main Vagrantfile. If this value is nil, then the default insecure private key that ships with Vagrant will be used.
The default value is unset, or nil
.
Allow the user to specify a collection of synced folders on each Vagrant instance. Source paths can be relative to the kitchen root.
The default is an empty Array, or []
. The example:
---
driver:
synced_folders:
- ["data/%{instance_name}", "/opt/instance_data"]
- ["/host_path", "/vm_path", "create: true, type: :nfs"]
will generate a Vagrantfile configuration similar to:
Vagrant.configure("2") do |config|
# ...
c.vm.synced_folder "/Users/mray/cookbooks/pxe_dust/data/default-ubuntu-1204", "/opt/instance_data"
c.vm.synced_folder "/host_path", "/vm_path", create: true, type: :nfs
end
Customize the cache directory on the Vagrant instance. This parameter must be an absolute path.
The defaults are:
- Windows:
C:\\omnibus\\cache
- Unix:
/tmp/omnibus/cache
The example:
---
driver:
cache_directory: Z:\\custom\\cache
To disable usage of cache directory set cache_directory
parameter to false
.
Customize the kitchen cache directory on the system running Test Kitchen. This parameter must be an absolute path.
The defaults are:
- Windows:
~/.kitchen/cache
- Unix:
~/.kitchen/cache
The example:
---
driver:
kitchen_cache_directory: Z:\\custom\\kitchen_cache
An alternate Vagrantfile ERB template that will be rendered for use by this
driver. The binding context for the ERB processing is that of the Driver
object, which means that methods like config[:kitchen_root]
, instance.name
,
and instance.provisioner[:run_list]
can be used to compose a custom
Vagrantfile if necessary.
Warning: Be cautious when going down this road as your setup may cease to be portable or applicable to other Test Kitchen Drivers such as Ec2 or Docker. Using the alternative Vagrantfile template strategy may be a dangerous road--be aware.
The default is to use a template which ships with this gem.
An array of paths to other Vagrantfiles to be merged with the default one. The paths can be absolute or relative to the .kitchen.yml file.
Note: the Vagrantfiles must have a .rb extension to satisfy Ruby's Kernel#require.
---
driver:
vagrantfiles:
- VagrantfileA.rb
- /tmp/VagrantfileB.rb
Sets the internal hostname for the instance. This is not used when connecting to the Vagrant virtual machine.
For more details on this setting please read the config.vm.hostname section of the Vagrant documentation.
To prevent this value from being rendered in the default Vagrantfile, you can
set this value to false
.
The default will be computed from the name of the instance. For example, the
instance was called "default-fuzz-9" will produce a default vm_hostname
value
of "default-fuzz-9"
. For Windows-based platforms, a default of nil
is used
to save on boot time and potential rebooting.
The following providers are reported to work but are unsupported:
- CloudStack via vagrant-cloudstack
- KVM/Libvirt via vagrant-libvirt
- LXC via vagrant-lxc
- OpenStack
- RackSpace via vagrant-rackspace
- SoftLayer via vagrant-softlayer
- Source hosted at GitHub
- Report issues/questions/feature requests on GitHub Issues
Pull requests are very welcome! Make sure your patches are well tested. Ideally create a topic branch for every separate change you make. For example:
- Fork the repo
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Created by Fletcher Nichol (fnichol@nichol.ca)
Apache 2.0 (see LICENSE)