Dustin C. Hatch
7629a5dd97
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.
.. 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