Cannot create an instance template from a running or suspended instance; only an undocumented guest-side trigger works

[garysassano]

Environment

• Unikraft CLI 0.4.2 (linux/amd64)
• Metro: fra
• Image: python:3.13-alpine based, built via unikraft build

Summary

The documented way to turn an instance into a template fails in every instance state I could reach. The only method that actually works — and that captures live memory — is a write from inside the guest that is not mentioned anywhere in the CLI help.

Steps to reproduce

1. Start an instance:

   unikraft run --metro fra --name tf-a --image <your-image> -p 443:8080/http+tls -m 512MiB
   

2. Try the form shown in the docs, which pass a name:

   $ unikraft instances template create tf-a --name my-template
   error: unknown flag --name, did you mean "--save"?
   

3. Try without the flag, against the running instance:

   $ unikraft instances template create tf-a
   error: failed on "fra" client: failed to create template for tf-a:
   request error: Cannot template instance in running state
   

4. The CLI help says "Convert a stopped instance into a template", so suspend it first:

   $ unikraft instances suspend tf-a
   ($ unikraft instances get tf-a -f state  ->  stopped)
   
   $ unikraft instances template create tf-a
   error: failed on "fra" client: failed to create template for tf-a:
   request error: Failed to patch: snapshot present
   

Running is rejected because it is running. Suspended is rejected because suspending attached a snapshot. There is no state in between.

What does work

Writing to a path inside the guest converts the VM into a template and preserves live process memory:

open("/uk/libukp/template_instance", "w").write("1")

The guest is suspended part-way through the write, so the request never returns and the instance disappears from unikraft instances list, appearing in unikraft instances template list instead.

This is genuinely impressive — a clone of the resulting template resumes the Python interpreter mid-flight with a 150k-element list and a seeded RNG value intact, booting in ~26-30ms against ~105ms cold. But this trigger appears in one older documentation page and nowhere in unikraft instances template create --help.

Expected

Either instances template create works against some reachable instance state, or its help text points at the guest-side trigger as the supported mechanism.

Actual

Every documented path is a dead end; the working path is undiscoverable from the CLI.

Impact

This is the entry point to the platform's headline capability. I only found the working mechanism by running os.listdir("/uk") from inside a guest.

[garysassano]

Related: #467 is a resource-lifecycle consequence of the same guest-side self-templating mechanism described here — the service group is not reclaimed when an instance converts itself into a template. Filed separately because the fixes land in different places, but they were found in one session and share a reproduction path.