The `vmdesc2xml` command reads a VM description from a YAML document and
prints the generated libvirt domain XML to stdout. This can be useful
for debugging or other purposes besides creating VMs directly.
This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.
.. vim: set ft=rst :
====
mkvm
====
``mkvm`` is a command-line tool and Python (3.x) API for creating Gentoo-based
*libvirt*/KVM virtual machines.
The ``mkvm`` command creates reproducible Gentoo system installations from
declarative configuration descriptions. Its goal is to produce a minimum
working environment that can then be managed by a configuration management
package such as `Ansible`_.
Features
========
* Reads virtual machine descriptions from YAML documents
* Supports installing Gentoo onto LVM volumes and image files
* Can fetch the latest stage3 tarball from a Gentoo mirror
* Partitions virtual machine disks using GPT and/or LVM
* Performs initial system configuration (e.g. filesystem mount configuration,
SSH host key generation, etc.)
* Allows execution of custom scripts inside target system environments
Requirements
============
* `Python`_ 3.3+
* `setuptools`_
* `libvirt-python`_
* `pygpgme`_
* `pyudev`_
* `PyYAML`_
Additionally, the following commands/packages may be needed:
* ``losetup`` – Used to build raw file images
* ``qemu-nbd`` – Used to build file images in *qcow2*, *vmdk*, etc.format
* ``lvm2`` – Used to support logical volumes, either inside the target
system or on the host
* ``sgdisk`` – Used to partition virtual disks with `GPT`_
* ``wget`` – Used to fetch Gentoo stage3 tarballs
Example
=======
Virtual machine description, in YAML format:
.. code-block:: yaml
name: TestVM
fqdn: testvm.example.org
ram: 512M
vcpus: 2
net_ifaces:
- bridge: br0
mac: 52:54:00:40:5b:1c
image_format: qcow2
disk_size: 5G
disk_label: null
volumes:
- name: root
size: 3G
fstype: ext4
fsopts: ro,noatime,discard
mountpoint: /
- name: var
size: 1G
fstype: ext4
fsopts: noatime
mountpoint: /var
- name: var-log
size: 512M
fstype: ext4
fsopts: noatime
mountpoint: /var/log
kernel: /var/lib/libvirt/images/vmlinuz-3.18.12-gentoo.vm
initrd: /var/lib/libvirt/images/initramfs-genkernel-x86_64-3.18.12-gentoo.vm
kcmdline: >-
root=/dev/testvm/root ro dolvm rootfstype=ext4 nodetect fastboot quiet
boot:
- kernel
timezone: America/Chicago
customize: |
ln -s net.lo /etc/init.d/net.eth0
ln -s /etc/init.d/net.eth0 /etc/runlevels/default/
echo config_eth0="dhcp" > /etc/conf.d/net
The following command will fetch the latest Gentoo stage3 tarball and create a
machine using the above description:
.. code-block:: sh
mkvm --latest testvm.yml
.. note:: ``mkvm`` likely needs to be run as root in order to set up loopback
devices, create filesystems, etc. Future versions may use privilege
separation techniques to allow normal users to create virtual machines.
.. _Ansible: http://www.ansible.com/
.. _Python: http://www.python.org/
.. _setuptools: https://pythonhosted.org/setuptools/
.. _libvirt-python: http://www.libvirt.org/
.. _pygpgme: https://pypi.python.org/pypi/pygpgme
.. _pyudev: https://pypi.python.org/pypi/pyudev
.. _PyYAML: http://pyyaml.org/
.. _GPT: https://en.wikipedia.org/wiki/GUID_Partition_Table
Dustin
7629a5dd97