Howto use my own VM XML template in kanku

Tags:

Problem:

I would like to customize the libvirt XML description for my new kanku VM.

TL;DR

Only two steps are required to use your own XML template

  • Create a new VM XML template
  • Configure your kanku job to use your new template in your
    • KankuFile
    • or /etc/kanku/jobs/.yml

Create a new VM XML template

First you need to create a new XML template in the template directory (/etc/kanku/templates/).

Lets assume you want to call your template myvm then you need to create the file /etc/kanku/templates/myvm.tt2

We recommend starting with one of the default templates delivered with the kanku-common package in /etc/kanku/templates/*.tt2.

The following options are used to populate the template and can be modified directly in the KankuFile or kanku job definition on the server:

Directly configurable options

  • domain
    • vcpu - Kanku::Handler::CreateDomain.options.vcpu
    • memory - Kanku::Handler::CreateDomain.options.memory
    • domain_name - multiple options (most specific wins)
      • KankuFile global option domain_name
      • Kanku::Handler::SetJobContext->options->domain_name
      • Kanku::Handler::CreateDomain->options->domain_name
    • network_name -
    • network_bridge - => $self->network_bridge ,

Automatically generated or selected options

disk_xml/disk_controllers_xml

The following variables

  • disk_xml
  • disk_controllers_xml

can be controlled/influenced by several options

  • Kanku::Handler::CreateDomain->options->empty_disks
  • Kanku::Handler::CreateDomain->options->additional_disks
  • Kanku::Handler::CreateDomain->options->root_disk_bus
  • Kanku::Handler::CreateDomain->options->root_disk_size
  • Kanku::Handler::CreateDomain->options->pool_name

Explaining these options in detail would blast this document.

Please have a look into the documentation of Kanku::Handler::CreateDomain or see our various KankuFile.examples.

hostshare

The hostshare variable contains the xml snippet to configure shared directories between host and guest.

It can be controlled/influenced by the following configuration options:

  • Kanku::Handler::CreateDomain->options->use_9p
  • Kanku::Handler::CreateDomain->options->host_dir_9p
  • Kanku::Handler::CreateDomain->options->accessmode_9p

host_feature/qemu_km

The following variables get automatically set by Kanku::Handler::CreateDomain depending on the underlying hardware.

  • host_feature
    • vmx
    • svm
    • aarch64
  • qemu_kvm - autoselected (path to emulator)

Deprecated options (might be removed in future)

  • images_dir (replaced by autogenerated disk_xml and cache_dir)
    • Kanku::Handler::SetJobContext->options->images_dir
    • Kanku::Handler::CreateDomain->options->images_dir
  • image_file

Configure kanku job

In development mode you need to configure your new template in KankuFile. In server mode you can do this in `/etc/kanku/jobs/.yml

You have two possibilities to specify your new template:

  • Kanku::Handler::SetJobContext->vm_template_file

or

  • Kanku::Handler::CreateDomain->template

Example KankuFile snippet:

- 
  use_handler: Kanku::Handler::SetJobContext
  options:
    vm_template_file: myvm
  ...
-
  use_handler: Kanku::Handler::CreateDomain
  options:
    template: myvm
...

Troubleshooting

Check your logs, which template is really used

Kanku will NOT exit/fail if the configured template does not exists. It will fallback to the default-vm.tt2 or use an internal default xml.

So please make sure that myvm.tt2 is really used. The used template will get logged in INFO loglevel and above.