Managing Operating System templates

MetalSoft provides templates for the important operating systems. The templates are often customized to suit the respective deployment’s needs.

Use the CLI to list and register (install in the environment) a template from the repository. The CLI pulls the templates from a repository. The default repository is https://github.com/metalsoft-io/os-templates but a company specific template repository could also be used by providing a --repo option to the CLI.

Listing available source templates

metalcloud-cli os-template list-source-templates
+-----------+-----------------------+--------------+----------------+-----------+-------------------------------------------+
| TYPE      | VERSION               | ARCHITECTURE | DEPLOY PROCESS | BOOT TYPE | SOURCE TEMPLATE PATH                      |
+-----------+-----------------------+--------------+----------------+-----------+-------------------------------------------+
| AlmaLinux | 8                     | x64          | pxe            | UEFI      | AlmaLinux/non-OOB-8                       |
| ESXi      | 7.0.0                 | x64          | virtual_media  | UEFI      | ESXi/OOB-7.0.0                            |
| ESXi      | 7.0.0.u03-DellEMC-A02 | x64          | virtual_media  | UEFI      | ESXi/OOB-7.0.0.u03-DellEMC_Customized-A02 |
| Ubuntu    | 20.04                 | x64          | virtual_media  | UEFI      | Ubuntu/non-OOB-20.04                      |
| Ubuntu    | 20.04                 | x64          | pxe            | UEFI      | Ubuntu/non-OOB-20.04-iscsi-ibft-uefi      |
| Ubuntu    | 20.04.4               | x64          | virtual_media  | UEFI      | Ubuntu/OOB-20.04                          |
| Windows   | 2019                  | x64          | virtual_media  | UEFI      | Windows/OOB-uefi 2019                     |
| Windows   | 10.0.17763            | x64          | virtual_media  | UEFI      | Windows/non-OOB-uefi 2019                 |
| Windows   | 2019                  | x64          | virtual_media  | Legacy    | Windows/OOB-bios 2019                     |
+-----------+-----------------------+--------------+----------------+-----------+-------------------------------------------+
Total: 9 Repository templates

Registering a new template

Besides the source template, the original iso is required for registering a new template.

  1. Download the ISO from any official repository to a local directory

  2. Identify the source template path required for the OS family you are adding such as Ubuntu/OOB-20.04 in the output of the metalcloud-cli os-template list-source-templates command.

  3. Create the new template based on the downloaded iso and the entry in the source template path column

metalcloud-cli os-template register --source-template Ubuntu/OOB-20.04 --name "Ubuntu 20.04.4 OOB" --source-iso /a/iso/ubuntu-22.04.1-live-server-amd64.iso --label ubuntu-2004-oob

  1. Upload the ISO on the repo at the specified location if not already uploaded.

Checking if the template has been registered:

You can use the Sidebar > Templates to verify if the new template exists or use the CLI:

metalcloud-cli os-template list
+---+-----------------+--------------------+-------------+-------------+--------------+-----------------------+--------------------+---------------+---------+----------------------+----------------------+
| ID| LABEL           | NAME               | DESCRIPTION | SIZE_MBYTES | BOOT_METHODS | OS                    | INSTALL_BOOTLOADER | OS_BOOTLOADER | USER_ID | CREATED              | UPDATED              |
+---+-----------------+--------------------+-------------+-------------+--------------+-----------------------+--------------------+---------------+---------+----------------------+----------------------+
| 1 | ubuntu-2004-oob | Ubuntu 20.04.4 OOB |             | 2048        | local_drives | Ubuntu 20.04.4 x86_64 |                    |               | 3       | 2023-01-18T10:40:32Z | 2023-01-18T10:40:32Z |
+---+-----------------+--------------------+-------------+-------------+--------------+-----------------------+--------------------+---------------+---------+----------------------+----------------------+
Total: 1 Templates

Customizing a template

To add a new software package, change the storage configuration or for other reasons you can view and edit the files (assets) that get injected in the image building process.

  1. Enable the Assets view.

    Normally the assets view is not enabled. Navigate to the Users & Permissions > user > Limits and check the Enable Template Assets view checkbox.

  2. Navigate to assets

    Once a template has been registered, navigate to the template Templates > Unattended install templates > template > Assets

  3. Edit an asset

    To open an asset select the asset and navigate to the Content tab to open the built-in content editor.

    Assets depend on the operating system. Consult the operating system’s unattended installation manual for instructions on how the files are named and their role. Note that additional helper assets might be added by MetalSoft for various purposes such as generating firewall configurations that might not be part of the standard installation process.

    Refer to the Template Language and Variables for more details on the Nunjucks programming language and the runtime variables used by the templates.

    Click the green Save button to save the asset.

    Note that assets can also be changed via the CLI metalcloud-cli asset edit command. Run to the metalcloud-cli asset commands for more details on the available commands.

  4. Test the template

    Test the deployment process by deploying an instance array in the usual way. Monitor the deployment of the operating system using the Job queue or by navigating to Infrastructures > > Open Deploy Graph or by using the metalcloud-cli job list commands.

    Warning

    Note that Save button will NOT propagate the changes to an ongoing deploy and thus retrying a task on the OS deployment tasks in the graph will not change the already ‘materialized’ assets. To fix an problem with an asset skip the offending task and try another deploy.

Upgrading an existing template to a newer version

First check for a newer version in the official MetalSoft repository using the metalcloud-cli os-template list-source-templates command. If no newer version exists you can attempt the upgrade yourself by using the same metalcloud-cli os-template register command as before and using a newer ISO and an older source template. This should be sufficient for most situations as the unattended installation process does not usually change between minor releases of an operating system.

Building a new template from scratch

To build a new template from scratch you will need to build a source repository similar to the provided ones.

  1. Create a directory

  2. Create a template.yaml file (refer to this as an example). This file describes the assets and their types.

  3. Add the assets, refer to Template Language and Variables for how to add variables to the files in order to adapt to each server that gets deployed.

  4. Use the newly created directory and use metalcloud-cli os-template register --source-template ./template-dir to use the local template as a source template for registering the template in the environment.

Building a new source template for legacy systems

Refer to the following resource for building templates for legacy (PXE) environments Managing OS templates for legacy (PXE).