116 lines
3.1 KiB
ReStructuredText
116 lines
3.1 KiB
ReStructuredText
.. 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
|