[blog] Howto use my own vm xml template in kanku

Fixes: #56

blog/2024/05/17/howto-use-my-own-vm-xml-template-in-kanku/index.md

@@ -0,0 +1,144 @@
+---
+status: published
+title: Howto use my own VM XML template in kanku
+date: 2024-05-17 15:40:24
+tags:
+  - howto 
+  - KankuFile
+  - template
+author: M0ses <[email protected]>
+---
+
+**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/<myjob>.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/<myjob>.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.
+
+