Skip to main content

Instancetypes and preferences

Modelled on KubeVirt's instancetypes and preferences. Instead of repeating vcpus, memory_mib and device defaults in every VM spec, name them once and reference them at create time.

  • An instancetype is a named, versioned size class: vCPUs, memory, and optionally hotplug ceilings, hugepages, a CPU model and network/block limits.
  • A preference is a named bundle of device and firmware defaults: disk bus, NIC model, Secure Boot, TPM, firmware path.

Using them​

fluxctl instancetype ls
fluxctl create --spec web.json --instancetype large --preference linux

or in the create body (POST /v1/vms, fluxctl create --spec, fluxctl vm-spec check):

{"name": "web-1", "backend": "qemu", "image": "/var/lib/fluxvm/images/debian.qcow2",
"instancetype": "large:1", "preference": "linux"}

instancetype is name (the latest version) or name:version. preference is a name.

Resolution rules​

instancetypepreference
Roleowns the fields it definessupplies defaults
Spec sets the same field400, naming every clashthe spec wins; recorded as skipped

{"instancetype": "large", "vcpus": 2} fails with spec sets `vcpus` but instancetype large:1 defines it; remove it from the spec, or drop `instancetype` - as in KubeVirt, a size class and a hand-set size are two answers to one question. Everything else in the spec (image, network, cloud-init, ...) is untouched.

Snapshot semantics​

Resolution writes the values into the VM's own spec, so later edits or deletes of a class never change an existing VM, and a restart or recovery uses the same numbers. What was resolved is also kept with the VM:

  • GET /v1/vms/{id}/instancetype (the file <workspace>/instancetype.json): the full class (name, version, spec) as it was, the spec keys that were applied, and the settings skipped with the reason.
  • labels fluxvm.io/instancetype=large:1 and fluxvm.io/preference=linux, so fluxctl list -l fluxvm.io/instancetype=large:1 finds them.
  • the create response carries the same snapshot as instancetype_snapshot.

What each field does​

Instancetype spec:

fieldVM spec keynote
vcpus, memory_mibvcpus, memory_mibrequired
max_vcpus, max_memory_mibsamehotplug ceilings
hugepageshugepages
cpu_modelcpu_templateFirecracker only; other backends have no per-VM CPU model, so it is recorded as skipped
limits.net_mbit_limit, net_pps_limit, blk_mbit_limit, blk_ops_limitsame

Preference spec:

fieldVM spec keynote
disk_busroot_disk_io.busonly virtio-blk applies to the root disk (it is always virtio-blk); scsi and vhost-user-blk are recorded as skipped
nic_model-not applied yet: the VM spec has no NIC model setting; recorded as skipped
secure_boot, tpm, firmwaresame

Versions and built-ins​

Classes are stored in <state_dir>/instancetypes.json and <state_dir>/preferences.json, next to vm-templates.json. fluxctl instancetype create web --vcpus 2 --memory-mib 4096 stores web:1; creating web again stores web:2, which an unversioned reference then picks. --spec-version N --replace overwrites version N.

Built in (version 1): small (1 vCPU, 2 GiB), medium (2, 4 GiB), large (4, 8 GiB), memory-optimised (4, 32 GiB); preferences linux (virtio disk and NIC) and windows (virtio disk, e1000e NIC, Secure Boot, TPM). Built-ins cannot be deleted but can be overridden: store a class of the same name and version with --replace, or a new version of the name to make it the default for unversioned references.

CLI and REST​

fluxctl instancetype ls | get NAME[:VER] | create NAME --vcpus N --memory-mib M [--spec-version V] [--max-vcpus ..] [--hugepages true] [--cpu-model ..] [--net-mbit-limit ..] [--replace] | rm NAME[:VER]
fluxctl preference ls | get NAME | create NAME [--disk-bus virtio-blk] [--nic-model ..] [--secure-boot true] [--tpm true] [--firmware PATH] [--replace] | rm NAME

Against a daemon (--server, a context) these call the REST routes; otherwise they edit the local state_dir, like vm-template.

GET /v1/instancetypes GET /v1/preferences
POST /v1/instancetypes POST /v1/preferences
GET /v1/instancetypes/{name} GET /v1/preferences/{name} # name or name:version
DELETE /v1/instancetypes/{name} DELETE /v1/preferences/{name} # name (all stored versions) or name:version
GET /v1/vms/{id}/instancetype # the snapshot recorded at create

Reads are open to every role; writes need the admin role. A missing class is 404, an invalid or conflicting one 400.

Spec lint​

fluxctl vm-spec check accepts the two keys. It resolves them against the built-in classes (a class that exists only on the daemon's host is reported as info: it is checked at create time), reports clashes as errors, and lints the resolved spec.

Limits​

  • The selectors are handled in the create paths that take a full spec (POST /v1/vms, fluxctl create); vm-template instantiate and sandboxes do not resolve them.
  • Resolution is by the raw body: a key set to null counts as unset.