Custom Templates

Exoscale provides various Compute Instance templates to choose from. However it is possible that you might want to customize templates to further fit your needs.

In addition to using a cloud-init configuration via an Instance’s User Data or using a configuration management tool such as Puppet or Ansible, you can also create your own customized templates.

Custom Templates can be used to launch a custom operating system or custom template configuration on Exoscale, allowing you to deploy Instances ready to go with minimal start-up configuration.

Create a Custom Template

Using Packer

HashiCorp Packer is a popular tool for building cloud infrastructure Compute images, which is the recommended method for creating custom templates on Exoscale.

Starting from version 1.7, Packer supports a new packer init command allowing automatic installation of Packer plugins, including the exoscale plugin. Read the Packer documentation for more information.

Snapshot instance disk using the exoscale Packer Builder (recommended)

The exoscale Packer Builder creates a Compute instance in your Exoscale organization, logs into it via SSH to execute configured provisioners and then snapshots the storage volume of the instance to register a custom template from the exported snapshot. This is the easiest way to create custom templates if you can use an existing Exoscale template as base image.

Import a disk image using the exoscale-import Packer Post-processor

The exoscale-import Packer Post-processor takes a local disk image file (e.g. built using the Packer QEMU or File Builders) and import it to Exoscale as a new Compute instance template. This method is useful if you need to build custom templates that are not based on an existing Exoscale template.

Manually

If you can’t or prefer not to use Packer, it is possible to build disk images and register them as custom templates manually.

Prerequisites

• The template image must be a true KVM-compatible QCOW2 image (do not just rename your .img, .iso or .vdmk file)
• The image must have the preallocation mode set to off.
• The virtual size of the image must be between 10 GB and 1 TB (this may differ from the actual file size, but the QCOW2 format must be within this range).
• To deploy machines with attached local storage larger than 1.6 TB a GPT partitioning table and UEFI boot must be used.
• To be registered, the template must be hosted on a publicly accessible HTTP or HTTPS URL, such as Exoscale S3 compatible Object Storage.
• We strongly encourage you to install cloud-init to get full functionality

KVM/QEMU tools are also required would you need to prepare your template to comply to requirements. For example, to convert a third party template from the raw format to QEMU QCOW2 format you can do the following:

qemu-img convert -f raw -O qcow2 -o preallocation=off source.img destination.qcow2

Additionally, you may need to resize the image to fit the minimum size required by Exoscale:

qemu-img resize destination.qcow2 10G

We provide Packer configuration examples in this Git repository to help you get started using the exoscale-import custom template building method.

cloud-init

Although not mandatory, we strongly recommend installing cloud-init 19.3 or later on Linux-based images: this enables full integration with Exoscale. Would you choose to not install it, we will only be able to provide very limited support.

Known limitations to the absence of cloud-init on your template are:

• The password reset functionality will not work
• During startup, the Instance will not be able to resize the partition table on the fly to match the desired VM local storage size. You will have to manually resize the partition table and the filesystem
• Without cloud-init it will not be possible to pass userdata to the Instance at boot
• The web portal UI will present some inconsistencies and limited functionality

Starting with version 19.3 the native Exoscale cloud-init datasource i used. During startup cloud-init will determine what the appropriate datasource is (Exoscale) by reading dmi information. Hence, no specific customization is needed for it to work properly.

You can find more informations about cloud-init in our documentation.

Virtual Disk Size

The template’s Virtual Disk Size will determine the initial space available to the filesystem. Your template needs to have the ability to automatically adapt the filesystem disk size to the actual volume size in order to use the entire space at startup. E.g:

1. A template has a virtual disk size of 10 GB
2. The template is used to start an Instance with a disk size of 200 GB
3. Without the ability to scale automatically, the filesystem has only 10 GB available, and an extra non-partitioned and non-used space of 190 GB
4. You will still be invoiced for the full volume size, alas 200 GB

This ability is enabled through cloud-init. You can of course adapt your filesystem partitions manually, but its important to keep the concept in mind as it could have unexpected results.

Register a Custom Template

Once your template image is ready you must host it on a publicly accessible HTTPS service such as Exoscale Object Storage, as you will need to indicate an URL pointing to it during template registration.

You can register a template using the exo CLI, the API, or our web application in the Templates section. The following informations are required to register a template:

• The template name
• The template image file checksum (MD5), to ensure import integrity
• The template location (public url to retrieve the template)

Optionally, the following properties can also be set:

• A template description
• Whether the template allows user password reset
• Whether the template allows a SSH key to be copied during Instance creation
• A username: this is used to better integrate with Exoscale tools, as the Instance details view in the web application or the CLI. Shortcuts and commands to connect to the machine will be correctly displayed, while in the absence of this data they will not work or be incorrect.
• A template boot-mode (legacy|uefi)

Note: a Custom Template is registered per zone: if you want to use it in multiple zones, you have to repeat this step in the zones you’re interested in.

This is what a template registration looks like in the CLI:

$ exo compute instance-template register   \
    my-custom-template                     \
    https://example.net/my-template.qcow2  \
    15dc21cc9505a68cc0380a9a66654536       \
    --zone de-fra-1                        \
    --description "My custom template"     \
    --username "foo"

You can run the exo compute instance-template --help command for more information on commands and options.

Once your custom template is registered you can use it to deploy an Instance with all Exoscale tools, would that be our web application, CLI, API or 3rd party integration.

From a Compute instance Snapshot

In addition of building a custom template from scratch, is it possible to export a Compute instance volume snapshot and register the exported file as you would do with a manually created disk image:

$ SNAPSHOT_ID=ce295d39-421e-49c4-81f7-9890c3db3600
$ TEMPLATE_ID=$(exo compute instance snapshot show --output-template {{.ID}} $SNAPSHOT_ID)
$ BOOTMODE=$(exo compute instance-template show --output-template {{.BootMode}} ${TEMPLATE_ID})
$ USERNAME=$(exo compute instance-template show --output-template {{.DefaultUser}} ${TEMPLATE_ID})
$ exo compute instance-template register \
    my-template \
    --zone de-fra-1 \
    --from-snapshot $SNAPSHOT_ID \
    --description "A template registered from a snapshot" \
    --boot-mode $BOOTMODE \
    --username $USERNAME
 ✔ Registering template "my-template"... 11m21s
┼──────────────────┼──────────────────────────────────────┼
│     TEMPLATE     │                                      │
┼──────────────────┼──────────────────────────────────────┼
│ ID               │ 0a7bfba5-9854-479b-8095-676ca73bcfcd │
│ Name             │ my-template                          │
│ Description      │ A template registered from a snapshot│
│ Family           │ other (64-bit)                       │
│ Creation Date    │ 2021-09-17 13:17:46 +0000 UTC        │
│ Visibility       │ private                              │
│ Size             │ 10 GiB                               │
│ Version          │                                      │
│ Build            │                                      │
│ Default User     │ centos                               │
│ SSH key enabled  │ true                                 │
│ Password enabled │ true                                 │
│ Boot Mode        │ legacy                               │
│ Checksum         │ 33d592a033bfe0aefafafeb0834d37d9     │
┼──────────────────┼──────────────────────────────────────┼

You can check this blog post for more details.

Based on an ISO File

• Create a Linux instance on Exoscale Portal

• Install KVM, virt-manager and all necessary packages to configure a virtual instance.

• Download your ISO file on your instance

• Connect to your instance using -Y option

• Make sure to add your user to the libvirt group

• Now that everything is set, you can start creating a new virtual machine (graphically)

virt-manager
Create new VM
Local browse for iso file
Begin Installation

Refer to create virtual machines in KVM using virt manager

• Once installation is finished, an image will be created (.qcow2 file)

• Resize the image

qemu-img convert -C -O qcow2 -p source.qcow2 target.qcow2

• Calculate md5 checksum for registration

• Refer to Register a Custom Template (previous section)

Limitations

• Custom Templates actively used by an instance cannot be deleted.
• Compute instances that run a Custom Template cannot be moved from an Organization to another, as Custom Templates are Organization-specific.
• Templates not using cloud-init will not integrate entirely with the Exoscale experience, and will require some manual handling. See the cloud-init section for more details.