Lab file: template and source

This chapter is the field-by-field reference for the template {} block and its required source {} child. A template block describes how to build a sealed base image for the store; Templates and the store explains the build flow and vmlab template the verbs that run it. Template blocks live at the top level of a vmlab.wcl, beside a lab {} or in a file of their own with no lab at all. `vmlab template build reads ./vmlab.wcl unless --file` names another.

template {}

One buildable template. The build creates a working disk from the source, boots it with the hardware declared here, runs the provisions and playbooks, shuts the VM down and seals the disk into the store under <arch>/<name>/<version>/. The hardware fields are recorded in the template's metadata and become the inheritance layer for every VM cloned from it.

template "<name>" {
  arch        = "x86_64"
  version     = "24.04"
  registry    = "ghcr.io/owner/ubuntu-24.04"
  profile     = "linux-modern"
  cpus        = 2
  memory      = 4GiB
  disk        = 20GiB
  display     = "virtio-vga"
  cpu_model   = "pentium3"
  accel       = "tcg"
  firmware    = "ovmf"
  tpm         = false
  secure_boot = false
  nested      = false
  gui         = false
  qemu_args   = []
  first_boot  = "scripts/first-boot.ws"
  agent       = true
  source "…"  { … }
  gpu         { … }
  media       { … }
  provision "…" { … }
  playbook "…"  { … }
  nic         { … }
  disk "…"    { … }
  variant "…" { … }
}

media, provision, playbook, nic, disk and gpu are the same blocks a vm carries; see vm and its children.

The build VM's GPU

A gpu {} on a template or a variant gives the build VM a GPU and nothing else. Validation checks it as a lab VM's, passthrough included. At the build boot the lab daemon picks the host GPU as it does for a lab VM: the host_gpu named, or the host's default, with its render node, the Vulkan loader filter, the PCI-filter layer and the host config's qemu_binary and qemu_env. A host_gpu this host does not declare warns and falls back to the default. The build log names the pick as host_gpu=<name>, and the build VM's qemu.log header shows the argv and environment it produced.

The block is never recorded in the template's metadata: a clone's GPU is the lab's choice, so a clone that declares no gpu {} boots on the profile's plain display. Use it when an install only completes on a working paravirtual GPU, such as a Windows GPU driver package that verifies its kernel driver started, and leave display alone.

Versions and the registry

The declared version is a fixed prefix naming the upstream identity, such as an OS release. Each build appends a counter: the stored version is <version>.<N>, where N is one higher than the highest existing build with that prefix, or 0 for the first. When registry is set the existing builds are read from its tags, so the counter continues across machines; otherwise the local store decides. Changing the prefix restarts the counter at .0. vmlab template build --version pins an explicit version instead. registry is also the repository vmlab template push publishes to; see Distributing templates over registries.

The first-boot script and the agent

first_boot is read at build time and baked into the template's metadata, so a clone runs it on its first start without the lab needing the file. It runs before the VM turns ready. With agent = true the build waits for the guest-installed agent's handshake before sealing and records the agent version in the metadata. With agent = false, or on a profile with no agent channel, the check is skipped and the build log says so.

Validation

• arch is one of the known architectures: x86_64, x86, aarch64, riscv64, loongarch64, s390x, ppc64.
• version is non-empty, and no other template in the file has the same arch, name and version.
• profile, if set, names a known profile.
• A scratch source requires disk.
• first_boot and every provision script exist under the template's root and compile.
• A playbook on a template whose arch is not x86_64 is rejected.
• Every media and disk source folder exists.
• Variant names match [a-z0-9][a-z0-9-]{0,31}, are not base, and do not repeat; exactly one variant sets default = true, unless there is only one.

// Ubuntu Server 24.04 template (PRD §6.1). The installer ISO is downloaded
// and sha256-verified into the artefact cache; cloudinit/ is packed into a
// CIDATA ISO that subiquity picks up as a NoCloud autoinstall source. The
// provision script answers the autoinstall confirmation and waits for the
// installer to power the VM off. Build with:
//
//   vmlab template build        (run from this directory)

import <vmlab.wcl>

template "ubuntu-24.04" {
  arch    = "x86_64"
  version = "24.04.4"
  profile = "linux-modern"
  cpus    = 2
  memory  = 4GiB
  disk    = 20GiB

  source "iso" {
    url    = "https://releases.ubuntu.com/24.04/ubuntu-24.04.4-live-server-amd64.iso"
    sha256 = "e907d92eeec9df64163a7e454cbc8d7755e8ddc7ed42f99dbc80c40f1a138433"
  }

  media { kind = "iso" from = "./cloudinit/" label = "CIDATA" }
  nic { nat = true }

  provision "scripts/install.ws" { }
}

source {}

What the build starts from. The inline label is the kind, and the kind decides which fields apply. Exactly one source {} per template; the schema rejects a template without one.

source "iso"      { path = "./installer.iso" }
source "iso"      { url = "https://…/installer.iso" sha256 = "…" }
source "qcow2"    { path = "./base.qcow2" }
source "template" { from = "x86_64/ubuntu-24.04@24.04.4" }
source "scratch"  { }

The four kinds:

• iso: an installer ISO. The build boots it with the attached media and lets the provision script drive the installer. A remote artefact is downloaded to the cache and verified against sha256 before use.
• qcow2: an existing disk image, imported as the base.
• template: a layered build. An existing store template is the base, more provisioning runs, and the result seals as a new template. from must be a local store reference; a registry reference or scratch is rejected here. On a source with variants, no # seeds from its default variant, #<variant> from that variant, and #base from its base; the build boot runs the first-boot script of what was selected, and none for #base. The selected disk and everything beneath it are flattened into the working disk.
• scratch: a blank disk of the template's disk size. The attached installer media and provision script do everything.

Validation requires exactly one of path and url for iso and qcow2, sha256 whenever url is set, a path file that exists, and a from template that is in the store. An unknown kind is rejected.

variant {}

One variant of the template: a named, sealed disk state built on the base by booting an overlay on it and running the variant's own steps. A template with variants is referenced as <arch>/<name>#<variant>, and a reference without # selects the default variant; see Templates and the store. The motivating case is Windows: the base is installed and updated but not generalized, and each variant generalizes after its own changes.

template "windows-11" {
  …base build: source, provisions ending in a clean shutdown, no sysprep…
  first_boot = "scripts/firstboot.ws"

  variant "standard" {
    default = true
    provision "scripts/generalize.ws" { }
  }
  variant "win3d" {
    description = "GPU driver installed"
    secure_boot = false
    gpu { mode = "vulkan" }          // the build VM only; host_gpu = "AMD1" to pin
    provision "scripts/win3d-setup.ws" { }
    provision "scripts/generalize.ws" { }
  }
}

The hardware fields override what the base recorded, field by field, for the variant's build boot and for every clone of the variant; a field the variant leaves out follows the base. secure_boot = false on a variant of a Secure Boot base boots its build, and its clones, on the firmware without Secure Boot. gpu {} is the exception: it reaches the variant's build boot and never its clones.

How a variant builds

vmlab template build seals the base first. On a template with variants the base embeds no first-boot script: the template's first_boot is each variant's to inherit, and a variant's own first_boot replaces it. Then each variant builds, the default first and the rest in file order. A variant build creates an overlay on the sealed base, boots it on the variant's hardware, waits for the agent, runs the variant's provisions and playbooks, and shuts down gracefully. It runs no first-boot script: the base was never generalized, so there is nothing to specialize until a clone of the finished variant starts. The overlay is then pointed at its base by the relative path ../../disk.qcow2, hashed, and installed with its metadata under the store lock.

A failed variant stops the build; the base and every variant installed before it stay installed, and nothing of the failed one is left behind. vmlab template build <name> --variant <v> builds or rebuilds just that variant onto the installed version. A rebuild is refused while a machine's clone is backed by the variant: destroy those machines first.