Exclusive Access · Invitation Only

Templates and Clones

A template is a copy of a stopped machine's boot disk that new machines can start from. A clone is a new machine made from a template, or from a stopped machine. The operator makes templates and clones in the console, on the command line or over the API. Tenants cannot reach these routes.

Part of Compute, in early access. Templates and clones need a licence that includes Compute and is not frozen.

Making a template

Stop the machine, then make its boot disk into a template. In the console, open the machine's Summary tab and, in its Copies card, choose Make a template. Give the template a name, and tick Let other tenants start machines from it to share it. The button is off while the machine runs, and says why.

On the command line:

sudo cenvero-str-ctl vm stop vm-3f9a1c2e
sudo cenvero-str-ctl vm template vm-3f9a1c2e --name almalinux-9-web

The answer names the template and the task that makes it. Follow the task with task log <task> --follow. Over the API, POST /api/v1/vms/{id}/templates takes {"name", "shared"}, and shared may be left out. The answer is 202 with the template and its task.

What the node does:

  • It copies the machine's boot disk into its image store, as a copy that depends on nothing else. Later snapshots and backups of the machine cannot change the template, and the template keeps working when the machine is deleted.
  • It checks the copy and records its SHA-256 and size.
  • It leaves the machine as it was: its disk, its data volumes and its settings do not change.

A machine whose boot disk is on a block pool makes a template the same way. The template is a copy in the node's image store, whichever pool the machine is on.

While the copy is made, the template is listed with the state making, and the machine cannot start. Each template then reads ready, or failed when the copy could not be finished. A copy that a restart of the node interrupts is marked failed too: delete it and make it again.

Two refusals are worth knowing:

  • A running machine cannot be made into a template: "this machine is running; stop it first".
  • A suspended tenant's machines cannot be made into templates: "this tenant is suspended: its machines cannot start, be cloned or be made into templates".

Who may use a template

A template belongs to the tenant whose machine it was made from, or to the operator when the machine was the operator's own. Only that owner's machines can be made from it, unless it is shared.

  • Sharing is set at creation with --shared, or afterwards on the Images page of the node, where a ready template has Share with other tenants (and Stop sharing takes it back). Over the API, PUT /api/v1/images/{id} with {"shared": true} (or false to stop sharing) answers 200 with the image. A template is the only image with a sharing setting: a base image is usable by every machine.
  • A shared template lets other tenants' machines start from it, and those machines read the template's whole content: its data, its files and anything else on the disk it was made from. Share a template only with that in mind.
  • Stop sharing is refused while another tenant's machine starts from the template. The answer says how many: "1 machine(s) of other tenants start from this template: delete them before you stop sharing it, or give each a full clone and delete the original". To stop sharing, delete those machines first, or give each one a full clone and delete the original. A full clone copies the whole disk, so the copy depends on nothing else. Then stop sharing again. Machines that belong to the operator are not counted, since the operator already holds the node's disks.
  • A machine that may not use a template is refused with "this template belongs to another tenant; ask an administrator to mark it shared".
  • A change to sharing is recorded as an event, and in the audit log. If the change cannot be recorded, nothing changes, and the answer says so: "the sharing change could not be recorded, so nothing changed: try again".

Deleting a template

A template can be deleted when no machine is made from it. While a machine uses it, the delete is refused, and the answer names the machine. A template that is still being made cannot be deleted either: wait for it to finish, or for it to fail.

Cloning

There are two kinds of clone. Both give the new machine its own identity.

A linked clone

A linked clone is a machine created from a template, as from any image. In the console, choose the template as the image in the create wizard. On the command line:

sudo cenvero-str-ctl vm create --name web-02 --tenant t-acme --image img-8c2d6a10 \
  --vcpus 2 --memory 2048 --network net-acme-web

Its boot disk starts from the template and keeps only its own changes, so it starts at once and takes little space at first. The template cannot be deleted while a clone uses it.

On a block pool, a template is copied to the pool once, the first time a machine is made there from it. Every later machine on that pool is a linked clone of that copy. The pools are described on Storage pools.

A full clone

A full clone copies a stopped machine's boot disk into a new machine that stands on its own. The source must be stopped. In the console, its Copies card has Clone, which asks for the new machine's Name and its Network. On the command line:

sudo cenvero-str-ctl vm clone vm-3f9a1c2e --name web-02 --network net-acme-web \
  --hostname web-02 --tenant t-acme

--network is repeated for each network the clone needs. --hostname defaults to the clone's name, and --tenant names the tenant the clone belongs to; it defaults to the source's tenant.

Over the API, POST /api/v1/vms/{id}/clone takes {"name", "networks", "hostname", "tenant_id"}. Each entry in networks is {"network_id"}, with an "ip" when you want one. The answer is 202 with the new machine and its task. A source that runs is refused with "this machine cannot be cloned while it runs: stop it first".

A clone's boot disk can be kept on a block pool. The copy can go from a directory pool to a block pool, from a block pool to a directory pool, or from one block pool to another. Over the API, pool names the pool the clone's boot disk is kept on. On the command line, vm clone --pool does the same. The default pool is used when it is left out. Storage pools describes the kinds of pool.

  • Only the boot disk is copied. The source's data volumes stay with the source.
  • The clone gets its own machine id, its own UUID and domain name, its own MAC addresses on the networks you name, and its own cloud-init instance. Its first boot is a first boot, so cloud-init configures it.
  • The clone is not protected, even when its source is.
  • Like any created machine, a clone starts when it is ready.
  • A clone counts against the tenant's machine limit, and a clone over the limit is refused.

The guest's own identity

A clone's guest identity, such as its SSH host keys and the machine id inside the guest, comes from the disk's contents. Cloud images regenerate those on their first boot, so most clones are safe to start. Windows needs its own preparation before a machine is made into a template, and the node does not do that for you.

Over the API

MethodPathPrivilegeAnswer
POST/api/v1/vms/{id}/templatesImage.Allocate and VM.Audit on the machine202 with the template and its task; 409 while the machine runs
PUT/api/v1/images/{id}Image.Allocate200 with the image; {"shared": true or false}. 409 while another tenant's machine starts from the template, when stopping sharing; 503 when the change cannot be recorded
POST/api/v1/vms/{id}/cloneVM.Allocate on the machine202 with the new machine and its task; 409 while the source runs

Every route here needs a licence that includes Compute and is not frozen. Reading the templates and the catalogue needs Image.Audit.

See also

↓ This page as JSON ↓ All documentation as JSON