Kvm-deploy is a tool for automated deployment of virtual machines on a [KVM] 2/[libvirt] 3 virtualization platform.

Deploying small to mid size KVM platforms can be expensive, not in the least part because it can involve a lot of manual labor in setting up virtual machines.

Large scale deployments of KVM, for instance with [OpenStack] 4 or [CloudStack] 5, do have good automated deployment tools. However, these tools are often not trivial to setup and also create a lot of overhead and complexity that makes sense for large deployments, but is also hindering cost minimization on small scale deployments. Many tools also happen to be a lot more vendor/distro specific then they claim to be, which is not helping matters when trying to create flexible solutions.

An additional issue can be that most automatic deployment tools are based on creating virtual machines off of prepared disk images with already installed operating systems on them. The creation of these images themselves often involves manual labor and has to be repeated every time a producer distributes a new version of their operating system in order to stay up to date. This maintenance need for standard disk images and the fact that creating tailored prepared images for different deployment needs at best multiplies these costs, make the small scale deployment of KVM a relatively expensive job.

This is where kvm-deploy can make a difference. It is a lightweight tool consisting of a [Python] 6 script and a set of [YAML] 7 configuration files. Kvm-deploy can fully automatically create or replace a virtual machines using a configuration file. The purpose of kvm-deploy is to get a system up and running up to the point where a system configuration management tool like [Salt] 8, [Puppet] 9 or [Chef] 10 can take over.

Kvm-deploy does not rely on prepared disk images, but uses installer images instead. These are the iso images publicly available from Linux distro producers. Normally this installation process would require human interaction. However, both Debian/Ubuntu and Red Hat based/derived Linux distributions also have mechanisms for automating this process, called [Preseed] 11 and [Kickstart] 12 respectively.

Kvm-deploy disassembles installer images and injects automation configuration before it reassembles them again. The result is an installer image specifically tailored for each individual virtual machine. As a result of this approach, kvm-deploy is limited to operating systems that have some mechanism for automating their installation by adding something to their installer iso image. On the positive side of this limitation, the only action to be taken to upgrade a virtual machine to a newer version is to change a single configuration entry and then redeploy the virtual machine.

A key design feature of kvm-deploy is that only a minimal amount of complexity and knowledge about the structure of configuration files is locked up in the main script's code. Most configurable aspects of a deployment comes from a freely editable template file and an accompanying translation table file, which links variables in a template to values in a deployment's configuration file.

To facilitate the management of larger sets of deployment configuration files, the standard YAML format has been extended with an include feature. This makes it possible to put parts of a configuration into a single reusable file. The result is that a deployment's configuration file can be very compact and only contain deployment specific information and a set of references to generic include files. See the Examples for more information.

The simplest way to get started is by cloning the git repository and as root run:

make install

All this does is install the kvm-deploy script in the /usr/sbin directory and create a directory with example configurations and templates in the /etc/kvm-develop directory. Please be aware that this installation happens outside of the control of your distro's package manager. If kvm-deploy needs to be uninstalled, this can be done by running:

make uninstall

Be careful because this command also deletes the full /etc/kvm-deploy directory, including any configuration files you may have made.

Kvm-deploy relies on some other tools, which on a Debian/Ubuntu based system can be installed with:

apt-get install rsync libvirt-bin virtinst

Once kvm-deploy is installed, the deployment of a virtual machine, its disk images and associated virtual networks, is as simple as invoking

kvm-deploy machine

Machine has to have a corresponding configuration file called /etc/kvm-deploy/machine.yaml. The name for a configuration file can be chosen arbitrarily, but a good convention could be to name these files after the hostname or [FQDN] 13 of they virtual machine the deploy.

For those who are using a Debian/Ubuntu bases system on their virtualization host machine, a deb package can be created with:

apt-get install devscripts build-essential fakeroot
make deb-package

It may be best to generate the deb package not on the target machine, but e.g. a temporary virtual machine or on a development system, because the installation of devscripts and build-essential will also install many other tools that do not belong on a production machine. The generated deb package can be found in the projects build directory.

If any of the Examples is used to create real deployments, make sure to put newly generated public and private keys in the configuration file and not reuse the example ones! The same goes for the ssh access configuration files for [debian] 23 and [ubuntu] 24. In real deployments it would be better to have an individual include file for each machine, or define unique values directly in the machine's deployment file.

Please take not of the fact that because of the flexible nature on the configuration of kvm-develop, it is also very easy to do bad things by manipulating configuration and template files.

One way to mitigate some of the security dangers and also to be better equipped against accidental mishaps, is to keep the whole configuration directory under the control of a git repository with:

cd /etc/kvm-deploy
git init
git remote add origin git@your_git_server:your_repository.git

Whenever anything is changed to the configuration run:

cd /etc/kvm-deploy
git add --all
git commit -am "<commit message>"
git push origin master

This way the configuration's integrity can always be verified and restored from a safe location.

Kvm-deploy comes with 3 example deployment configurations to demonstrate some of kvm-deploy's capabilities. The examples are called [EXAMPLE1] 19, [EXAMPLE2] 20 and [EXAMPLE3] 21. They can be deployed with:

kvm-deploy example1
kvm-deploy example2
kvm-deploy example3

A deployment of all the examples will create a situation like this:

In this illustration, the numbers in orange indicate example values that have to be adjusted to match the network in which the KVM host is situated. This means that in order to deploy EXAMPLE1, some values need to be edited in the [example's configuration file] 19, and also in the [network's configuration file] 22. In order to deploy EXAMPLE3, EXAMPLE1 needs to already be deployed for it acts as the gateway router for EXAMPLE1. Additionally, for EXAMPLE3 to be deployed, a static route on the KVM host's network gateway router is required. This static route needs to direct any traffic for the 172.16.1.0/24 network to the IP address of the primary interface of EXAMPLE1. EXAMPLE2 does not have any special requirement and can be deployed without making any changes.

EXAMPLE1:

• Debian 7 VM, with 128 Mbyte of RAM and a single 1 GByte disk image.
• Directly connected to the KVM host's network for Internet access.
• Acts as a gateway router for the virbrXiso1 virtual network and EXAMPLE3.
• Will create an isolated virtual network (if not existing), called virbrXiso1.

EXAMPLE2:

• Debian 7 VM, with 128 Mbyte of RAM and a single 1 GByte disk image.
• Connected to a NAT forwarding virtual network for Internet access.
• Will create a NAT forwarding virtual network (if not existing), called virbrXnat0.
• Will create an isolated virtual network (if not existing), called virbrXiso1.
• Will create an isolated virtual network (if not existing), called virbrXiso2..

EXAMPLE3:

• Ubuntu 13.10 Server VM, with 256 Mbyte of RAM and a single 2 GByte disk image.
• Connected to an isolated network (virbrXiso1) with a gateway router (EXAMPLE1) for Internet access.
• Will create an isolated virtual network (if not existing), called virbrXiso1.
• Will create an isolated virtual network (if not existing), called virbrXiso2..

All examples use USA mirrors as package repositories and UTC for their time zone settings. It is advised to create include files for your personal location and if possible use a local APT proxy, which will speed up a deployment considerably.

• Add support for [RPM package] 14 generation (make rpm-package).
• Add support for [Kickstart] 9, for [Fedora] 15/[CentOS] 16 deployments.
• Add support for [AutoYaST] 17, for [openSUSE] 18 deployments.