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 NG 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 NG only supports the libvirt and VirtualBox providers. Other providers require a different box layout that is currently not supported by KIWI NG.

In addition, you can use the KIWI NG 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 NG image description from Build a Virtual Disk Image, the following steps are required:

  1. Update the image type setup

    <type image="oem" filesystem="ext4" format="vagrant">
    <bootloader name="grub2" timeout="0"/>
    <vagrantconfig provider="libvirt" virtualsize="42"/>
    <size unit="G">42</size>
    <oemconfig>
        <oem-resize>false</oem-resize>
    </oemconfig>
</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_present can be set to true when the VirtualBox guest additions are installed in the KIWI NG image:

    <type image="oem" filesystem="ext4" format="vagrant">
    <bootloader name="grub2" timeout="0"/>
    <vagrantconfig
      provider="virtualbox"
      virtualbox_guest_additions_present="true"
      virtualsize="42"
    />
    <size unit="G">42</size>
    <oemconfig>
        <oem-resize>false</oem-resize>
    </oemconfig>
</type>

    The resulting Vagrant box then uses the vboxfs module for the synchronized folder instead of rsync, that is used by default.

  2. Add mandatory packages

    <package name="sudo"/>
<package name="openssh"/>

  3. Add additional packages

    If you have set the attribute virtualbox_guest_additions_present to 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 rsync:

    <package name="rsync"/>

    Note that KIWI NG cannot verify whether these packages are installed. If they are missing, the resulting Vagrant box will be broken.

  4. 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.

  5. Configure SSH, the default shared folder and sudo permissions

    Vagrant expects that it can login as the user vagrant using an insecure public key [1]. Furthermore, vagrant also usually uses /vagrant as the default shared folder and assumes that the vagrant user can invoke commands via sudo without having to enter a password.

    This can be achieved using the function baseVagrantSetup in config.sh:

    baseVagrantSetup

  6. Additional customizations:

    Additionally to baseVagrantSetup, you might want to also ensure the following:

    • If you have installed the Virtualbox guest additions into your box, then also load the vboxsf kernel module.

    • When building boxes for libvirt, then ensure that the default wired networking interface is called eth0 and uses DHCP. This is necessary since libvirt uses dnsmasq to issue IPs to the VMs. This step can be omitted for Virtualbox boxes.

An image built with the above setup creates a Vagrant box file with the extension .vagrant.libvirt.box or .vagrant.virtualbox.box. Add the box file to Vagrant with the command:

vagrant box add my-box image-file.vagrant.libvirt.box

Note

Using the box with the libvirt provider requires alongside a correct Vagrant installation:

  • the plugin vagrant-libvirt to 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

Warning

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 NG 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 Vagrantfile, then the user can provide KIWI NG with a path to an alternative via the attribute 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 config.sh):

<type image="oem" filesystem="ext4" format="vagrant">
    <bootloader name="grub2" timeout="0"/>
    <vagrantconfig
      provider="libvirt"
      virtualsize="42"
      embedded_vagrantfile="MyVagrantfile"
    />
    <size unit="G">42</size>
    <oemconfig>
        <oem-resize>false</oem-resize>
    </oemconfig>
</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 Vagrantfile (in 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="8.0" name="{exc_image_base_name}">
  <!-- 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="oem"
      filesystem="ext4"
      format="vagrant">
        <bootloader name="grub2" timeout="0"/>
        <vagrantconfig
          provider="libvirt"
          virtualsize="42"
          embedded_vagrantfile="LibvirtVagrantfile"
        />
        <size unit="G">42</size>
        <oemconfig>
            <oem-resize>false</oem-resize>
        </oemconfig>
   </type>
   </preferences>
   <preferences profiles="virtualbox">
     <type
       image="oem"
       filesystem="ext4"
       format="vagrant">
         <bootloader name="grub2" timeout="0"/>
         <vagrantconfig
           provider="virtualbox"
           virtualbox_guest_additions_present="true"
           virtualsize="42"
         />
         <size unit="G">42</size>
         <oemconfig>
             <oem-resize>false</oem-resize>
         </oemconfig>
     </type>
   </preferences>

   <!-- remaining box description -->
 </image>