KIWI Image Description for Vagrant¶
Vagrant is a framework to implement consistent processing/testing work environments based on Virtualization technologies. To run a system, Vagrant needs so-called boxes. A box is a TAR archive containing a virtual disk image and some metadata.
To build Vagrant boxes, you can use Packer which is provided by Hashicorp itself. Packer is based on the official installation media (DVDs) as shipped by the distribution vendor.
The KIWI way of building images might be helpful, if such a media does not exist or does not suit your needs. For example, if the distribution is still under development or you want to use a collection of your own repositories. Note, that in contrast to Packer KIWI only supports the libvirt and VirtualBox providers. Other providers require a different box layout that is currently not supported by KIWI.
In addition, you can use the KIWI image description as source for the Open Build Service which allows building and maintaining boxes.
Vagrant expects boxes to be setup in a specific way (for details refer to the Vagrant box documentation.), applied to the referenced KIWI image description from Build a Virtual Disk Image, the following steps are required:
Update the image type setup
<type image="vmx" filesystem="ext4" format="vagrant" boottimeout="0"> <vagrantconfig provider="libvirt" virtualsize="42"/> <size unit="G">42</size> </type>
This modifies the type to build a Vagrant box for the libvirt provider including a pre-defined disk size. The disk size is optional, but recommended to provide some free space on disk.
For the VirtualBox provider, the additional attribute
virtualbox_guest_additions_presentcan be set to
truewhen the VirtualBox guest additions are installed in the KIWI image:
<type image="vmx" filesystem="ext4" format="vagrant" boottimeout="0"> <vagrantconfig provider="virtualbox" virtualbox_guest_additions_present="true" virtualsize="42" /> <size unit="G">42</size> </type>
The resulting Vagrant box then uses the
vboxfsmodule for the synchronized folder instead of
rsync, that is used by default.
Add mandatory packages
<package name="sudo"/> <package name="openssh"/>
Add additional packages
If you have set the attribute
true, add the VirtualBox guest additions. For openSUSE the following packages are required:
<package name="virtualbox-guest-tools"/> <package name="virtualbox-guest-x11"/> <package name="virtualbox-guest-kmp-default"/>
Otherwise, you must add
Note that KIWI cannot verify whether these packages are installed. If they are missing, the resulting Vagrant box will be broken.
Add Vagrant user
<users group='vagrant'> <user name='vagrant' password='vh4vw1N4alxKQ' home='/home/vagrant'/> </users>
This adds the vagrant user to the system and applies the name of the user as the password for login.
Integrate public SSH key
Vagrant requires an insecure public key pair 1 to be added to the authorized keys for the user
vagrantso that Vagrant itself can connect to the box via ssh. The key can be obtained from GitHub and should be inserted into the file
home/vagrant/.ssh/authorized_keys, which can be added as an overlay file into the image description.
Keep in mind to set the file system permissions of
home/vagrant/.ssh/authorized_keyscorrectly, otherwise Vagrant will not be able to connect to your box. The following snippet can be added to
chmod 0600 /home/vagrant/.ssh/authorized_keys chown -R vagrant:vagrant /home/vagrant/
Create the default shared folder
Vagrant boxes usually provide a default shared folder under
/vagrant. Consider adding this empty folder to your overlay files and ensure that the user
vagranthas write permissions to it.
Note, that the boxes that KIWI produces require this folder to exist, otherwise Vagrant will not be able to start them properly.
Setup and start SSH daemon
config.shadd the start of sshd:
#====================================== # Activate services #-------------------------------------- baseInsertService sshd
Also make sure to add the line UseDNS=no into
/etc/ssh/sshd_config. This can be done by an overlay file or by patching the file in the above mentioned
Configure sudo for the Vagrant user
Vagrant expects to have passwordless root permissions via
sudoto be able to setup your box. Add the following line to
/etc/sudoersor add it into a new file
vagrant ALL=(ALL) NOPASSWD: ALL
You can also use visudo to verify that the resulting
visudo -cf /etc/sudoers if [ $? -ne 0 ]; then exit 1 fi
An image built with the above setup creates a Vagrant box file with the
.vagrant.virtualbox.box. Add the box file to Vagrant with the
vagrant box add my-box image-file.vagrant.libvirt.box
Using the box with the libvirt provider requires alongside a correct Vagrant installation:
vagrant-libvirtto be installed
a running libvirtd daemon
Once added to Vagrant, boot the box and log in with the following sequence of vagrant commands:
vagrant init my-box vagrant up --provider libvirt vagrant ssh
Customizing the embedded Vagrantfile¶
This is an advanced topic and not required for most users
Vagrant ship with an embedded
Vagrantfile that carries settings
specific to this box, for instance the synchronization mechanism for the
shared folder. KIWI generates such a file automatically for you and it
should be sufficient for most use cases.
If a box requires different settings in the embedded
then the user can provide KIWI with a path to an alternative via the
embebbed_vagrantfile of the
vagrantconfig element: it
specifies a relative path to the
Vagrantfile that will be included
in the finished box.
In the following example snippet from
config.xml we add a custom
MyVagrantfile into the box (the file should be in the image
description directory next to
<type image="vmx" filesystem="ext4" format="vagrant" boottimeout="0"> <vagrantconfig provider="libvirt" virtualsize="42" embedded_vagrantfile="MyVagrantfile" /> <size unit="G">42</size> </type>
The option to provide a custom
Vagrantfile can be combined with the
usage of profiles (see Image Profiles), so that
certain builds can use the automatically generated
the following example that is the Virtualbox build) and others get a
customized one (the libvirt profile in the following example):
<?xml version="1.0" encoding="utf-8"?> <image schemaversion="7.1" name="LimeJeOS-Leap-15.1"> <!-- description goes here --> <profiles> <profile name="libvirt" description="Vagrant Box for Libvirt"/> <profile name="virtualbox" description="Vagrant Box for VirtualBox"/> </profiles> <!-- general preferences go here --> <preferences profiles="libvirt"> <type image="vmx" filesystem="ext4" format="vagrant" boottimeout="0" bootloader="grub2"> <vagrantconfig provider="libvirt" virtualsize="42" embedded_vagrantfile="LibvirtVagrantfile" /> <size unit="G">42</size> </type> </preferences> <preferences profiles="virtualbox"> <type image="vmx" filesystem="ext4" format="vagrant" boottimeout="0" bootloader="grub2"> <vagrantconfig provider="virtualbox" virtualbox_guest_additions_present="true" virtualsize="42" /> <size unit="G">42</size> </type> </preferences> <!-- remaining box description --> </image>
The insecure key is removed from the box when the it is first booted via Vagrant.