Template Specs

Katapult's templating system provides a powerful set of tools allowing you to fully customise how virtual machines are built. Using the Template Spec system you can compose an appropriate set of configuration which allows you to prompt for information when creating a virtual machine as well as configuring actions to run as part of the virtual machine provisioning process.

This page provides an example template spec along with appropriate comments to help understand what options are available to you.

Example template spec with annotations

In some areas you can use the Liquid templating system to template responses (for example in CreateFile and RunScript actions). The variables that are available to you are shown at the bottom of this page.

<Spec>

  <!---
    This section defines a list of attributes which should be displayed to users
    within the Katapult interface. In this case, we add the root_password attribute
    so users can see a generated root password.
  -->
  <Store>
    <Attribute>
      <Name>root_password</Name>
      <Label>Root password</Label>
      <Description>
        This is the password we have set for your root user.
        You should change this.
      </Description>
      <Protect>true</Protect>
    </Attribute>
  </Store>

  <!---
    This section lists all fields which should be prompted for when a new virtual
    machine is created using this template.
  -->
  <Fields>
    <Field>
      <!--- The name to store the field in -->
      <Name>root_password</Name>
      <!--- The type of field (can use: 'Text', 'Boolean', 'Password' or 'Keyboard') -->
      <Type>Password</Type>
      <!--- The label to describe the field -->
      <Label>Initial root password</Label>
      <!--- Placeholder text to display in the input box where appropriate -->
      <Placeholder>Automatically generated</Placeholder>
      <!--- A description of the field -->
      <Description>
        You can choose what the initial root password for this server will be.
        By default, a random string will be generated for you. Please be aware that
        this server will be configured with root password logins enabled on SSH and
        therefore you should choose a secure password here to ensure your server
        remains secure.
      </Description>
    </Field>

    <Field>
      <Name>keyboard_layout</Name>
      <Type>Keyboard</Type>
      <Label>Keyboard layout</Label>
      <Description>Select the country whose keyboard layout you would like to use.</Description>
    </Field>

    <Field>
      <Name>install_agent</Name>
      <Type>Boolean</Type>
      <Label>Install QEMU guest agent?</Label>
      <Description>
        If enabled, the QEMU guest agent will be installed in this virtual
        machine, enabling secure access by the Katapult management system
        to the virtual machine. Some features such as memory monitoring require
        the agent to be installed.
      </Description>
      <!--- Specifies the default value (prefilled in the form) -->
      <Prefill>true</Prefill>
      <!--- Specifies that the field is not required -->
      <Required>false</Required>
    </Field>

  </Fields>

  <!---
    This section lists all the actions which should be run when a new virtual machine
    is built from this template. 

    All actions are run in order.

    For each of the actions listed below, you can provide an `if` or `unless` attribute
    (as shown below) to determine whether that action is run or not. The format of this
    condition is the same as that used by the templating lanauge, Liquid.

    Note: the examples below are not expected to be run in this order. They are just
    listed for documentation purposes.
  -->

  <Actions>

    <!---
      Generate a random string and store it in the `root_password`
      attribute of the store.

      In this example, it will also only be run if no root_password
      has already been set.
    -->
    <GenerateRandomString unless="store.root_password">
      <Style>Password</Style>
      <Length>16</Length>
      <StoreAs>root_password</StoreAs>
    </GenerateRandomString>

    <!---
      Hashses the provided root password in SHA512 and stores the 
      resulting hash in the root_password_sha512 attribute.
    -->
    <CryptUnix>
      <Source>{{ store.root_password }}</Source>
      <Algorithm>SHA512</Algorithm>
      <StoreAs>root_password_sha512</StoreAs>
    </CryptUnix>

    <!---
      Sets the root user's password to the value.
    -->
    <SetUserPassword>
      <Username>root</Username>
      <EncryptedPassword>{{ store.root_password_sha512 }}</EncryptedPassword>
    </SetUserPassword>

    <!---
      Create a new file

      In this case, only if a hostname is provided.
    -->
    <CreateFile if="virtual_machine.hostname">
      <Path>/etc/hostname</Path>
      <Mode>644</Mode>
      <Content>
        <![CDATA[
          {{ virtual_machine.hostname }}
        ]]>
      </Content>
    </CreateFile>

    <!---
      Copies a value from one part of the store to another. In this case,
      we copy a value from the previous installation to the current one.
      The previous installation, in this case, is only available if the
      machine has been installed previously.
    -->
    <Copy>
      <From source="previous">ssh_host_keys</From>
      <To>ssh_host_keys</To>
    </Copy>

    <!---
      Generaetes a set of host keys and stores them.
    -->
    <GenerateSSHHostKeys unless="store.ssh_host_keys">
      <StoreAs>ssh_host_keys</StoreAs>
    </GenerateSSHHostKeys>

    <!---
      Runs a script.

      Note: this script is run as part of the provisioning process and therefore the
      virtual machine does not have any network connectivity and may not behave in the
      same way as it would if was booted normally.

      If you want to run something on boot it is recommended to use CreateFile
      to place a script on the machine and then configure the OS to run it on boot.
    -->
    <RunScript>
      <Description>Run something</Description>
      <Script>
        <![CDATA[
          echo 1 > /path/to/file
        ]]>
      </Script>
    </RunScript>
  </Actions>
</Spec>

Template variables

The following variables are available within the templating system:

• store.* - provides access to an internal store including any values provided as fields.
• id - the ID of the specific installation

Disk

This relates to the disk that the template is being installed on to.

• disk.id - the ID of the disk
• disk.name - the name of the disk
• disk.size_in_gb - the size in GB of the disk

Template

This relates to the specific template that is being installed.

• template.id
• template.name
• template.version

Operating System

• os.id
• os.name

Virtual Machine

• virtual_machine.id
• virtual_machine.hostname
• virtual_machine.name
• virtual_machine.fqdn
• virtual_machine.uuid

Network interfaces

This is an array of network interfaces which are allocated to this virtual machine.

• virtual_machine.network_interfaces[].id
• virtual_machine.network_interfaces[].slot
• virtual_machine.network_interfaces[].interface_name
• virtual_machine.network_interfaces[].mac_address
• virtual_machine.network_interfaces[].network.id
• virtual_machine.network_interfaces[].network.name
• virtual_machine.network_interfaces[].network.nameservers - an array of nameserver IP addresses
• virtual_machine.network_interfaces[].ip_addresses[] - an array of IP addresses assigned to the interface's network
• virtual_machine.network_interfaces[].ip_addresses[].id
• virtual_machine.network_interfaces[].ip_addresses[].address
• virtual_machine.network_interfaces[].ip_addresses[].address_with_mask
• virtual_machine.network_interfaces[].ip_addresses[].gateway
• virtual_machine.network_interfaces[].ip_addresses[].mask
• virtual_machine.network_interfaces[].ip_addresses[].version
• virtual_machine.network_interfaces[].ip_addresses[].broadcast
• virtual_machine.network_interfaces[].ip_addresses[].v4_netmask
• virtual_machine.network_interfaces[].ipv4_addresses[]... - an array of IPs as above but only containing v4 addresses
• virtual_machine.network_interfaces[].ipv6_addresses[]... - an array of IPs as above but only containing v6 addresses
• virtual_machine.network_interfaces[].default_gateway_4 - the default gateway for IPv4
• virtual_machine.network_interfaces[].default_gateway_6 - the default gateway for IPv6

Organization

This relates to the organziation the virtual machine belongs to.

• organization.id
• organization.name

Users

This is an array of users that have access to this virtual machine.

• users[].id
• users[].name
• users[].email_address
• users[].owner
• users[].ssh_keys[] - an array of SSH keys for this user
• users[].ssh_keys[].id
• users[].ssh_keys[].key
• users[].ssh_keys[].name
• users[].ssh_keys[].fingerprint
• users[].ssh_keys[].authorized_keys_line - an appropriate line for inserting into an authorized_keys file.