Dustin C. Hatch
9549fd984b
If the `lxml` package is available, its ElementTree implementation is used instead of the one in the Python standard library. This implementation provides a "pretty print" option when serializing XML documents. Note that since `Element.attrib` is not a "real" dictionary object, it does not accept keyword arguments to its `update` method, so a dictionary must be passed in instead. This is used in a few places to set element attributes in bulk.
.. 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