Preparing templates for provisioning

orcharhino provides the following default template types:

  • Provisioning templates

  • Partition tables

You can use the default templates or create custom templates.

Provisioning templates are implemented with parameters that you can configure as host parameters to affect the provisioning process. You can also add custom steps to certain templates by creating custom pre or post snippets and thus customize the provisioning process further without editing the default templates.

Thanks to partition tables implemented as templates, you can create custom, even dynamic, partition tables.

When you do not edit the default templates, maintenance is easier and you get the benefit of updates to the templates from ATIX AG.

Provisioning templates

A provisioning template defines the way orcharhino Server installs an operating system on a host.

orcharhino includes many template examples. In the orcharhino management UI, navigate to Hosts > Templates > Provisioning Templates to view them. You can create a template or clone a template and edit the clone. For help with templates, navigate to Hosts > Templates > Provisioning Templates > Create Template > Help.

Templates supported by ATIX AG are indicated by an orcharhino icon.

By default, all supported templates are locked to ensure that they automatically receive updates with future orcharhino versions. If you unlock such templates, they become unsupported and will not receive updates from ATIX AG.

If you clone a supported template, the cloned template will be unsupported.

Templates accept the Embedded Ruby (ERB) syntax. For more information, see Template Writing Reference in Managing Hosts.

You can download provisioning templates. Before you can download the template, you must create a debug certificate. For more information, see Creating an Organization Debug Certificate in Managing Organizations and Locations.

You can synchronize templates between orcharhino Server and a Git repository or a local directory. For more information, see Synchronizing template repositories in Administering orcharhino.

To view the history of changes applied to a template, navigate to Hosts > Templates > Provisioning Templates, select one of the templates, and click History. Click Revert to override the content with the previous version. You can also revert to an earlier change. Click Show Diff to see information about a specific change:

  • The Template Diff tab displays changes in the body of a provisioning template.

  • The Details tab displays changes in the template description.

  • The History tab displays the user who made a change to the template and date of the change.

Kinds of provisioning templates

There are various kinds of provisioning templates:

Provision

The main template for the provisioning process. For example, a Kickstart template.

PXELinux, PXEGrub, PXEGrub2

PXE-based templates that deploy to the template orcharhino Proxy associated with a subnet to ensure that the host uses the installer with the correct kernel options. For BIOS provisioning, select PXELinux template. For UEFI provisioning, select PXEGrub2.

Finish

Post-configuration scripts to execute using an SSH connection when the main provisioning process completes. You can use Finish templates only for image-based provisioning in virtual or cloud environments that do not support user_data. Do not confuse an image with a foreman discovery ISO, which is sometimes called a Foreman discovery image. An image in this context is an install image in a virtualized environment for easy deployment.

When a finish script successfully exits with the return code 0, orcharhino treats the code as a success and the host exits the build mode.

Note that there are a few finish scripts with a build mode that uses a call back HTTP call. These scripts are not used for image-based provisioning, but for post configuration of operating-system installations such as Debian, Ubuntu, and BSD.

user_data

Post-configuration scripts for providers that accept custom data, also known as seed data. You can use the user_data template to provision virtual machines in cloud or virtualised environments only. This template does not require orcharhino to be able to reach the host; the cloud or virtualization platform is responsible for delivering the data to the image.

Ensure that the image that you want to provision has the software to read the data installed and set to start during boot. For example, cloud-init, which expects YAML input, or ignition, which expects JSON input.

cloud_init

Some environments, such as VMWare, either do not support custom data or have their own data format that limits what can be done during customization. In this case, you can configure a cloud-init client with the foreman plugin, which attempts to download the template directly from orcharhino over HTTP or HTTPS. This technique can be used in any environment, preferably virtualized.

Ensure that you meet the following requirements to use the cloud_init template:

  • Ensure that the image that you want to provision has the software to read the data installed and set to start during boot.

  • A provisioned host is able to reach orcharhino from the IP address that matches the host’s provisioning interface IP.

    Note that cloud-init does not work behind NAT.

Bootdisk

Templates for PXE-less boot methods.

Kernel Execution (kexec)

Kernel execution templates for PXE-less boot methods.

Script

An arbitrary script not used by default but useful for custom tasks.

ZTP

Zero Touch Provisioning templates.

POAP

PowerOn Auto Provisioning templates.

iPXE

Templates for iPXE or gPXE environments to use instead of PXELinux.

Creating provisioning templates

A provisioning template defines the way orcharhino Server installs an operating system on a host. Use this procedure to create a new provisioning template.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Templates > Provisioning Templates and click Create Template.

  2. In the Name field, enter a name for the provisioning template.

  3. Fill in the rest of the fields as required. The Help tab provides information about the template syntax and details the available functions, variables, and methods that can be called on different types of objects within the template.

CLI procedure

  1. Before you create a template with the CLI, create a plain text file that contains the template. This example uses the ~/my-template file.

  2. Create the template using the hammer template create command and specify the type with the --type option:

    $ hammer template create \
--file ~/my-template \
--locations "My_Location" \
--name "My_Provisioning_Template" \
--organizations "My_Organization" \
--type provision

Cloning provisioning templates

A provisioning template defines the way orcharhino Server installs an operating system on a host. Use this procedure to clone a template and add your updates to the clone.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Templates > Provisioning Templates.

  2. Find the template that you want to use.

  3. Click Clone to duplicate the template.

  4. In the Name field, enter a name for the provisioning template.

  5. Select the Default checkbox to set the template to associate automatically with new organizations or locations.

  6. In the Template editor field, enter the body of the provisioning template. You can also use the Template file browser to upload a template file.

  7. In the Audit Comment field, enter a summary of changes to the provisioning template for auditing purposes.

  8. Click the Type tab and if your template is a snippet, select the Snippet checkbox. A snippet is not a standalone provisioning template, but a part of a provisioning template that can be inserted into other provisioning templates.

  9. From the Type list, select the type of the template. For example, Provisioning template.

  10. Click the Association tab and from the Applicable Operating Systems list, select the names of the operating systems that you want to associate with the provisioning template.

  11. Optionally, click Add combination and select a host group from the Host Group list or an environment from the Environment list to associate provisioning template with the host groups and environments.

  12. Click the Organizations and Locations tabs to add any additional contexts to the template.

  13. Click Submit to save your provisioning template.

Running custom code during host provisioning

You can run custom code before or after provisioning the host by creating a custom provisioning snippet.

Prerequisites

  • Check your provisioning template to ensure that it supports the custom snippets you want to use.

    You can view all provisioning templates under Hosts > Templates > Provisioning Templates.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Templates > Provisioning Templates.

  2. Click Create Template.

  3. In the Name field, enter a name for your custom provisioning snippet. The name must start with the name of a provisioning template that supports including custom provisioning snippets:

    • Append custom pre to the name of a provisioning template to run code before provisioning a host.

    • Append custom post to the name of a provisioning template to run code after provisioning a host.

  4. On the Type tab, select Snippet.

  5. Click Submit to create your custom provisioning snippet.

CLI procedure

  1. Create a plain text file that contains your custom snippet.

  2. Create the template using hammer:

    $ hammer template create \
--file "/path/to/My_Snippet" \
--locations "My_Location" \
--name "My_Template_Name_custom_pre" \
--organizations "_My_Organization" \
--type snippet

Custom provisioning snippet example for Debian

You can use Custom Post snippets to call external APIs from within the provisioning template directly after provisioning a host.

Preseed default custom post Example for Debian/Ubuntu
echo "Calling API to report successful host deployment"

apt-get install -y curl ca-certificates

curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "<%= @host.name %>", "operating_system": "<%= @host.operatingsystem.name %>", "status": "provisioned",}' \
"https://api.example.com/"

Associating templates with operating systems

You can associate templates with operating systems in orcharhino. The following example adds a provisioning template to an operating system entry. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Templates > Provisioning Templates.

  2. Select a provisioning template.

  3. On the Association tab, select all applicable operating systems.

  4. Click Submit to save your changes.

CLI procedure

  1. Optional: View all templates:

    $ hammer template list

  2. Optional: View all operating systems:

    $ hammer os list

  3. Associate a template with an operating system:

    $ hammer template add-operatingsystem \
--id My_Template_ID \
--operatingsystem-id My_Operating_System_ID

Creating partition tables

A partition table is a type of template that defines the way orcharhino Server configures the disks available on a new host. A Partition table uses the same ERB syntax as provisioning templates. orcharhino contains a set of default partition tables to use, including a Preseed default. You can also edit partition table entries to configure the preferred partitioning scheme, or create a partition table entry and add it to the operating system entry.

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Templates > Partition Tables.

  2. Click Create Partition Table.

  3. In the Name field, enter a name for the partition table.

  4. Select the Default checkbox if you want to set the template to automatically associate with new organizations or locations.

  5. Select the Snippet checkbox if you want to identify the template as a reusable snippet for other partition tables.

  6. From the Operating System Family list, select the distribution or family of the partitioning layout. Debian belongs to the Debian family.

  7. In the Template editor field, enter the layout for the disk partition.

    The format of the layout must match that for the intended operating system. For example, Debian requires a layout that matches a Preseed file, such as:

    zerombr
clearpart --all --initlabel
autopart

    For more information, see Dynamic partition example.

    You can also use the file browser in the template editor to import the layout from a file.

  8. In the Audit Comment field, add a summary of changes to the partition layout.

  9. Click the Organizations and Locations tabs to add any other provisioning contexts that you want to associate with the partition table. orcharhino adds the partition table to the current provisioning context.

  10. Click Submit to save your partition table.

CLI procedure

  1. Create a plain text file, such as ~/My_Partition_Table, that contains the partition layout.

    The format of the layout must match that for the intended operating system. For example, Debian requires a layout that matches a Preseed file, such as:

    zerombr
clearpart --all --initlabel
autopart

    For more information, see Dynamic partition example.

  2. Create the installation medium using the hammer partition-table create command:

    $ hammer partition-table create \
--file "~/My_Partition_Table" \
--locations "My_Location" \
--name "My_Partition_Table" \
--organizations "My_Organization" \
--os-family "Debian" \
--snippet false

Dynamic partition example

Using an Anaconda Kickstart template, the following section instructs Anaconda to erase the whole disk, automatically partition, enlarge one partition to maximum size, and then proceed to the next sequence of events in the provisioning process:

zerombr
clearpart --all --initlabel
autopart <%= host_param('autopart_options') %>

Dynamic partitioning is executed by the installation program. Therefore, you can write your own rules to specify how you want to partition disks according to runtime information from the node, for example, disk sizes, number of drives, vendor, or manufacturer.

If you want to provision servers and use dynamic partitioning, add the following example as a template. When the #Dynamic entry is included, the content of the template loads into a %pre shell scriplet and creates a /tmp/diskpart.cfg that is then included into the Kickstart partitioning section.

#Dynamic (do not remove this line)

MEMORY=$((`grep MemTotal: /proc/meminfo | sed 's/^MemTotal: *//'|sed 's/ .*//'` / 1024))
if [ "$MEMORY" -lt 2048 ]; then
    SWAP_MEMORY=$(($MEMORY * 2))
elif [ "$MEMORY" -lt 8192 ]; then
    SWAP_MEMORY=$MEMORY
elif [ "$MEMORY" -lt 65536 ]; then
    SWAP_MEMORY=$(($MEMORY / 2))
else
    SWAP_MEMORY=32768
fi

cat <<EOF > /tmp/diskpart.cfg
zerombr
clearpart --all --initlabel
part /boot --fstype ext4 --size 200 --asprimary
part swap --size "$SWAP_MEMORY"
part / --fstype ext4 --size 1024 --grow
EOF

The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution Share Alike 4.0 International ("CC BY-SA 4.0") license. This page also contains text from the official Foreman documentation which uses the same license ("CC BY-SA 4.0").