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

Creating Custom Templates is a 2-step process: create a template image (i.e. a disk image), then register it as a template on Exoscale.

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 and 100 GB. (This may differ from the actual file size, but the QCOW2 format must be in 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

Build a template image

To create a template image, we strongly recommend using Packer. Although Exoscale is not (yet) supported natively as a builder, you can use the QEMU builder to create template images.

A dedicated Exoscale Import Post-Processor allows you to automate the image registration on Exoscale as a last step of a packer build.

We provide Packer configuration examples in this Git repository to help you get started.

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

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.

cloud-init version < 19.3

The Exoscale datasource is only available for cloud-init version 19.3 or later. In case the 19.3 version is not yet available on your platform of choice, please use the following legacy configuration instead:

yaml datasource_list: - Cloudstack

Please note that the legacy datasource suffers from some known problems that might prevent some Exoscale features from working as intended.

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 actually use the entire space at startup. E.g:

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

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)

Note

If the from-snapshot flag is used, the url and checksum flags are no longer required.

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 zone list
...
35eb7739-d19e-45f7-a581-4687c54d6d02 │ de-fra-1
...

$ exo vm template register my-custom-template  \
  --checksum 15dc21cc9505a68cc0380a9a66654536  \
  --description "my custom template"           \
  --url http://public-url/template.qcow2       \
  --username "foo"                             \
  --zone de-fra-1                              \

You can run exo vm template --help for full details and options. Among other options it is if course possible to:

- **list your templates**  
  `exo vm template list --mine`

- **delete a template**  
  `exo vm template delete <template uuid>`

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 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:

$ exo vm template register my-template \
    --from-snapshot ce295d39-421e-49c4-81f7-9890c3db3600 \
    --description "A template registered from a snapshot" \
    --zone de-fra-1 \
    --username alice
Exporting snapshot "ce295d39-421e-49c4-81f7-9890c3db3600". success
Registering the template.................................. success
┼───────────────┼──────────────────────────────────────┼
│   TEMPLATE    │                                      │
┼───────────────┼──────────────────────────────────────┼
│ ID            │ 0a7bfba5-9854-479b-8095-676ca73bcfcd │
│ Name          │ my-template                          │
│ OS Type       │ Other (64-bit)                       │
│ Creation Date │ 2020-05-04T14:38:38Z                 │
│ Zone          │ de-fra-1                             │
│ Disk Size     │ 10 GiB                               │
│ Username      │ alice                                │
│ Password?     │ true                                 │
│ Boot Mode     │ legacy                               │
┼───────────────┼──────────────────────────────────────┼

Limitations

  • 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.